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 Tax amount
amount_detail.nontaxable Transaction is non taxable. Options are: Y = nontaxable or N = taxable
amount_detail.tip Tip amount 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
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"}' \

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}' \

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"


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.