POST /payrequests

POST /api/v2/paymentengine/payrequests

Starts a new payment request (transaction). This will cause the terminal to walk the customer through the payment processing screens:

  1. Swipe/dip/tap card.
  2. Choose credit/debit (if supported).
  3. Enter PIN (if necessary).
  4. Prompt for tip (if enabled).
  5. Approve amount.
  6. Capture signature (if enabled/supported).

A payment requestkey will be returned which can be used to track the customers progress on the terminal via GET /api/v2/paymentengine/payrequests/:requestkey:. When the process is complete, transaction details will be available.

Request Parameters

Variable Description
devicekey Device key. If device key is not specified, the device associated with current source key is used.
command Type of command being sent for the transaction. Options are: sale, authonly, or refund.
amount Transaction amount.

In addition to the basic request parameters above, any of the transaction API parameters can also be passed through.

Variable Description
amount_detail.subtotal Amount before discounts, shipping, duty and tax. This field is optional, but if sent the following MUST be true: amount = subtotal - discount + shipping + duty + tax
amount_detail.tax Tax amount
amount_detail.nontaxable Transaction is non taxable. Options are: Y = nontaxable or N = taxable
amount_detail.tip Tip amount
amount_detail.discount Discount amount
amount_detail.shipping Shipping amount
amount_detail.duty Duty amount (for level 3 processing)
invoice Invoice number (11 chars max)
ponum Customer's purchase order number (for corporate cards)
orderid Merchant assigned order ID
description Transaction description
comments Text only visible to merchant
terminal Terminal identifier (i.e. multilane)
table Restaurant table number
clerk Clerk/cashier/server name
billing_address.firstname
billing_address.lastname
billing_address.street
billing_address.street2
billing_address.city
billing_address.state
billing_address.postalcode
billing_address.country
billing_address.phone
shipping_address.firstname
shipping_address.lastname
shipping_address.street
shipping_address.street2
shipping_address.city
shipping_address.state
shipping_address.postalcode
shipping_address.country
shipping_address.phone
custid Merchant assigned customer ID
email Customer's email address
geolocation Latitude and longitude of transaction location.
software Software name and version (useful for troubleshooting).
ignore_duplicate Bypass duplicate detection/folding
save_card Save card and return token

Example Requests

Minimal Payment Request (curl)

curl --basic --user APIKEY:PINHASH \
 -X POST \
 -H "Content-Type: application/json" \
 -d '{"devicekey":"sa_1BTTI5Yys0G3gVQa6beYxM4K0hhjC","command":"cc:sale","amount":"8.88"}' \
 https://EBizCharge.com/api/v2/paymentengine/payrequests

Minimal Payment Request (json)

{
  "devicekey": "sa_YdebDV6I2q0MfWV8kPDvQkHEvUjpA",
  "command": "sale",
  "amount": "8.88"
}

Request Tokenization

In addition to processing the payment, a token will be generated that can be used for future payments.

curl --basic --user APIKEY:PINHASH \
-H "Content-Type: application/json" \
-d '{"devicekey":"sa_1BTTI5Yys0G3gVQa6beYxM4K0hhjC","command":"cc:sale","amount":"8.88","save_card":true}' \
https://EBizCharge.com/api/v2/paymentengine/payrequests

Response Variables

Variable Description
key Request key
expiration The expiration is the date/time the request will expire and no longer be valid.
status The status of the request.

Example Response

{
  "type": "request",
  "key": "pr_3mW7rstrdA0Sp32LW9MN3djCITAhx",
  "expiration": "2016-07-08 16:40:48",
  "status": "pending"
}

Errors

Errorcode Message Troubleshooting
21121 Unknown devicekey xxxxxxx Double check that the device key is valid. If the device status was still "waiting for device pairing," the request may have expired.