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

Parameter 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.

Optional Paramters

Parameter Description
timeout Time in seconds to wait for payment. Default is 180 seconds. See timeout handling below.
block_offline By default, the payment engine will wait for an offline payment terminal to connect and then start the transaction, up to the timeout time limit. If "block_offline" is set to true, the payment request will return an error right away.
ignore_duplicate Bypass duplicate detection/folding if it has been configured on the api key
save_card Save card and return token
manual_key If true, an option will be displayed to manually key the transaction.
prompt_tip Customer will be prompted to leave a tip.

Additional Transaction Parameters

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

Parameter 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)
amount_detail.enable_partialauth Include this parameter to authorize partial funds when the full amount is not available. For example, if the total is $10 and the customer only has $5 in their account, $5 will be authorized. If not included in request, partial authorization defaults to disabled.
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
customerid Merchant assigned customer ID
email Customer's email address
geolocation Latitude and longitude of transaction location.
software Software name and version (useful for troubleshooting).
custom_fields Optional fields for storing custom data.

Line Item Parameters

Parameter Description
lineitems Information for one or more individual line items that make up the order. Below are some of the line item details that can be included
sku Identification code for line item
name Name of line item
description Description of line item
cost cost of line item
qty Quantity (Required for Level 3 processing)
commoditycode Commodity code (only required for level 3 processing). See http://www.unspsc.org/ for valid list of codes. (Required for Level 3 processing)
discountamount Discount amount for line (Required for Level 3 processing)
discountrate Discount percentage for line (Required for Level 3 processing)
taxable Y = Taxable, N = Non-taxable (Required for Level 3 processing)
taxamount Amount of tax charge for line (if left blank will be calculated from taxrate) (Required for Level 3 processing)
taxclass The product's tax class (Required for Level 3 processing)
taxrate Tax rate for line (Required for Level 3 processing)
um Unit of measure (Required for Level 3 processing)

Custom Flow Parameters

If you are using an Ingenico device, you also have to option to customize the flow of a transaction. The current default flow for transactions is: amount, payment, result.

Parameter Description
custom_flow(comma delimited string) Allows you to customize the order in which each payment screen is displayed on the device.

Below are the parameters that can be included in the comma delimited string of the custom_flow parameter. Each of these parameters represents a screen which appears on the payment device. The payment and result screens are required. All others are optional.

Parameter Description
payment Payment taking screen (must come before result).
amount Optional confirmation of amount (must come before result).
result Displays the transaction result.
signature Signature capture (must come after result).
signature_required Signature capture. If the signature is cancelled, then the transaction will be cancelled (must come after result).

Timeout Handling

Once a payment request is initiated, the payment engine does not require any further input from the point of sale software to complete the payment process. This can lead to confusion and potentially duplicate transactions if the point of sale software does not correctly poll the payment request. Consider the follow sequence of events:

  1. User starts the transaction on the point of sale software.
  2. The point of sale software starts polling the status of the request, but is configured to give up after 1 minute.
  3. User takes longer than 1 minute to swipe card.
  4. Payment engine successfully processes transaction, approval is shown on terminal.
  5. User returns to point of sale and sees an error indicating that the request timed out.
  6. User repeats the process and this time swipes the card in under a minute.
  7. Duplicate transaction is run and two charges are now in the batch, despite the point of sale only acknowledging one.

By default the payment engine will wait for 3 minutes (180 seconds) for the user to swipe, dip or tap their card. This can be configured by passing the "timeout" parameter. To prevent the above, the point of sale software should continue to poll the payment request for the full amount of time set in the timeout. When timeout is exceeded, the payment request status will change to "timeout".

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://usaepay.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://usaepay.com/api/v2/paymentengine/payrequests

Other Parameter Examples

Line Items

{
    "lineitems": [
        {
            "sku": "The SKU",
            "name": "Prod Name",
            "description": "Prod Desc",
            "cost": "8.88",
            "qty": 1
        },
        {
            "sku": "The SKU 2",
            "name": "Prod Name 2",
            "description": "Prod Desc 2",
            "cost": "1.98",
            "qty": 2
        }
    ]
}

Custom Fields

{
    "custom_fields": {
        "1": "Custom value 1",
        "2": "Custom value 2",
        "3": "Custom value 3"
    }
}

Response Parameters

Parameter 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": "sent to device"
}

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.
21143 Request failed (Payment terminal battery too low) Charge the terminal before processing any more transactions. The terminal does not have the power to complete the transaction.
21144 Transaction request has timed out. Retry transaction, and complete before time out allotted (default is 180 seconds). Lengthen timeout parameter if necessary.
21145 Device is currently offline. Verify terminal is connected to payment engine and try again.
21146 Device is currently processing another transaction. Two requests were sent simultaneously. Wait until the first request is complete and try again.