Transactions

Endpoints for processing transactions

List Transactions

GET/transactions

Returns a paginated list of transactions for the authenticated merchant.

Filtering and Sorting

You can filter and sort the results using query parameters:

Available Filter/Sort Fields:

id - Transaction ID
timestamp - Transaction timestamp (UTC)
referenceId - Reference ID
orderNumber - Order number
invoiceNumber - Invoice number
type - Transaction type (Sale, Refund, Void, Auth, Capture, Chargeback)
amount - Transaction amount
status - Processing status; see the TransactionStatus schema

Transaction Status Definitions:

Created: Initial transaction state when created but not yet processed. This includes hosted payment form sessions that haven't been completed by the customer (the customer hasn't yet submitted payment) or hosted payment form sessions that were initiated but never finalized.

Pending: The session is waiting for customer input.

Submitted, Acknowledged, and Processing: The request is in flight. AwaitingSettlement waits for a bank-transfer outcome.

Completed: Processing finished for an approval or decline. transactionResponses[].responseCode tells you whether the payment was approved: only 1 and 2 are approvals. Failed means processing stopped because of a technical issue. Abandoned means the customer did not complete the flow before submission. Both states close the request.

This endpoint lists transaction records. A request can still be processing before its transaction record is available, so an empty list does not prove that no charge occurred. Check webhooks and query again before deciding whether to retry.

Deleted Token Behavior

When a token has been removed from the system, transactions that used that token will show:

dateDeleted timestamp in the paymentMethod object
Sensitive fields (maskedCardNumber, cardExpDate) will be removed for security
All other transaction data (amounts, authorization codes, card type) remains intact

Filter Operators:

Operator	Meaning
`==`	Equals
`!=`	Not equals
`>`	Greater than
`<`	Less than
`>=`	Greater than or equal to
`<=`	Less than or equal to
`@=`	Contains
`_=`	Starts with
`_-=`	Ends with
`!@=`	Does not Contains
`!_=`	Does not Starts with
`!_-=`	Does not Ends with
`@=*`	Case-insensitive string Contains
`_=*`	Case-insensitive string Starts with
`_-=*`	Case-insensitive string Ends with
`==*`	Case-insensitive string Equals
`!=*`	Case-insensitive string Not equals
`!@=*`	Case-insensitive string does not Contains
`!_=*`	Case-insensitive string does not Starts with

Special Filter Syntax:

Use | (pipe) for OR conditions: type==Sale|Capture
Use - prefix for descending sort: sorts=-timestamp

Examples:

Filter by timestamp range: ?filters=timestamp>=2025-05-21T01:00:00,timestamp<2025-05-22T01:00:00
Filter by type with OR: ?filters=type==Sale|Capture
Filter by status: ?filters=status==Completed
Sort by timestamp descending: ?sorts=-timestamp
Combined: ?filters=timestamp>=2025-05-27T04:00:00.000Z,type==Sale|Capture&sorts=-timestamp

Note: All transaction timestamps are in UTC.

Parameters

Name	In	Type	Description
`filters`	query	string	Filter criteria in the format: field==value,field!=value Multiple filters can be separated by commas. Use \| for OR conditions within a field. Available fields: id, timestamp, referenceId, orderNumber, invoiceNumber, type, amount, status
`sorts`	query	string	Sort criteria as comma-separated field names. Use - prefix for descending order. Available fields: id, timestamp, referenceId, orderNumber, invoiceNumber, type, amount, status
`page`	query	integer	Page number to retrieve (starts at 1). For example, if you have 100 records with 10 per page, page 2 gives you records 11 to 20.
`pageSize`	query	integer	Number of records per page. For example, if you have 100 records with 10 per page, page 2 gives you records 11 to 20.

Responses

200

A successful paginated response containing transactions

application/json · TransactionsListResponse

totalCount integer required

Total number of transactions that match the filter criteria

Example: 5

page integer required

The current page number (starts at 1)

Example: 1

pageSize integer required

Number of items per page

Example: 10

totalPages integer required

Total number of pages available

Example: 1

hasNextPage boolean required

True if there are more pages of results available

Example: false

hasPreviousPage boolean required

True if there are previous pages of results available

Example: false

items array of TransactionResponseObject required

Array of transactions for the current page

Child attributes

id string

Unique ID for this transaction.

Example: "trx_01J2F0EKHC7HY2R93C8ENBD1FG"

timestamp string (date-time)

Transaction timestamp in UTC

Example: "2025-05-27T18:49:31Z"

type string

Type of transaction.

Chargeback records an ACH payment that the payer's bank returned after the funds reached the merchant. It is a separate transaction: the original sale is not changed and stays approved. originalTransactionId holds the sale's ID, and the amount is the returned amount. Its approved outcome (resultCode 0, responseCode 1) means the chargeback took effect and the money went back to the payer. See Chargebacks.

Treat this list as open: ignore a value your integration does not recognize instead of rejecting the transaction.

Allowed: Sale, Auth, Capture, Refund, Void, Chargeback

Example: "Sale"

status TransactionStatus

The processing lifecycle, separate from approval or decline. Pending waits for customer input; Submitted, Acknowledged, and Processing are in flight; AwaitingSettlement waits for a bank transfer outcome. Completed can be approved or declined: inspect resultCode and transactionResponses[].responseCode. Failed means processing stopped because of a technical issue. Abandoned means the customer did not complete the flow before submission. Both states close the request.

Allowed: Unknown, Created, Pending, Submitted, Acknowledged, Processing, AwaitingSettlement, Completed, Failed, Abandoned

Example: "Completed"

accountHolder object

Account holder information associated with the transaction

Child attributes

id string required

Account holder ID assigned by the API.

Example: "aho_01JRZPRGFF4J2SZC3HMDBYEN2J"

externalId string required

External account holder ID assigned by your application.

Example: "usr_1234567890123"

contact object

Contact information for the account holder. Only returned for Card Not Present transactions.

Child attributes

name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "60606"

address string

Example: "300 S Wacker Dr"

state string

Example: "IL"

city string

Example: "Chicago"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

paymentMethod object

The payment method used for this transaction.

Child attributes

id string required

The unique identifier of the payment method. This ID has a prefix that makes it human-readable (pmt_trm_ for physical terminals, pmt_vrt_ for virtual card terminals, pmt_ach_ for virtual ACH terminals, pmt_tkn_ for tokens, which store a card or an ACH bank account), but applications should always use the type field to determine the payment method type rather than parsing this ID.

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

The date and time (UTC) when this payment method token was removed from the system using the Remove Token endpoint. This parameter will only be returned if the token was removed/deleted from the system.

This field will be present in three scenarios:

As part of a successful Remove Token endpoint response
In token.removed webhook notifications
In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

Physical - A physical payment terminal for Card Present transactions
Virtual - A hosted payment form/iframe for Card Not Present transactions
VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

Child attributes

name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "12345"

address string

Example: "123 Main St"

state string

Example: "NY"

city string

Example: "Anytown"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

cardType string

The type of card used for this transaction:

UNKNOWN - The card type is unknown
DEBIT - Debit Card
VISA - Visa Credit Card
MASTERCARD - MasterCard Credit Card
AMEX - American Express Credit Card
DINERS - Diners Club Credit Card
DISCOVER - Discover Credit Card
JCB - JCB Credit Card
UNIONPAY - UnionPay Credit Card
MAESTRO - Maestro Debit Card
GIFT - Gift Card
CASH - All-cash Transaction
EBT - Electronic Benefits Transfer Card
INTERAC - Interac (Canadian PIN-debit network), Card Present only
OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

For card tokens: Credit or Debit.
For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

invoiceNumber InvoiceNumber

An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.

max length 100

Example: "inv_1234567890123456"

orderNumber OrderNumber

An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.

max length 100

Example: "order_number_1234"

referenceId ReferenceIdForResponse

The reference ID for this transaction. This will either be the reference ID provided in the transaction request or, if no value was provided, a value generated automatically by the system. This reference ID can be used for processing captures and referenced refunds by including it in the originalReferenceId field of subsequent transactions.

max length 100

Example: "ref_s192i49i"

originalTransactionId string

The trx_ ID of the earlier transaction this one belongs to, when the link has been verified. Set on card-present captures and voids, card-present Interac refunds, ACH refunds once the gateway confirms the original sale, ACH chargebacks (the charged-back sale), and ACH resubmissions (the original sale).

Absent when there is no verified link. That includes card-not-present captures, refunds, and voids, other card-present refunds, and older transactions recorded before the link was stored. Do not treat an absent value as proof that the transaction has no original.

Example: "trx_01JWBPE27KHY2K4J7A13ATQ786"

resultCode ResultCode

Result codes:

0 - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)
1003 - The payment terminal is busy or unavailable. (If this error persists, the user may need to close and re-open the Payment Application on the terminal or restart the terminal)
1005 - The specified terminal could not be found.
1010 - The transaction request is pending to become transaction.
2014 - The payment method or card brand is not enabled for the merchant. resultText carries the message, such as ACH payments are not enabled for this merchant. or Visa cards are not enabled for this merchant. The transaction is Completed and failed; do not retry it with the same payment method.
3000 - An unexpected error occurred. Please try again.
3002 - The transaction could not be completed because the payment terminal could not find the related transaction.
3005 - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.
3006 - The transaction could not be completed because the payment terminal is low on battery.
3009 - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.
3010 - The transaction took too long and was cancelled by the application.
3011 - Invalid transaction request. Please consult the documentation for valid transaction requests.
3012 - Invalid transaction request. paymentMethodId is invalid.
3013 - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.
3014 - Invalid amount. Please try your transaction again with an amount greater than $0.
3020 - An unsupported transaction result was received.
4001 - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.
6800 - 3D Secure authentication was rejected by the issuer's ACS (card auth failed, security failure, stolen card, suspected fraud, etc.). Surfaced on declined CNP transactions when formConfig.enable3DSecure: true and the gateway reports a 3D Secure reason; other failures in a 3D Secure session use 6900-6902. See SDK Error Codes for guidance.
6801 - 3D Secure authentication could not be completed because of an upstream technical issue (ACS timeout, directory server unreachable). Retry later or, if merchant policy allows, retry with 3DS disabled.
6802 - The card is not enrolled in 3D Secure. Retry without 3DS only if merchant policy allows; approval is not guaranteed.
6900 - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText. See SDK Error Codes for guidance.
6901 - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision. See SDK Error Codes for guidance.
6902 - The gateway reported no failure but returned no payment token. See SDK Error Codes for guidance.
9998 - The system is not ready to process a transaction.
9999 - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.
1010 - The transaction request is pending customer interaction.
4100 - Cardholder verification is required. Follow threeDsChallenge.redirectUrl and reconcile the final transaction outcome before retrying.
55 - The customer cancelled the hosted payment attempt.

Allowed: 0, 55, 1003, 1005, 1010, 2014, 3000, 3002, 3005, 3006, 3009, 3010, 3011, 3012, 3013, 3014, 3020, 4001, 4100, 6800, 6801, 6802, 6900, 6901, 6902, 9998, 9999

Example: 0

resultText ResultText

A message describing the result code in more detail. On a stored transaction it is uppercase, such as APPROVED, DECLINED, or the gateway's reason, except for resultCode 2014, where it is the message in sentence case. Use it for display, not for branching.

Example: "APPROVED"

requestedAmount integer

The requested amount in minor units. Virtual tokenization uses 0; physical tokenization uses a 1-unit authorization.

Example: 1000

approvedAmount integer

The approved amount in minor units. This is 0 for a decline or an outcome that is still in flight. A terminal may adjust the amount, for example by adding a tip.

Example: 1000

balanceAmount integer

The balance that remains to be paid on the transaction. This amount is always an integer in the smallest denomination of the currency (e.g. cents for USD or CAD).

Example: 0

refundableAmount integer

The amount that can still be refunded against this sale or capture, in the smallest denomination of the currency. Normally available within seconds of approval. Absent for authorizations, refunds, voids, and declined transactions; it can also be absent briefly after a sale or capture is approved. Absence does not mean unlimited; it means this value is not yet available or not applicable. An ACH chargeback reduces it like a refund. 0 means fully refunded, voided, or charged back.

Example: 1000

transactionResponses array of object

Individual gateway responses, with receipts under each entry. The array can be empty while processing is incomplete.

Child attributes

responseCode ResponseCode

The outcome of the payment, and the field that tells you whether the transaction succeeded. The HTTP status, resultCode, and status do not. A transaction succeeded only when status is Completed and a transaction response has responseCode 1 or 2.

Outcomes:

Approved - 1, 2. For 2, only amountApproved was approved. On a Chargeback transaction, approved means the chargeback took effect: the money went back to the payer.
Declined - 10 to 18. The issuer or bank refused the payment. Do not retry with the same payment details.
Canceled - 54, 55. No money moved.
Pending - 57. The outcome is not final. Wait for the webhook or query the transaction again.
Unknown - 0. No specific code was reported. While status is not Completed, the outcome is not final. On a Completed transaction it is not an approval: read resultCode and resultText for the reason, for example 2014, 6901, or 6902.
Error - every other code. Processing failed for a technical or request reason.

See Transaction response codes.

Response codes:

0 - UNKNOWN
1 - APPROVED - Transaction was approved
2 - PARTIAL_APPROVED - Transaction was partially approved, but not for the full requested amount.
10 - DECLINED - Transaction was declined by the issuer or bank. For Card-Present, the transaction can also be declined offline by the terminal.
11 - INSUFFICIENT_FUNDS - Rejected due to insufficient funds in the account.
12 - CARD_EXPIRED - The card used for the transaction has expired.
13 - FRAUD_SUSPECTED - The transaction was flagged for potential fraud.
14 - INVALID_PAYMENT_INFO - The provided information is invalid (e.g.: card number).
15 - LIMIT_EXCEEDED - Rejected due to reaching a limit (e.g.: credit limit).
16 - VERIFICATION_REQUIRED - Additional customer verification is required for the transaction to proceed (e.g.: 3D Secure).
17 - AUTHENTICATION_FAILED - Rejected due to incorrect PIN or authentication failure.
18 - POLICY_VIOLATION - Rejected due to a violation of the payment gateway's terms of service or policies.
19 - BATCH_EMPTY - Indicates that the batch for processing is empty.
20 - RECORD_NOT_FOUND - Indicates that the requested record for a transaction was not found (e.g.: to VOID a reference).
21 - ALREADY_VOIDED - Indicates that the transaction has already been voided and cannot be processed again.
50 - NETWORK_ERROR - Rejected due to network or communication issues with the payment gateway.
51 - INVALID_ECR_PARAMETER - Payment Terminal or system-specific errors.
52 - NOT_SUPPORTED - Rejected because the requested operation is not supported.
53 - BUSY_OR_UNAVAILABLE - The Payment Terminal, Payment App or system is busy or unavailable.
54 - CANCELLED - Cancelled by the user or merchant.
55 - USER_CANCELLED - Specific to scenarios where the user cancels the transaction.
56 - TIMED_OUT_ON_USER_INPUT - Failed to complete the transaction in time.
57 - PENDING - The transaction is awaiting an asynchronous outcome.

Allowed: 0, 1, 2, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 50, 51, 52, 53, 54, 55, 56, 57

authCode string

The authorization code provided by the card issuer, confirming transaction approval.

Example: "123456"

amountApproved integer

The amount approved for this transaction response.

Example: 1000

approvedAmountBreakdown ApprovedAmountBreakdown

A breakdown of approvedAmount, where each amounts approved on the payment terminal are returned separately. Only returned on Sale, Auth and Capture transactions.

Child attributes

amountGoodsAndServices integer

The approved amount for goods and services.

Example: 900

tax integer

The approved tax amount.

Example: 100

cashback integer

The approved cashback amount.

Example: 0

tip integer

The approved tip amount.

Example: 0

paymentMethod object

The payment method used for this transaction.

Child attributes

id string required

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

This field will be present in three scenarios:

As part of a successful Remove Token endpoint response
In token.removed webhook notifications
In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

Physical - A physical payment terminal for Card Present transactions
Virtual - A hosted payment form/iframe for Card Not Present transactions
VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

cardType string

The type of card used for this transaction:

UNKNOWN - The card type is unknown
DEBIT - Debit Card
VISA - Visa Credit Card
MASTERCARD - MasterCard Credit Card
AMEX - American Express Credit Card
DINERS - Diners Club Credit Card
DISCOVER - Discover Credit Card
JCB - JCB Credit Card
UNIONPAY - UnionPay Credit Card
MAESTRO - Maestro Debit Card
GIFT - Gift Card
CASH - All-cash Transaction
EBT - Electronic Benefits Transfer Card
INTERAC - Interac (Canadian PIN-debit network), Card Present only
OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

For card tokens: Credit or Debit.
For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

cardType CardType

The type of card used for this transaction:

UNKNOWN - The card type is unknown
DEBIT - Debit Card
VISA - Visa Credit Card
MASTERCARD - MasterCard Credit Card
AMEX - American Express Credit Card
DINERS - Diners Club Credit Card
DISCOVER - Discover Credit Card
JCB - JCB Credit Card
UNIONPAY - UnionPay Credit Card
MAESTRO - Maestro Debit Card
GIFT - Gift Card
CASH - All-cash Transaction
EBT - Electronic Benefits Transfer Card
INTERAC - Interac (Canadian PIN-debit network), Card Present only
OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

avsResult AVSResult

The AVS (Address Verification Service) result. Typically returned on Card Not Present transactions.

A - Address matches, ZIP does not. The first five numerical characters contained in the address match those stored at the VIC or issuer's center. However, the ZIP code does not match.
E - Ineligible transaction.
N - Neither address nor ZIP matches. Neither the first five numerical characters contained in the address match with those stored at the VIC nor issuer's center nor the ZIP code match.
R - Retry (system unavailable or timed out).
S - Card type not supported. The card type for this transaction is not supported by AVS. AVS can verify addresses for Visa cards, MasterCard, proprietary cards, and private label transactions.
U - Address information unavailable.
G - Address information unavailable, International - Visa only, The address information was not available at the VIC or issuer's center.
W - Nine-digit ZIP match, address does not. The nine-digit Postal ZIP code matches that stored at the VIC or card issuer's centre. However, the first five numerical characters contained in the address do not match.
X - Exact match (nine digit ZIP and address). Both the nine-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
Y - Address and five-digit ZIP match. Both the five-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
Z - Five-digit ZIP matches, address does not. The five-digit Postal ZIP code matches that stored at the VIC or card issuer's centre.

NOTE: Transactions can still be authorized if the AVS responses are no match or failure. AVS responses are for merchant information only, and usually do not influence the overall Authorization result. This can vary based on the Issuing Bank.

Allowed: A, E, N, R, S, U, G, W, X, Y, Z

cvvResult CVVResult

The CVV verification result. Typically returned on Card Not Present transactions.

M - CVV Match
N - CVV No Match
P - Not Processed
S - CVV should be on the card but the merchant indicates it is not.
U - User is unregistered

NOTE: Transactions can still be authorized if the CVV responses are no match or failure. CVV responses are for merchant information only, and usually do not influence the overall Authorization result. This can vary based on the Issuing Bank.

Allowed: M, N, P, S, U

accountType string

The funding-source classification associated with the payment method used in this transaction.

For credit/debit cards: Credit or Debit. May be null when the classification is unavailable, including on older transactions.
For ACH/EFT bank accounts: Checking or Savings.

The immediate hosted ACH response uses lowercase checking or savings. Retrieved transaction responses normally use Checking or Savings.

Allowed: Credit, Debit, Checking, Savings, checking, savings

Example: "Credit"

hostResponseText string

A meaningful text explaining the response code from the host.

Example: "APPROVED 00"

receipt Receipt

Receipt lines for this transaction response. Card-present responses can contain printable receipt lines; other responses can return an empty lines array.

Child attributes

lines array of string required

The receipt lines.

sourceId string

Identifier of the session or other source that initiated the transaction. For an ACH chargeback, it is the chargeback's own trx_ ID, or the billing subscription ID when the charged-back sale was a subscription payment.

threeDs ThreeDsAuthentication

3D Secure (EMV 3DS2) authentication outcome. Populated on transactions initiated with formConfig.enable3DSecure: true. All fields (other than status) are optional - what the issuer returns depends on whether the transaction was frictionless, challenged, or declined.

Child attributes

status string

The authentication outcome to use in your integration. The other threeDs fields provide supporting authentication data.

Allowed: Authenticated, Attempted, NotAuthenticated, Failed, Unavailable, NotEnrolled

Example: "Authenticated"

cavv string

Cardholder Authentication Verification Value. Cryptographic proof that 3DS authentication was performed. Present on frictionless and challenge-completed transactions.

Example: "AAABBkgwVoRhY2tcYlZGAAAAAAA="

eci string

E-commerce Indicator. Indicates 3DS liability-shift status per card scheme:

02 / 05 - Fully authenticated (liability shift to issuer).
01 / 06 - Attempted authentication (partial liability shift).
00 / 07 - Not authenticated (no liability shift).

Example: "05"

xid string

3DS1 transaction identifier. Some issuers still return this under 3DS2 for backward compatibility.

Example: "MDAwMDAwMDAwMDAwMDAwMTM3MDI="

dsTransId string

Directory Server transaction ID (3DS2). Identifies the authentication associated with this card transaction.

Example: "b71a7d5d-cc38-4ce9-80c3-50a7d53271f7"

threeDReasonId string

Issuer-provided reason code when 3DS authentication failed. Populated only on declines. Use status to handle the outcome and threeDReason for the explanation.

Example: "10"

threeDReason string

Human-readable description matching threeDReasonId.

Example: "Stolen Card"

threeDsChallenge ThreeDsChallenge

Present when a token payment requires a cardholder challenge (resultCode: 4100).

Child attributes

redirectUrl string (uri) required

Hosted URL where the cardholder completes the challenge.

followUpToken string required

Opaque token identifying the pending challenge.

Transactions within timestamp range (UTC)

{
  "totalCount": 2,
  "page": 1,
  "pageSize": 10,
  "totalPages": 1,
  "hasNextPage": false,
  "hasPreviousPage": false,
  "items": [
    {
      "id": "trx_01JWBPE27KHY2K4J7A13ATQ786",
      "timestamp": "2025-05-22T17:00:50Z",
      "type": "Sale",
      "status": "Completed",
      "resultCode": 0,
      "resultText": "APPROVED",
      "referenceId": "ref_s192i49i",
      "orderNumber": "order_number_1234",
      "invoiceNumber": "inv_1234567890123456",
      "requestedAmount": 1000,
      "approvedAmount": 1000,
      "balanceAmount": 0,
      "refundableAmount": 1000,
      "accountHolder": {
        "id": "aho_01JRZPRGFF4J2SZC3HMDBYEN2J",
        "externalId": "usr_1234567890123",
        "contact": {
          "name": "John Doe",
          "countryCode": "US",
          "zipCode": "60606",
          "address": "300 S Wacker Dr",
          "state": "IL",
          "city": "Chicago"
        }
      },
      "paymentMethod": {
        "id": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
        "type": "Virtual",
        "currency": "USD",
        "description": "Online Checkout Iframe"
      },
      "transactionResponses": [
        {
          "authCode": "111890",
          "cardType": "VISA",
          "accountType": "Credit",
          "responseCode": 1,
          "hostResponseText": "APPROVED",
          "amountApproved": 1000,
          "avsResult": "Y",
          "cvvResult": "M",
          "paymentMethod": {
            "id": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J",
            "type": "Token",
            "currency": "USD",
            "billingContact": {
              "name": "John Doe",
              "countryCode": "US",
              "zipCode": "12345",
              "address": "123 Main St",
              "state": "NY",
              "city": "Anytown"
            },
            "description": "Token for John Doe's Visa",
            "cardType": "VISA",
            "maskedCardNumber": "4****1111",
            "cardExpDate": "1225"
          }
        }
      ]
    },
    {
      "id": "trx_01JWBNTQ6G0MJWVADFZVYMXPBF",
      "timestamp": "2025-05-22T19:22:47Z",
      "type": "Sale",
      "status": "Completed",
      "resultCode": 0,
      "resultText": "APPROVED",
      "referenceId": "ref_s192i49i",
      "orderNumber": "order_number_1234",
      "invoiceNumber": "inv_1234567890123456",
      "requestedAmount": 1000,
      "approvedAmount": 1000,
      "balanceAmount": 0,
      "refundableAmount": 1000,
      "accountHolder": {
        "id": "aho_01JRZPRGFF4J2SZC3HMDBYEN2J",
        "externalId": "usr_1234567890123",
        "contact": {
          "name": "John Doe",
          "countryCode": "US",
          "zipCode": "60606",
          "address": "300 S Wacker Dr",
          "state": "IL",
          "city": "Chicago"
        }
      },
      "paymentMethod": {
        "id": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J",
        "type": "Token",
        "currency": "USD",
        "description": "Token for John Doe's Visa"
      },
      "transactionResponses": [
        {
          "authCode": "111048",
          "cardType": "VISA",
          "accountType": "Credit",
          "responseCode": 1,
          "hostResponseText": "APPROVED",
          "amountApproved": 1000,
          "avsResult": "Y",
          "cvvResult": "M",
          "paymentMethod": {
            "id": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J",
            "type": "Token",
            "currency": "USD",
            "billingContact": {
              "name": "John Doe",
              "countryCode": "US",
              "zipCode": "12345",
              "address": "123 Main St",
              "state": "NY",
              "city": "Anytown"
            },
            "description": "Token for John Doe's Visa",
            "cardType": "VISA",
            "maskedCardNumber": "4****1111",
            "cardExpDate": "1225"
          }
        }
      ]
    }
  ]
}

Sale and Capture transactions with descending timestamp sort

{
  "totalCount": 2,
  "page": 1,
  "pageSize": 10,
  "totalPages": 1,
  "hasNextPage": false,
  "hasPreviousPage": false,
  "items": [
    {
      "id": "trx_01JWBNTQ6G0MJWVADFZVYMXPBF",
      "resultCode": 0,
      "resultText": "APPROVED",
      "referenceId": "ref_s192i49i",
      "orderNumber": "order_number_1234",
      "invoiceNumber": "inv_1234567890123456",
      "timestamp": "2025-05-27T18:59:31Z",
      "type": "Capture",
      "status": "Completed",
      "requestedAmount": 450,
      "approvedAmount": 450,
      "balanceAmount": 0,
      "accountHolder": {
        "id": "aho_01JRZPRGFF4J2SZC3HMDBYEN2J",
        "externalId": "usr_1234567890123",
        "contact": {
          "name": "John Doe",
          "countryCode": "US",
          "zipCode": "60606",
          "address": "300 S Wacker Dr",
          "state": "IL",
          "city": "Chicago"
        }
      },
      "paymentMethod": {
        "id": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J",
        "type": "Token",
        "currency": "USD",
        "description": "Token for John Doe's Visa"
      },
      "transactionResponses": [
        {
          "authCode": "111688",
          "cardType": "VISA",
          "accountType": "Credit",
          "responseCode": 1,
          "hostResponseText": "APPROVED",
          "amountApproved": 450,
          "avsResult": "Y",
          "cvvResult": "M",
          "paymentMethod": {
            "id": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J",
            "type": "Token",
            "currency": "USD",
            "description": "Token for John Doe's Visa",
            "billingContact": {
              "name": "John Doe",
              "countryCode": "US",
              "zipCode": "12345",
              "address": "123 Main St",
              "state": "NY",
              "city": "Anytown"
            },
            "cardType": "VISA",
            "maskedCardNumber": "4****5297",
            "cardExpDate": "1225"
          }
        }
      ]
    },
    {
      "id": "trx_01JWBPE27KHY2K4J7A13ATQ786",
      "resultCode": 0,
      "resultText": "APPROVED",
      "referenceId": "ref_s192i49i",
      "orderNumber": "order_number_1234",
      "invoiceNumber": "inv_1234567890123456",
      "timestamp": "2025-05-27T18:49:31Z",
      "type": "Sale",
      "status": "Completed",
      "requestedAmount": 1000,
      "approvedAmount": 1000,
      "balanceAmount": 0,
      "accountHolder": {
        "id": "aho_01JRZPRGFF4J2SZC3HMDBYEN2J",
        "externalId": "usr_1234567890123",
        "contact": {
          "name": "John Doe",
          "countryCode": "US",
          "zipCode": "60606",
          "address": "300 S Wacker Dr",
          "state": "IL",
          "city": "Chicago"
        }
      },
      "paymentMethod": {
        "id": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
        "type": "Virtual",
        "currency": "USD",
        "description": "Online Checkout Iframe"
      },
      "transactionResponses": [
        {
          "authCode": "111890",
          "cardType": "VISA",
          "accountType": "Credit",
          "responseCode": 1,
          "hostResponseText": "APPROVED",
          "amountApproved": 1000,
          "avsResult": "Y",
          "cvvResult": "M",
          "paymentMethod": {
            "id": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J",
            "type": "Token",
            "currency": "USD",
            "billingContact": {
              "name": "John Doe",
              "countryCode": "US",
              "zipCode": "12345",
              "address": "123 Main St",
              "state": "NY",
              "city": "Anytown"
            },
            "description": "Token for John Doe's Visa",
            "cardType": "VISA",
            "maskedCardNumber": "4****1111",
            "cardExpDate": "1225"
          }
        }
      ]
    }
  ]
}

401

Unauthorized response due to an invalid or missing API key.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Allowed: 0, 1000, 1001, 2000, 2010, 2011, 2012, 2013, 2014, 2020, 2021, 2100, 2101, 2102, 2103, 2105, 2201, 2202, 2900, 2901, 2902, 2903, 3000, 3201, 3202, 3203, 3204, 3205, 3299, 3400, 3401, 3501, 3502, 3503, 4000, 4001, 4002, 4003, 4004, 6000, 6001, 6100, 6101, 6102, 6103, 6200, 6201, 6202, 6203, 6300, 6301, 6400, 6500, 6501, 6600, 6700, 6701, 6800, 6801, 6802, 6900, 6901, 6902, 9000, 9999

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

UnauthorizedError

{
  "code": 1000,
  "status": "Rejected",
  "message": "API key cannot be empty",
  "traceId": "1-6838be96-74c62f8e2804352739e63476",
  "timestamp": "2025-05-29T20:07:50.4723483Z",
  "errorDetails": []
}

400

Invalid request or query parameters.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

Get Transaction

GET/transactions/{id}

Returns one transaction for the authenticated merchant. An unknown transaction or a transaction owned by another merchant returns 404.

Parameters

Name	In	Type	Description
`id` required	path	string	The transaction ID to retrieve. The transaction must belong to the merchant that owns the API key used for this request.

Responses

200

A successful response containing the transaction

application/json · TransactionResponseObject

id string

Unique ID for this transaction.

Example: "trx_01J2F0EKHC7HY2R93C8ENBD1FG"

timestamp string (date-time)

Transaction timestamp in UTC

Example: "2025-05-27T18:49:31Z"

type string

Type of transaction.

Treat this list as open: ignore a value your integration does not recognize instead of rejecting the transaction.

Allowed: Sale, Auth, Capture, Refund, Void, Chargeback

Example: "Sale"

status TransactionStatus

Allowed: Unknown, Created, Pending, Submitted, Acknowledged, Processing, AwaitingSettlement, Completed, Failed, Abandoned

Example: "Completed"

accountHolder object

Account holder information associated with the transaction

Child attributes

id string required

Account holder ID assigned by the API.

Example: "aho_01JRZPRGFF4J2SZC3HMDBYEN2J"

externalId string required

External account holder ID assigned by your application.

Example: "usr_1234567890123"

contact object

Contact information for the account holder. Only returned for Card Not Present transactions.

Child attributes

name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "60606"

address string

Example: "300 S Wacker Dr"

state string

Example: "IL"

city string

Example: "Chicago"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

paymentMethod object

The payment method used for this transaction.

Child attributes

id string required

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

This field will be present in three scenarios:

As part of a successful Remove Token endpoint response
In token.removed webhook notifications
In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

Physical - A physical payment terminal for Card Present transactions
Virtual - A hosted payment form/iframe for Card Not Present transactions
VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

Child attributes

name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "12345"

address string

Example: "123 Main St"

state string

Example: "NY"

city string

Example: "Anytown"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

cardType string

The type of card used for this transaction:

UNKNOWN - The card type is unknown
DEBIT - Debit Card
VISA - Visa Credit Card
MASTERCARD - MasterCard Credit Card
AMEX - American Express Credit Card
DINERS - Diners Club Credit Card
DISCOVER - Discover Credit Card
JCB - JCB Credit Card
UNIONPAY - UnionPay Credit Card
MAESTRO - Maestro Debit Card
GIFT - Gift Card
CASH - All-cash Transaction
EBT - Electronic Benefits Transfer Card
INTERAC - Interac (Canadian PIN-debit network), Card Present only
OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

For card tokens: Credit or Debit.
For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

invoiceNumber InvoiceNumber

An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.

max length 100

Example: "inv_1234567890123456"

orderNumber OrderNumber

An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.

max length 100

Example: "order_number_1234"

referenceId ReferenceIdForResponse

max length 100

Example: "ref_s192i49i"

originalTransactionId string

Example: "trx_01JWBPE27KHY2K4J7A13ATQ786"

resultCode ResultCode

Result codes:

0 - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)
1003 - The payment terminal is busy or unavailable. (If this error persists, the user may need to close and re-open the Payment Application on the terminal or restart the terminal)
1005 - The specified terminal could not be found.
1010 - The transaction request is pending to become transaction.
2014 - The payment method or card brand is not enabled for the merchant. resultText carries the message, such as ACH payments are not enabled for this merchant. or Visa cards are not enabled for this merchant. The transaction is Completed and failed; do not retry it with the same payment method.
3000 - An unexpected error occurred. Please try again.
3002 - The transaction could not be completed because the payment terminal could not find the related transaction.
3005 - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.
3006 - The transaction could not be completed because the payment terminal is low on battery.
3009 - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.
3010 - The transaction took too long and was cancelled by the application.
3011 - Invalid transaction request. Please consult the documentation for valid transaction requests.
3012 - Invalid transaction request. paymentMethodId is invalid.
3013 - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.
3014 - Invalid amount. Please try your transaction again with an amount greater than $0.
3020 - An unsupported transaction result was received.
4001 - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.
6800 - 3D Secure authentication was rejected by the issuer's ACS (card auth failed, security failure, stolen card, suspected fraud, etc.). Surfaced on declined CNP transactions when formConfig.enable3DSecure: true and the gateway reports a 3D Secure reason; other failures in a 3D Secure session use 6900-6902. See SDK Error Codes for guidance.
6801 - 3D Secure authentication could not be completed because of an upstream technical issue (ACS timeout, directory server unreachable). Retry later or, if merchant policy allows, retry with 3DS disabled.
6802 - The card is not enrolled in 3D Secure. Retry without 3DS only if merchant policy allows; approval is not guaranteed.
6900 - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText. See SDK Error Codes for guidance.
6901 - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision. See SDK Error Codes for guidance.
6902 - The gateway reported no failure but returned no payment token. See SDK Error Codes for guidance.
9998 - The system is not ready to process a transaction.
9999 - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.
1010 - The transaction request is pending customer interaction.
4100 - Cardholder verification is required. Follow threeDsChallenge.redirectUrl and reconcile the final transaction outcome before retrying.
55 - The customer cancelled the hosted payment attempt.

Example: 0

resultText ResultText

Example: "APPROVED"

requestedAmount integer

The requested amount in minor units. Virtual tokenization uses 0; physical tokenization uses a 1-unit authorization.

Example: 1000

approvedAmount integer

The approved amount in minor units. This is 0 for a decline or an outcome that is still in flight. A terminal may adjust the amount, for example by adding a tip.

Example: 1000

balanceAmount integer

The balance that remains to be paid on the transaction. This amount is always an integer in the smallest denomination of the currency (e.g. cents for USD or CAD).

Example: 0

refundableAmount integer

Example: 1000

transactionResponses array of object

Individual gateway responses, with receipts under each entry. The array can be empty while processing is incomplete.

Child attributes

responseCode ResponseCode

Outcomes:

Approved - 1, 2. For 2, only amountApproved was approved. On a Chargeback transaction, approved means the chargeback took effect: the money went back to the payer.
Declined - 10 to 18. The issuer or bank refused the payment. Do not retry with the same payment details.
Canceled - 54, 55. No money moved.
Pending - 57. The outcome is not final. Wait for the webhook or query the transaction again.
Unknown - 0. No specific code was reported. While status is not Completed, the outcome is not final. On a Completed transaction it is not an approval: read resultCode and resultText for the reason, for example 2014, 6901, or 6902.
Error - every other code. Processing failed for a technical or request reason.

See Transaction response codes.

Response codes:

0 - UNKNOWN
1 - APPROVED - Transaction was approved
2 - PARTIAL_APPROVED - Transaction was partially approved, but not for the full requested amount.
10 - DECLINED - Transaction was declined by the issuer or bank. For Card-Present, the transaction can also be declined offline by the terminal.
11 - INSUFFICIENT_FUNDS - Rejected due to insufficient funds in the account.
12 - CARD_EXPIRED - The card used for the transaction has expired.
13 - FRAUD_SUSPECTED - The transaction was flagged for potential fraud.
14 - INVALID_PAYMENT_INFO - The provided information is invalid (e.g.: card number).
15 - LIMIT_EXCEEDED - Rejected due to reaching a limit (e.g.: credit limit).
16 - VERIFICATION_REQUIRED - Additional customer verification is required for the transaction to proceed (e.g.: 3D Secure).
17 - AUTHENTICATION_FAILED - Rejected due to incorrect PIN or authentication failure.
18 - POLICY_VIOLATION - Rejected due to a violation of the payment gateway's terms of service or policies.
19 - BATCH_EMPTY - Indicates that the batch for processing is empty.
20 - RECORD_NOT_FOUND - Indicates that the requested record for a transaction was not found (e.g.: to VOID a reference).
21 - ALREADY_VOIDED - Indicates that the transaction has already been voided and cannot be processed again.
50 - NETWORK_ERROR - Rejected due to network or communication issues with the payment gateway.
51 - INVALID_ECR_PARAMETER - Payment Terminal or system-specific errors.
52 - NOT_SUPPORTED - Rejected because the requested operation is not supported.
53 - BUSY_OR_UNAVAILABLE - The Payment Terminal, Payment App or system is busy or unavailable.
54 - CANCELLED - Cancelled by the user or merchant.
55 - USER_CANCELLED - Specific to scenarios where the user cancels the transaction.
56 - TIMED_OUT_ON_USER_INPUT - Failed to complete the transaction in time.
57 - PENDING - The transaction is awaiting an asynchronous outcome.

Allowed: 0, 1, 2, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 50, 51, 52, 53, 54, 55, 56, 57

authCode string

The authorization code provided by the card issuer, confirming transaction approval.

Example: "123456"

amountApproved integer

The amount approved for this transaction response.

Example: 1000

approvedAmountBreakdown ApprovedAmountBreakdown

A breakdown of approvedAmount, where each amounts approved on the payment terminal are returned separately. Only returned on Sale, Auth and Capture transactions.

Child attributes

amountGoodsAndServices integer

The approved amount for goods and services.

Example: 900

tax integer

The approved tax amount.

Example: 100

cashback integer

The approved cashback amount.

Example: 0

tip integer

The approved tip amount.

Example: 0

paymentMethod object

The payment method used for this transaction.

Child attributes

id string required

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

This field will be present in three scenarios:

As part of a successful Remove Token endpoint response
In token.removed webhook notifications
In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

Physical - A physical payment terminal for Card Present transactions
Virtual - A hosted payment form/iframe for Card Not Present transactions
VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

Child attributes

name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "12345"

address string

Example: "123 Main St"

state string

Example: "NY"

city string

Example: "Anytown"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

cardType string

The type of card used for this transaction:

UNKNOWN - The card type is unknown
DEBIT - Debit Card
VISA - Visa Credit Card
MASTERCARD - MasterCard Credit Card
AMEX - American Express Credit Card
DINERS - Diners Club Credit Card
DISCOVER - Discover Credit Card
JCB - JCB Credit Card
UNIONPAY - UnionPay Credit Card
MAESTRO - Maestro Debit Card
GIFT - Gift Card
CASH - All-cash Transaction
EBT - Electronic Benefits Transfer Card
INTERAC - Interac (Canadian PIN-debit network), Card Present only
OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

For card tokens: Credit or Debit.
For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

cardType CardType

The type of card used for this transaction:

UNKNOWN - The card type is unknown
DEBIT - Debit Card
VISA - Visa Credit Card
MASTERCARD - MasterCard Credit Card
AMEX - American Express Credit Card
DINERS - Diners Club Credit Card
DISCOVER - Discover Credit Card
JCB - JCB Credit Card
UNIONPAY - UnionPay Credit Card
MAESTRO - Maestro Debit Card
GIFT - Gift Card
CASH - All-cash Transaction
EBT - Electronic Benefits Transfer Card
INTERAC - Interac (Canadian PIN-debit network), Card Present only
OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

avsResult AVSResult

The AVS (Address Verification Service) result. Typically returned on Card Not Present transactions.

A - Address matches, ZIP does not. The first five numerical characters contained in the address match those stored at the VIC or issuer's center. However, the ZIP code does not match.
E - Ineligible transaction.
N - Neither address nor ZIP matches. Neither the first five numerical characters contained in the address match with those stored at the VIC nor issuer's center nor the ZIP code match.
R - Retry (system unavailable or timed out).
S - Card type not supported. The card type for this transaction is not supported by AVS. AVS can verify addresses for Visa cards, MasterCard, proprietary cards, and private label transactions.
U - Address information unavailable.
G - Address information unavailable, International - Visa only, The address information was not available at the VIC or issuer's center.
W - Nine-digit ZIP match, address does not. The nine-digit Postal ZIP code matches that stored at the VIC or card issuer's centre. However, the first five numerical characters contained in the address do not match.
X - Exact match (nine digit ZIP and address). Both the nine-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
Y - Address and five-digit ZIP match. Both the five-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
Z - Five-digit ZIP matches, address does not. The five-digit Postal ZIP code matches that stored at the VIC or card issuer's centre.

Allowed: A, E, N, R, S, U, G, W, X, Y, Z

cvvResult CVVResult

The CVV verification result. Typically returned on Card Not Present transactions.

M - CVV Match
N - CVV No Match
P - Not Processed
S - CVV should be on the card but the merchant indicates it is not.
U - User is unregistered

Allowed: M, N, P, S, U

accountType string

The funding-source classification associated with the payment method used in this transaction.

For credit/debit cards: Credit or Debit. May be null when the classification is unavailable, including on older transactions.
For ACH/EFT bank accounts: Checking or Savings.

The immediate hosted ACH response uses lowercase checking or savings. Retrieved transaction responses normally use Checking or Savings.

Allowed: Credit, Debit, Checking, Savings, checking, savings

Example: "Credit"

hostResponseText string

A meaningful text explaining the response code from the host.

Example: "APPROVED 00"

receipt Receipt

Receipt lines for this transaction response. Card-present responses can contain printable receipt lines; other responses can return an empty lines array.

Child attributes

lines array of string required

The receipt lines.

sourceId string

threeDs ThreeDsAuthentication

Child attributes

status string

The authentication outcome to use in your integration. The other threeDs fields provide supporting authentication data.

Allowed: Authenticated, Attempted, NotAuthenticated, Failed, Unavailable, NotEnrolled

Example: "Authenticated"

cavv string

Cardholder Authentication Verification Value. Cryptographic proof that 3DS authentication was performed. Present on frictionless and challenge-completed transactions.

Example: "AAABBkgwVoRhY2tcYlZGAAAAAAA="

eci string

E-commerce Indicator. Indicates 3DS liability-shift status per card scheme:

02 / 05 - Fully authenticated (liability shift to issuer).
01 / 06 - Attempted authentication (partial liability shift).
00 / 07 - Not authenticated (no liability shift).

Example: "05"

xid string

3DS1 transaction identifier. Some issuers still return this under 3DS2 for backward compatibility.

Example: "MDAwMDAwMDAwMDAwMDAwMTM3MDI="

dsTransId string

Directory Server transaction ID (3DS2). Identifies the authentication associated with this card transaction.

Example: "b71a7d5d-cc38-4ce9-80c3-50a7d53271f7"

threeDReasonId string

Issuer-provided reason code when 3DS authentication failed. Populated only on declines. Use status to handle the outcome and threeDReason for the explanation.

Example: "10"

threeDReason string

Human-readable description matching threeDReasonId.

Example: "Stolen Card"

threeDsChallenge ThreeDsChallenge

Present when a token payment requires a cardholder challenge (resultCode: 4100).

Child attributes

redirectUrl string (uri) required

Hosted URL where the cardholder completes the challenge.

followUpToken string required

Opaque token identifying the pending challenge.

A transaction with its refundable balance

{
  "id": "trx_01JWBPE27KHY2K4J7A13ATQ786",
  "timestamp": "2025-05-22T17:00:50Z",
  "type": "Sale",
  "status": "Completed",
  "resultCode": 0,
  "resultText": "APPROVED",
  "referenceId": "ref_s192i49i",
  "orderNumber": "order_number_1234",
  "invoiceNumber": "inv_1234567890123456",
  "requestedAmount": 1000,
  "approvedAmount": 1000,
  "balanceAmount": 0,
  "refundableAmount": 1000
}

400

Request Error

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

Invalid transaction ID

{
  "code": 2000,
  "status": "Rejected",
  "message": "Invalid transaction ID",
  "traceId": "1-6838bcce-5c0074e82ac7170d4f990d87",
  "timestamp": "2025-05-29T20:00:15.5752808Z",
  "errorDetails": [
    {
      "code": 2000,
      "field": "id",
      "message": "Invalid transaction ID"
    }
  ]
}

401

Unauthorized response due to an invalid or missing API key.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

UnauthorizedError

{
  "code": 1000,
  "status": "Rejected",
  "message": "API key cannot be empty",
  "traceId": "1-6838be96-74c62f8e2804352739e63476",
  "timestamp": "2025-05-29T20:07:50.4723483Z",
  "errorDetails": []
}

404

Transaction not found

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

Unknown transaction or transaction owned by another merchant

{
  "code": 4000,
  "status": "Rejected",
  "message": "Transaction trx_01JWBPE27KHY2K4J7A13ATQ786 not found",
  "traceId": "1-6838bcce-5c0074e82ac7170d4f990d87",
  "timestamp": "2025-05-29T20:00:15.5752808Z",
  "errorDetails": []
}

Sale (Card Present)

POST/transactions/physical-sale

Process a financial transaction using a physical payment terminal where the card is present. The card will be tokenized for future use.

Webhook Events

The following webhook events will be triggered during the transaction process:

sale.completed - when a financial transaction is processed and completed.
token.created - when a card is tokenized and stored as a payment method.

Request body

The request to process a Card Present transaction using a physical payment terminal.

application/json · CardPresentRequest

amount Amount required

The total transaction amount. This is the full amount that will be processed in the transaction. Transaction amounts are positive integers representing the amount in its smallest denomination of the configured currency (e.g. cents for USD or CAD).

min 1 · max 999999999

Example: 1000

amountBreakdown AmountBreakdown

Optional fields to specify the portion of the total transaction amount that represents goods/services, tax, cashback and/or tip. These values are for reporting purposes only and will not be added to the Amount field. These amount are represented as a positive integer in the smallest denomination of the configured currency (e.g. cents for USD or CAD). If supplied, the component sum must equal amount; components are not added to amount.

Child attributes

amountGoodsAndServices integer

The amount for goods and services.

min 0 · max 999999999

Example: 900

tax integer

The tax amount.

min 0 · max 999999999

Example: 100

cashback integer

The cashback amount.

min 0 · max 999999999

Example: 0

tip integer

The tip amount.

min 0 · max 999999999

Example: 0

paymentMethodId string

The ID of the physical payment terminal that will process this Card Present transaction.

Example format: pmt_trm_01JRZPTMTBN41PC3VPQNZ5T3HF
Omit only when the merchant has a configured default for this operation or a single resolvable payment method.
Otherwise, provide an explicit payment method ID.

You can retrieve all available physical payment terminal IDs for your account using the GET /payment-methods endpoint.

max length 35

Example: "pmt_trm_01JRZPTMTBN41PC3VPQNZ5T3HF"

invoiceNumber InvoiceNumberCardPresent

An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response and will appear on the receipt.

Card Present Limit: Maximum length is 20 characters. If this limit is exceeded, the API will return a validation error.

max length 20

Example: "inv_1234567890123456"

orderNumber OrderNumber

An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.

max length 100

Example: "order_number_1234"

referenceId ReferenceIdForTransactions

An optional custom reference ID for this transaction. Include this if you want to use your own reference system for linking transactions together (for example, when processing captures and refunds). Use a unique value per merchant. This field is not an idempotency key and reusing it does not replay the prior response. The reference ID can be used for processing captures and referenced refunds by including it in the originalReferenceId field of subsequent transactions. If not provided, a unique reference ID will be generated automatically by the system.

max length 100

Example: "ref_s192i49i"

Card Present Sale request example

{
  "amount": 1000,
  "amountBreakdown": {
    "amountGoodsAndServices": 900,
    "tax": 100,
    "cashback": 0,
    "tip": 0
  },
  "paymentMethodId": "pmt_trm_01JRZPTMTBN41PC3VPQNZ5T3HF",
  "invoiceNumber": "inv_1234567890123456",
  "orderNumber": "order_number_1234",
  "referenceId": "ref_s192i49i"
}

Responses

200

A successful Card Present sale response

application/json · object

id string

Unique ID for this transaction.

Example: "trx_01J2F0EKHC7HY2R93C8ENBD1FG"

timestamp string (date-time)

Transaction timestamp in UTC

Example: "2025-05-27T18:49:31Z"

type string

Type of transaction.

Treat this list as open: ignore a value your integration does not recognize instead of rejecting the transaction.

Allowed: Sale, Auth, Capture, Refund, Void, Chargeback

Example: "Sale"

status TransactionStatus

Allowed: Unknown, Created, Pending, Submitted, Acknowledged, Processing, AwaitingSettlement, Completed, Failed, Abandoned

Example: "Completed"

accountHolder object

Account holder information associated with the transaction

Child attributes

id string required

Account holder ID assigned by the API.

Example: "aho_01JRZPRGFF4J2SZC3HMDBYEN2J"

externalId string required

External account holder ID assigned by your application.

Example: "usr_1234567890123"

contact object

Contact information for the account holder. Only returned for Card Not Present transactions.

Child attributes

name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "60606"

address string

Example: "300 S Wacker Dr"

state string

Example: "IL"

city string

Example: "Chicago"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

paymentMethod object

The payment method used for this transaction.

Child attributes

id string required

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

This field will be present in three scenarios:

As part of a successful Remove Token endpoint response
In token.removed webhook notifications
In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

Physical - A physical payment terminal for Card Present transactions
Virtual - A hosted payment form/iframe for Card Not Present transactions
VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

Child attributes

name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "12345"

address string

Example: "123 Main St"

state string

Example: "NY"

city string

Example: "Anytown"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

cardType string

The type of card used for this transaction:

UNKNOWN - The card type is unknown
DEBIT - Debit Card
VISA - Visa Credit Card
MASTERCARD - MasterCard Credit Card
AMEX - American Express Credit Card
DINERS - Diners Club Credit Card
DISCOVER - Discover Credit Card
JCB - JCB Credit Card
UNIONPAY - UnionPay Credit Card
MAESTRO - Maestro Debit Card
GIFT - Gift Card
CASH - All-cash Transaction
EBT - Electronic Benefits Transfer Card
INTERAC - Interac (Canadian PIN-debit network), Card Present only
OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

For card tokens: Credit or Debit.
For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

invoiceNumber InvoiceNumber

An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.

max length 100

Example: "inv_1234567890123456"

orderNumber OrderNumber

An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.

max length 100

Example: "order_number_1234"

referenceId ReferenceIdForResponse

max length 100

Example: "ref_s192i49i"

originalTransactionId string

Example: "trx_01JWBPE27KHY2K4J7A13ATQ786"

resultCode ResultCode

Result codes:

0 - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)
1003 - The payment terminal is busy or unavailable. (If this error persists, the user may need to close and re-open the Payment Application on the terminal or restart the terminal)
1005 - The specified terminal could not be found.
1010 - The transaction request is pending to become transaction.
2014 - The payment method or card brand is not enabled for the merchant. resultText carries the message, such as ACH payments are not enabled for this merchant. or Visa cards are not enabled for this merchant. The transaction is Completed and failed; do not retry it with the same payment method.
3000 - An unexpected error occurred. Please try again.
3002 - The transaction could not be completed because the payment terminal could not find the related transaction.
3005 - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.
3006 - The transaction could not be completed because the payment terminal is low on battery.
3009 - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.
3010 - The transaction took too long and was cancelled by the application.
3011 - Invalid transaction request. Please consult the documentation for valid transaction requests.
3012 - Invalid transaction request. paymentMethodId is invalid.
3013 - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.
3014 - Invalid amount. Please try your transaction again with an amount greater than $0.
3020 - An unsupported transaction result was received.
4001 - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.
6800 - 3D Secure authentication was rejected by the issuer's ACS (card auth failed, security failure, stolen card, suspected fraud, etc.). Surfaced on declined CNP transactions when formConfig.enable3DSecure: true and the gateway reports a 3D Secure reason; other failures in a 3D Secure session use 6900-6902. See SDK Error Codes for guidance.
6801 - 3D Secure authentication could not be completed because of an upstream technical issue (ACS timeout, directory server unreachable). Retry later or, if merchant policy allows, retry with 3DS disabled.
6802 - The card is not enrolled in 3D Secure. Retry without 3DS only if merchant policy allows; approval is not guaranteed.
6900 - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText. See SDK Error Codes for guidance.
6901 - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision. See SDK Error Codes for guidance.
6902 - The gateway reported no failure but returned no payment token. See SDK Error Codes for guidance.
9998 - The system is not ready to process a transaction.
9999 - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.
1010 - The transaction request is pending customer interaction.
4100 - Cardholder verification is required. Follow threeDsChallenge.redirectUrl and reconcile the final transaction outcome before retrying.
55 - The customer cancelled the hosted payment attempt.

Example: 0

resultText ResultText

Example: "APPROVED"

requestedAmount integer

The requested amount in minor units. Virtual tokenization uses 0; physical tokenization uses a 1-unit authorization.

Example: 1000

approvedAmount integer

The approved amount in minor units. This is 0 for a decline or an outcome that is still in flight. A terminal may adjust the amount, for example by adding a tip.

Example: 1000

balanceAmount integer

The balance that remains to be paid on the transaction. This amount is always an integer in the smallest denomination of the currency (e.g. cents for USD or CAD).

Example: 0

refundableAmount integer

Example: 1000

transactionResponses array of object

Individual gateway responses, with receipts under each entry. The array can be empty while processing is incomplete.

Child attributes

responseCode ResponseCode

Outcomes:

Approved - 1, 2. For 2, only amountApproved was approved. On a Chargeback transaction, approved means the chargeback took effect: the money went back to the payer.
Declined - 10 to 18. The issuer or bank refused the payment. Do not retry with the same payment details.
Canceled - 54, 55. No money moved.
Pending - 57. The outcome is not final. Wait for the webhook or query the transaction again.
Unknown - 0. No specific code was reported. While status is not Completed, the outcome is not final. On a Completed transaction it is not an approval: read resultCode and resultText for the reason, for example 2014, 6901, or 6902.
Error - every other code. Processing failed for a technical or request reason.

See Transaction response codes.

Response codes:

0 - UNKNOWN
1 - APPROVED - Transaction was approved
2 - PARTIAL_APPROVED - Transaction was partially approved, but not for the full requested amount.
10 - DECLINED - Transaction was declined by the issuer or bank. For Card-Present, the transaction can also be declined offline by the terminal.
11 - INSUFFICIENT_FUNDS - Rejected due to insufficient funds in the account.
12 - CARD_EXPIRED - The card used for the transaction has expired.
13 - FRAUD_SUSPECTED - The transaction was flagged for potential fraud.
14 - INVALID_PAYMENT_INFO - The provided information is invalid (e.g.: card number).
15 - LIMIT_EXCEEDED - Rejected due to reaching a limit (e.g.: credit limit).
16 - VERIFICATION_REQUIRED - Additional customer verification is required for the transaction to proceed (e.g.: 3D Secure).
17 - AUTHENTICATION_FAILED - Rejected due to incorrect PIN or authentication failure.
18 - POLICY_VIOLATION - Rejected due to a violation of the payment gateway's terms of service or policies.
19 - BATCH_EMPTY - Indicates that the batch for processing is empty.
20 - RECORD_NOT_FOUND - Indicates that the requested record for a transaction was not found (e.g.: to VOID a reference).
21 - ALREADY_VOIDED - Indicates that the transaction has already been voided and cannot be processed again.
50 - NETWORK_ERROR - Rejected due to network or communication issues with the payment gateway.
51 - INVALID_ECR_PARAMETER - Payment Terminal or system-specific errors.
52 - NOT_SUPPORTED - Rejected because the requested operation is not supported.
53 - BUSY_OR_UNAVAILABLE - The Payment Terminal, Payment App or system is busy or unavailable.
54 - CANCELLED - Cancelled by the user or merchant.
55 - USER_CANCELLED - Specific to scenarios where the user cancels the transaction.
56 - TIMED_OUT_ON_USER_INPUT - Failed to complete the transaction in time.
57 - PENDING - The transaction is awaiting an asynchronous outcome.

Allowed: 0, 1, 2, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 50, 51, 52, 53, 54, 55, 56, 57

authCode string

The authorization code provided by the card issuer, confirming transaction approval.

Example: "123456"

amountApproved integer

The amount approved for this transaction response.

Example: 1000

approvedAmountBreakdown ApprovedAmountBreakdown

A breakdown of approvedAmount, where each amounts approved on the payment terminal are returned separately. Only returned on Sale, Auth and Capture transactions.

Child attributes

amountGoodsAndServices integer

The approved amount for goods and services.

Example: 900

tax integer

The approved tax amount.

Example: 100

cashback integer

The approved cashback amount.

Example: 0

tip integer

The approved tip amount.

Example: 0

paymentMethod object

The payment method used for this transaction.

Child attributes

id string required

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

This field will be present in three scenarios:

As part of a successful Remove Token endpoint response
In token.removed webhook notifications
In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

Physical - A physical payment terminal for Card Present transactions
Virtual - A hosted payment form/iframe for Card Not Present transactions
VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

Child attributes

name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "12345"

address string

Example: "123 Main St"

state string

Example: "NY"

city string

Example: "Anytown"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

cardType string

The type of card used for this transaction:

UNKNOWN - The card type is unknown
DEBIT - Debit Card
VISA - Visa Credit Card
MASTERCARD - MasterCard Credit Card
AMEX - American Express Credit Card
DINERS - Diners Club Credit Card
DISCOVER - Discover Credit Card
JCB - JCB Credit Card
UNIONPAY - UnionPay Credit Card
MAESTRO - Maestro Debit Card
GIFT - Gift Card
CASH - All-cash Transaction
EBT - Electronic Benefits Transfer Card
INTERAC - Interac (Canadian PIN-debit network), Card Present only
OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

For card tokens: Credit or Debit.
For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

cardType CardType

The type of card used for this transaction:

UNKNOWN - The card type is unknown
DEBIT - Debit Card
VISA - Visa Credit Card
MASTERCARD - MasterCard Credit Card
AMEX - American Express Credit Card
DINERS - Diners Club Credit Card
DISCOVER - Discover Credit Card
JCB - JCB Credit Card
UNIONPAY - UnionPay Credit Card
MAESTRO - Maestro Debit Card
GIFT - Gift Card
CASH - All-cash Transaction
EBT - Electronic Benefits Transfer Card
INTERAC - Interac (Canadian PIN-debit network), Card Present only
OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

avsResult AVSResult

The AVS (Address Verification Service) result. Typically returned on Card Not Present transactions.

A - Address matches, ZIP does not. The first five numerical characters contained in the address match those stored at the VIC or issuer's center. However, the ZIP code does not match.
E - Ineligible transaction.
N - Neither address nor ZIP matches. Neither the first five numerical characters contained in the address match with those stored at the VIC nor issuer's center nor the ZIP code match.
R - Retry (system unavailable or timed out).
S - Card type not supported. The card type for this transaction is not supported by AVS. AVS can verify addresses for Visa cards, MasterCard, proprietary cards, and private label transactions.
U - Address information unavailable.
G - Address information unavailable, International - Visa only, The address information was not available at the VIC or issuer's center.
W - Nine-digit ZIP match, address does not. The nine-digit Postal ZIP code matches that stored at the VIC or card issuer's centre. However, the first five numerical characters contained in the address do not match.
X - Exact match (nine digit ZIP and address). Both the nine-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
Y - Address and five-digit ZIP match. Both the five-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
Z - Five-digit ZIP matches, address does not. The five-digit Postal ZIP code matches that stored at the VIC or card issuer's centre.

Allowed: A, E, N, R, S, U, G, W, X, Y, Z

cvvResult CVVResult

The CVV verification result. Typically returned on Card Not Present transactions.

M - CVV Match
N - CVV No Match
P - Not Processed
S - CVV should be on the card but the merchant indicates it is not.
U - User is unregistered

Allowed: M, N, P, S, U

accountType string

The funding-source classification associated with the payment method used in this transaction.

For credit/debit cards: Credit or Debit. May be null when the classification is unavailable, including on older transactions.
For ACH/EFT bank accounts: Checking or Savings.

The immediate hosted ACH response uses lowercase checking or savings. Retrieved transaction responses normally use Checking or Savings.

Allowed: Credit, Debit, Checking, Savings, checking, savings

Example: "Credit"

hostResponseText string

A meaningful text explaining the response code from the host.

Example: "APPROVED 00"

receipt Receipt

Receipt lines for this transaction response. Card-present responses can contain printable receipt lines; other responses can return an empty lines array.

Child attributes

lines array of string required

The receipt lines.

sourceId string

threeDs ThreeDsAuthentication

Child attributes

status string

The authentication outcome to use in your integration. The other threeDs fields provide supporting authentication data.

Allowed: Authenticated, Attempted, NotAuthenticated, Failed, Unavailable, NotEnrolled

Example: "Authenticated"

cavv string

Cardholder Authentication Verification Value. Cryptographic proof that 3DS authentication was performed. Present on frictionless and challenge-completed transactions.

Example: "AAABBkgwVoRhY2tcYlZGAAAAAAA="

eci string

E-commerce Indicator. Indicates 3DS liability-shift status per card scheme:

02 / 05 - Fully authenticated (liability shift to issuer).
01 / 06 - Attempted authentication (partial liability shift).
00 / 07 - Not authenticated (no liability shift).

Example: "05"

xid string

3DS1 transaction identifier. Some issuers still return this under 3DS2 for backward compatibility.

Example: "MDAwMDAwMDAwMDAwMDAwMTM3MDI="

dsTransId string

Directory Server transaction ID (3DS2). Identifies the authentication associated with this card transaction.

Example: "b71a7d5d-cc38-4ce9-80c3-50a7d53271f7"

threeDReasonId string

Issuer-provided reason code when 3DS authentication failed. Populated only on declines. Use status to handle the outcome and threeDReason for the explanation.

Example: "10"

threeDReason string

Human-readable description matching threeDReasonId.

Example: "Stolen Card"

threeDsChallenge ThreeDsChallenge

Present when a token payment requires a cardholder challenge (resultCode: 4100).

Child attributes

redirectUrl string (uri) required

Hosted URL where the cardholder completes the challenge.

followUpToken string required

Opaque token identifying the pending challenge.

successfulResponse

{
  "id": "trx_01J2F0EKHC7HY2R93C8ENBD1FG",
  "timestamp": "2025-05-27T18:49:31Z",
  "type": "Sale",
  "status": "Completed",
  "accountHolder": {
    "id": "aho_01JRZPRGFF4J2SZC3HMDBYEN2J",
    "externalId": "usr_1234567890123"
  },
  "paymentMethod": {
    "id": "pmt_trm_01JRZPTMTBN41PC3VPQNZ5T3HF",
    "type": "Physical",
    "currency": "USD",
    "description": "Main Store Terminal"
  },
  "invoiceNumber": "inv_1234567890123456",
  "orderNumber": "order_number_1234",
  "referenceId": "ref_s192i49i",
  "resultCode": 0,
  "resultText": "APPROVED",
  "requestedAmount": 1000,
  "approvedAmount": 1000,
  "balanceAmount": 0,
  "transactionResponses": [
    {
      "responseCode": 1,
      "authCode": "123456",
      "amountApproved": 1000,
      "approvedAmountBreakdown": {
        "amountGoodsAndServices": 1000,
        "tax": 0,
        "cashback": 0,
        "tip": 0
      },
      "paymentMethod": {
        "id": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J",
        "type": "Token",
        "currency": "USD",
        "description": "Token for John Doe's Visa",
        "cardType": "VISA",
        "maskedCardNumber": "************0011"
      },
      "cardType": "VISA",
      "accountType": "Credit",
      "hostResponseText": "APPROVED 00",
      "receipt": {
        "lines": [
          "     Test Merchant      ",
          "      300 S Wacker      ",
          "         Loop,          ",
          "                        ",
          "                        ",
          " ",
          "TERM #          11000367",
          "RECORD #         0656191",
          "HOST INVOICE #    000038",
          "HOST SEQ #    1720656191",
          "MERCH",
          "INVOICE inv_123456789012",
          "        3456",
          "------------------------",
          "CARD    ************0011",
          "VISA             Contact",
          "07/10/2024      20:03:05",
          "------------------------",
          "CLERK ID               1",
          "          SALE          ",
          "",
          "",
          "TOTAL         USD $10.00",
          "------------------------",
          "AUTH#:123456       B:171",
          "",
          "      APPROVED 00      ",
          "       THANK YOU       ",
          " ",
          "     NO CARDHOLDER     ",
          "      VERIFICATION      ",
          "",
          " ",
          " Visa                    ",
          "AID: A0000000031010     ",
          "TC: 43F4ACF64B07551A    ",
          "TVR: 8000008000         ",
          "TSI: 7800               ",
          "",
          "  Retain this copy for  ",
          "  statement validation  ",
          "",
          "                        ",
          "                        ",
          "                        ",
          "                        ",
          "                        ",
          "     CUSTOMER COPY     ",
          "",
          "     Test Merchant      ",
          "      300 S Wacker      ",
          "         Loop,          ",
          "                        ",
          "                        ",
          " ",
          "TERM #          11000367",
          "RECORD #         0656191",
          "HOST INVOICE #    000038",
          "HOST SEQ #    1720656191",
          "MERCH",
          "INVOICE inv_123456789012",
          "        3456",
          "------------------------",
          "CARD    ************0011",
          "VISA             Contact",
          "07/10/2024      20:03:05",
          "------------------------",
          "CLERK ID               1",
          "          SALE          ",
          "",
          "",
          "TOTAL         USD $10.00",
          "------------------------",
          "AUTH#:123456       B:171",
          "",
          "      APPROVED 00      ",
          "       THANK YOU       ",
          " ",
          "     NO CARDHOLDER     ",
          "      VERIFICATION      ",
          "",
          " ",
          " Visa                    ",
          "AID: A0000000031010     ",
          "TC: 43F4ACF64B07551A    ",
          "TVR: 8000008000         ",
          "TSI: 7800               ",
          "",
          "",
          "",
          "                        ",
          "                        ",
          "                        ",
          "                        ",
          "                        ",
          "     MERCHANT COPY     "
        ]
      }
    }
  ]
}

400

Request Error

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

401

Unauthorized response due to an invalid or missing API key.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

UnauthorizedError

{
  "code": 1000,
  "status": "Rejected",
  "message": "API key cannot be empty",
  "traceId": "1-6838be96-74c62f8e2804352739e63476",
  "timestamp": "2025-05-29T20:07:50.4723483Z",
  "errorDetails": []
}

Sale (Card Not Present)

POST/transactions/virtual-sale

Process a financial transaction using a hosted payment form / iframe where the card is not physically present. This POST request initiates a payment session and returns a short-lived iframe URL to embed in your payment page, rather than using a static iframe URL.

For a JavaScript drop-in integration, load https://cdn.omni.integratedcommerce.io/sdk/latest/ic-pay-sdk.js and pass the returned sessionId to ic.payment.v1.mount(...). See Integrated Payment SDK.

When the customer submits their payment information, they will be redirected to the returnUrl (if provided) or a postMessage event will be sent to the parent window. The complete transaction result will be delivered via the Sale Completed webhook.

The payment method will be tokenized for future use.

Payment Method Types

This endpoint supports different payment method types based on the paymentMethodId provided:

Virtual (Card): Standard card-not-present transaction with immediate processing
VirtualAch (ACH Bank Transfer): ACH transactions for US bank transfers

ACH Transactions

When using an ACH payment method (VirtualAch), the transaction flow differs from card transactions:

Session creation returns status: Pending without a result code. After submission, the hosted ACH response uses status: Processing and resultCode: 0. A token-sale response can report status: Completed before bank settlement.
The transaction request progresses through Processing and AwaitingSettlement as the bank transfer executes
Final outcomes are delivered via webhook with status: Completed; inspect transactionResponses[].responseCode for approval or decline (typically 1-5 business days)
The ACH account will be tokenized for future token sales

Note: ACH tokens have restrictions - they cannot be used for void, authorization, or subscription transactions.

Account Holder Integration

You can optionally provide an accountHolder object with an externalId to associate the transaction with a customer in your system. This is useful for:

Tracking payment history per customer using your own identifiers
Linking tokenized payment methods to customers
Querying a customer's saved payment methods later via GET /payment-methods/account-holder/{externalId}

If an account holder with the provided externalId already exists, it will be used. Otherwise, a new account holder will be created.

Webhook Events

The following webhook events will be triggered during the transaction process:

sale.completed - when a financial transaction is processed and completed.
token.created - when a card or ACH account is tokenized and stored as a payment method.

Request body

The request to process a Card Not Present transaction using a hosted payment form / iframe.

application/json · CardNotPresentRequest

amount Amount required

min 1 · max 999999999

Example: 1000

amountBreakdown AmountBreakdown

Child attributes

amountGoodsAndServices integer

The amount for goods and services.

min 0 · max 999999999

Example: 900

tax integer

The tax amount.

min 0 · max 999999999

Example: 100

cashback integer

The cashback amount.

min 0 · max 999999999

Example: 0

tip integer

The tip amount.

min 0 · max 999999999

Example: 0

paymentMethodId string

The ID of the hosted payment form / iframe that will collect card information for this Card Not Present transaction.

Example format: pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS
Omit only when the merchant has a configured default for this operation or a single resolvable payment method.
Otherwise, provide an explicit payment method ID.

You can retrieve all available hosted payment form IDs for your account using the GET /payment-methods endpoint.

max length 35

Example: "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS"

invoiceNumber InvoiceNumber

An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.

max length 100

Example: "inv_1234567890123456"

orderNumber OrderNumber

An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.

max length 100

Example: "order_number_1234"

referenceId ReferenceIdForTransactions

max length 100

Example: "ref_s192i49i"

returnUrl string

Will be used to redirect user back to merchant's site after iframe completed or canceled if provided. The URL will include various parameters that are detailed in "Transaction Result Parameters" section of the Hosted Payment Form section. If you do not provide a returnUrl, the customer will see either a "Payment Processed Successfully" or "Payment Processing Issue" screen.

max length 1000

Example: "https://merchant.example.com/payment-complete"

useJavaScriptCallback boolean

At the end of the transaction flow, the user is always redirected to either the returnUrl (if provided), or a default success or issue page. In addition, if useJavaScriptCallback is set to true, the iframe will use JavaScript to post a message to the parent window to notify the merchant's site when the iframe completed. This allows for more control over the user experience on the merchant's site.

Example: true

formConfig object

Optional form configuration. Omit to use payment method defaults. If supplied, billingInfoCaptureLevel is required.

Child attributes

billingInfoCaptureLevel string required

Required when formConfig is supplied. Choose Full or Minimal.

Allowed: Minimal, Full

enable3DSecure boolean

Optional. When true, the hosted payment form performs 3D Secure (3DS2) cardholder authentication during card tokenization. The issuer decides whether the transaction is authenticated frictionlessly or requires a cardholder challenge; when a challenge is required, it is rendered in an overlay on the hosted payment form and the SDK resumes automatically on completion.

When false, 3DS is skipped and liability for fraudulent chargebacks remains with the merchant.

The resulting transaction exposes the authentication outcome in threeDs.status and additional authentication data in threeDs when available.

Card payment methods only. 3DS is a card-network protocol and is not supported for ACH or EFT payment methods - setting enable3DSecure: true on a non-card payment method is rejected with a validation error.

When omitted, this field inherits the payment method default.

Recommended: Combine with billingInfoCaptureLevel: Full (the default) to maximize the likelihood of a frictionless flow. Full billing is not required for 3DS to function, but the risk engine uses address, email, and phone to score the transaction.

piiFields array of string

Optional additional contact fields to collect. Omitted values inherit the payment method defaults; an empty array requests neither field.

Allowed: Email, Phone

accountHolder object

Optional external customer identifier. Supported by virtual sale and virtual tokenization; ignored by virtual authorization.

Child attributes

externalId string

Your external identifier for this customer. This can be any unique identifier from your system.

If an account holder with this external ID already exists for the merchant identified by your API key, it will be used. Otherwise, a new account holder will be created with this external ID.

max length 255

Example: "customer_abc123xyz"

Card Not Present Sale request example

{
  "amount": 1000,
  "amountBreakdown": {
    "amountGoodsAndServices": 900,
    "tax": 100,
    "cashback": 0,
    "tip": 0
  },
  "paymentMethodId": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
  "invoiceNumber": "inv_1234567890123456",
  "orderNumber": "order_number_1234",
  "referenceId": "ref_s192i49i",
  "useJavaScriptCallback": true
}

Card Not Present Sale with minimal billing (country and ZIP/postal code)

{
  "amount": 1000,
  "paymentMethodId": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
  "invoiceNumber": "inv_1234567890123456",
  "useJavaScriptCallback": true,
  "formConfig": {
    "billingInfoCaptureLevel": "Minimal"
  }
}

Card Not Present Sale with full billing address

{
  "amount": 1000,
  "paymentMethodId": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
  "invoiceNumber": "inv_1234567890123456",
  "useJavaScriptCallback": true,
  "formConfig": {
    "billingInfoCaptureLevel": "Full"
  }
}

Card Not Present Sale with account holder

{
  "amount": 1000,
  "paymentMethodId": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
  "invoiceNumber": "inv_1234567890123456",
  "referenceId": "ref_s192i49i",
  "useJavaScriptCallback": true,
  "accountHolder": {
    "externalId": "customer_abc123xyz"
  }
}

Responses

200

A successful Card Not Present sale response

application/json · CNPVirtualResponse

id string

Identifier of the hosted session request (ifr_ prefix). This is not a transaction ID.

Example: "ifr_01J2F0ZJ2JW5B63CJFPXRGAB1S"

paymentMethod object

The payment method used for this transaction.

Child attributes

id string required

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

This field will be present in three scenarios:

As part of a successful Remove Token endpoint response
In token.removed webhook notifications
In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

Physical - A physical payment terminal for Card Present transactions
Virtual - A hosted payment form/iframe for Card Not Present transactions
VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

Child attributes

name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "12345"

address string

Example: "123 Main St"

state string

Example: "NY"

city string

Example: "Anytown"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

cardType string

The type of card used for this transaction:

UNKNOWN - The card type is unknown
DEBIT - Debit Card
VISA - Visa Credit Card
MASTERCARD - MasterCard Credit Card
AMEX - American Express Credit Card
DINERS - Diners Club Credit Card
DISCOVER - Discover Credit Card
JCB - JCB Credit Card
UNIONPAY - UnionPay Credit Card
MAESTRO - Maestro Debit Card
GIFT - Gift Card
CASH - All-cash Transaction
EBT - Electronic Benefits Transfer Card
INTERAC - Interac (Canadian PIN-debit network), Card Present only
OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

For card tokens: Credit or Debit.
For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

invoiceNumber InvoiceNumber

An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.

max length 100

Example: "inv_1234567890123456"

orderNumber OrderNumber

An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.

max length 100

Example: "order_number_1234"

referenceId ReferenceIdForResponse

max length 100

Example: "ref_s192i49i"

requestedAmount integer

The amount sent in the transaction request. The amount is always a non-null positive integer in the smallest denomination of the currency (e.g. cents for USD or CAD).

Example: 1000

sessionId string

Opaque session token. Pass this exact unprefixed value to the SDK.

Example: "01JSFAMY0AGW27QKP30C727512"

iframeUrl string

URL for the iframe to collect payment information, or null if iframe could not be created due to invalid credentials, etc.

Example: "https://hpf.integratedcommerce.io/session/01JSFAMY0AGW27QKP30C727512"

expirationTimestamp string (date-time)

Absolute session expiry in UTC, 10 minutes after creation.

Example: "2025-04-17T14:19:03Z"

status string

Status of the iframe session. When created, this will always be pending. The status values will be updated as the customer goes through the iframe process.

Allowed: Pending, Completed, Expired, Error

Example: "Pending"

A successful response for a Card Not Present sale transaction.

{
  "id": "ifr_01J2F0EKHC7HY2R93C8ENBD1FG",
  "paymentMethod": {
    "id": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
    "type": "Virtual",
    "currency": "USD",
    "description": "Online Checkout Iframe"
  },
  "invoiceNumber": "inv_1234567890123456",
  "orderNumber": "order_number_1234",
  "referenceId": "ref_s192i49i",
  "requestedAmount": 1000,
  "sessionId": "01JSFAMY0AGW27QKP30C727512",
  "iframeUrl": "https://hpf.integratedcommerce.io/session/01JSFAMY0AGW27QKP30C727512",
  "expirationTimestamp": "2025-04-17T14:19:03Z",
  "status": "Pending"
}

400

Request Error

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

401

Unauthorized response due to an invalid or missing API key.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

UnauthorizedError

{
  "code": 1000,
  "status": "Rejected",
  "message": "API key cannot be empty",
  "traceId": "1-6838be96-74c62f8e2804352739e63476",
  "timestamp": "2025-05-29T20:07:50.4723483Z",
  "errorDetails": []
}

Sale (Token)

POST/transactions/token-sale

Process a financial transaction using a previously tokenized payment method. This endpoint supports both tokenized cards and tokenized ACH (bank transfer) payment methods.

ACH Token Sales

When processing a sale with an ACH token (a pmt_tkn_ payment method that stores a bank account), the transaction will be processed as an ACH bank transfer. ACH transactions are asynchronous:

The immediate token-sale response can report status: Completed before bank settlement. Empty transactionResponses and the synchronous response do not establish the final bank outcome.
The transaction request progresses through Processing and AwaitingSettlement
Final outcomes are delivered via webhook with status: Completed; inspect transactionResponses[].responseCode for approval or decline

Note: ACH tokens have restrictions. They cannot be used for authorization, void, or subscription transactions.

Payment method not enabled

If the payment method or the card brand is not enabled for the merchant, the request is rejected with HTTP 400 and error code 2014 (PaymentMethodNotEnabled). The message names what is not enabled, for example Visa cards are not enabled for this merchant. For an ACH token, the message is ACH payments are not enabled for this merchant. The failed transaction is stored with resultCode 2014 and can be read with GET /transactions, but no webhook is sent for it. Do not retry with the same payment method.

Token not ready

A token that is not yet ready for payments is rejected with HTTP 409 and error code 4001 (Payment method not yet available). Retry after a few moments.

Webhook Events

The following webhook events will be triggered during the transaction process:

sale.completed - when a financial transaction is processed and completed.

Request body

The request to process a Card On File transaction using a tokenized card or ACH payment method.

application/json · CardOnFileRequest

amount Amount required

min 1 · max 999999999

Example: 1000

amountBreakdown AmountBreakdown

Child attributes

amountGoodsAndServices integer

The amount for goods and services.

min 0 · max 999999999

Example: 900

tax integer

The tax amount.

min 0 · max 999999999

Example: 100

cashback integer

The cashback amount.

min 0 · max 999999999

Example: 0

tip integer

The tip amount.

min 0 · max 999999999

Example: 0

paymentMethodId string required

The ID of the token that will be used for this Card On File transaction.

Example format: pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J
ALWAYS REQUIRED when using a token

max length 35

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

invoiceNumber InvoiceNumber

An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.

max length 100

Example: "inv_1234567890123456"

orderNumber OrderNumber

An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.

max length 100

Example: "order_number_1234"

referenceId ReferenceIdForTransactions

max length 100

Example: "ref_s192i49i"

Card On File Sale request example

{
  "amount": 1000,
  "amountBreakdown": {
    "amountGoodsAndServices": 900,
    "tax": 100,
    "cashback": 0,
    "tip": 0
  },
  "paymentMethodId": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J",
  "invoiceNumber": "inv_1234567890123456",
  "orderNumber": "order_number_1234",
  "referenceId": "ref_s192i49i"
}

Responses

200

A successful Card On File sale response

application/json · CNPTransactionResponse

id string

Unique ID for this transaction.

Example: "trx_01J2F0EKHC7HY2R93C8ENBD1FG"

sourceId string

The source ID of the transaction.

Example: "trx_01J2F0EKHC7HY2R93C8ENBD1FG"

timestamp string (date-time)

Transaction timestamp in UTC

Example: "2025-05-27T18:49:31Z"

type string

Type of transaction

Allowed: Sale, Auth, Capture, Refund, Void

Example: "Sale"

status TransactionStatus

Allowed: Unknown, Created, Pending, Submitted, Acknowledged, Processing, AwaitingSettlement, Completed, Failed, Abandoned

Example: "Completed"

accountHolder object

Account holder information associated with the transaction

Child attributes

id string required

Account holder ID assigned by the API.

Example: "aho_01JRZPRGFF4J2SZC3HMDBYEN2J"

externalId string required

External account holder ID assigned by your application.

Example: "usr_1234567890123"

contact object

Contact information for the account holder. Only returned for Card Not Present transactions.

Child attributes

name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "60606"

address string

Example: "300 S Wacker Dr"

state string

Example: "IL"

city string

Example: "Chicago"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

paymentMethod object

The payment method used for this transaction.

Child attributes

id string required

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

This field will be present in three scenarios:

As part of a successful Remove Token endpoint response
In token.removed webhook notifications
In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

Physical - A physical payment terminal for Card Present transactions
Virtual - A hosted payment form/iframe for Card Not Present transactions
VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

Child attributes

name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "12345"

address string

Example: "123 Main St"

state string

Example: "NY"

city string

Example: "Anytown"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

cardType string

The type of card used for this transaction:

UNKNOWN - The card type is unknown
DEBIT - Debit Card
VISA - Visa Credit Card
MASTERCARD - MasterCard Credit Card
AMEX - American Express Credit Card
DINERS - Diners Club Credit Card
DISCOVER - Discover Credit Card
JCB - JCB Credit Card
UNIONPAY - UnionPay Credit Card
MAESTRO - Maestro Debit Card
GIFT - Gift Card
CASH - All-cash Transaction
EBT - Electronic Benefits Transfer Card
INTERAC - Interac (Canadian PIN-debit network), Card Present only
OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

For card tokens: Credit or Debit.
For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

invoiceNumber InvoiceNumber

An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.

max length 100

Example: "inv_1234567890123456"

orderNumber OrderNumber

An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.

max length 100

Example: "order_number_1234"

referenceId ReferenceIdForResponse

max length 100

Example: "ref_s192i49i"

resultCode ResultCode

Result codes:

0 - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)
1003 - The payment terminal is busy or unavailable. (If this error persists, the user may need to close and re-open the Payment Application on the terminal or restart the terminal)
1005 - The specified terminal could not be found.
1010 - The transaction request is pending to become transaction.
2014 - The payment method or card brand is not enabled for the merchant. resultText carries the message, such as ACH payments are not enabled for this merchant. or Visa cards are not enabled for this merchant. The transaction is Completed and failed; do not retry it with the same payment method.
3000 - An unexpected error occurred. Please try again.
3002 - The transaction could not be completed because the payment terminal could not find the related transaction.
3005 - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.
3006 - The transaction could not be completed because the payment terminal is low on battery.
3009 - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.
3010 - The transaction took too long and was cancelled by the application.
3011 - Invalid transaction request. Please consult the documentation for valid transaction requests.
3012 - Invalid transaction request. paymentMethodId is invalid.
3013 - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.
3014 - Invalid amount. Please try your transaction again with an amount greater than $0.
3020 - An unsupported transaction result was received.
4001 - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.
6800 - 3D Secure authentication was rejected by the issuer's ACS (card auth failed, security failure, stolen card, suspected fraud, etc.). Surfaced on declined CNP transactions when formConfig.enable3DSecure: true and the gateway reports a 3D Secure reason; other failures in a 3D Secure session use 6900-6902. See SDK Error Codes for guidance.
6801 - 3D Secure authentication could not be completed because of an upstream technical issue (ACS timeout, directory server unreachable). Retry later or, if merchant policy allows, retry with 3DS disabled.
6802 - The card is not enrolled in 3D Secure. Retry without 3DS only if merchant policy allows; approval is not guaranteed.
6900 - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText. See SDK Error Codes for guidance.
6901 - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision. See SDK Error Codes for guidance.
6902 - The gateway reported no failure but returned no payment token. See SDK Error Codes for guidance.
9998 - The system is not ready to process a transaction.
9999 - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.
1010 - The transaction request is pending customer interaction.
4100 - Cardholder verification is required. Follow threeDsChallenge.redirectUrl and reconcile the final transaction outcome before retrying.
55 - The customer cancelled the hosted payment attempt.

Example: 0

resultText ResultText

Example: "APPROVED"

requestedAmount integer

The requested amount in minor units. Virtual tokenization uses 0; physical tokenization uses a 1-unit authorization.

Example: 1000

approvedAmount integer

The approved amount in minor units. This is 0 for a decline or an outcome that is still in flight. A terminal may adjust the amount, for example by adding a tip.

Example: 1000

balanceAmount integer

The balance that remains to be paid on the transaction. This amount is always an integer in the smallest denomination of the currency (e.g. cents for USD or CAD).

Example: 0

refundableAmount integer

Example: 1000

transactionResponses array of TransactionResponse

Individual gateway responses, with receipts under each entry. The array can be empty while processing is incomplete.

Child attributes

responseCode ResponseCode

Outcomes:

Approved - 1, 2. For 2, only amountApproved was approved. On a Chargeback transaction, approved means the chargeback took effect: the money went back to the payer.
Declined - 10 to 18. The issuer or bank refused the payment. Do not retry with the same payment details.
Canceled - 54, 55. No money moved.
Pending - 57. The outcome is not final. Wait for the webhook or query the transaction again.
Unknown - 0. No specific code was reported. While status is not Completed, the outcome is not final. On a Completed transaction it is not an approval: read resultCode and resultText for the reason, for example 2014, 6901, or 6902.
Error - every other code. Processing failed for a technical or request reason.

See Transaction response codes.

Response codes:

0 - UNKNOWN
1 - APPROVED - Transaction was approved
2 - PARTIAL_APPROVED - Transaction was partially approved, but not for the full requested amount.
10 - DECLINED - Transaction was declined by the issuer or bank. For Card-Present, the transaction can also be declined offline by the terminal.
11 - INSUFFICIENT_FUNDS - Rejected due to insufficient funds in the account.
12 - CARD_EXPIRED - The card used for the transaction has expired.
13 - FRAUD_SUSPECTED - The transaction was flagged for potential fraud.
14 - INVALID_PAYMENT_INFO - The provided information is invalid (e.g.: card number).
15 - LIMIT_EXCEEDED - Rejected due to reaching a limit (e.g.: credit limit).
16 - VERIFICATION_REQUIRED - Additional customer verification is required for the transaction to proceed (e.g.: 3D Secure).
17 - AUTHENTICATION_FAILED - Rejected due to incorrect PIN or authentication failure.
18 - POLICY_VIOLATION - Rejected due to a violation of the payment gateway's terms of service or policies.
19 - BATCH_EMPTY - Indicates that the batch for processing is empty.
20 - RECORD_NOT_FOUND - Indicates that the requested record for a transaction was not found (e.g.: to VOID a reference).
21 - ALREADY_VOIDED - Indicates that the transaction has already been voided and cannot be processed again.
50 - NETWORK_ERROR - Rejected due to network or communication issues with the payment gateway.
51 - INVALID_ECR_PARAMETER - Payment Terminal or system-specific errors.
52 - NOT_SUPPORTED - Rejected because the requested operation is not supported.
53 - BUSY_OR_UNAVAILABLE - The Payment Terminal, Payment App or system is busy or unavailable.
54 - CANCELLED - Cancelled by the user or merchant.
55 - USER_CANCELLED - Specific to scenarios where the user cancels the transaction.
56 - TIMED_OUT_ON_USER_INPUT - Failed to complete the transaction in time.
57 - PENDING - The transaction is awaiting an asynchronous outcome.

Allowed: 0, 1, 2, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 50, 51, 52, 53, 54, 55, 56, 57

authCode string

The authorization code provided by the card issuer, confirming transaction approval.

Example: "123456"

amountApproved integer

The amount approved for this transaction response.

Example: 1000

approvedAmountBreakdown ApprovedAmountBreakdown

A breakdown of approvedAmount, where each amounts approved on the payment terminal are returned separately. Only returned on Sale, Auth and Capture transactions.

Child attributes

amountGoodsAndServices integer

The approved amount for goods and services.

Example: 900

tax integer

The approved tax amount.

Example: 100

cashback integer

The approved cashback amount.

Example: 0

tip integer

The approved tip amount.

Example: 0

paymentMethod object

The payment method used for this transaction.

Child attributes

id string required

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

This field will be present in three scenarios:

As part of a successful Remove Token endpoint response
In token.removed webhook notifications
In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

Physical - A physical payment terminal for Card Present transactions
Virtual - A hosted payment form/iframe for Card Not Present transactions
VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

Child attributes

name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "12345"

address string

Example: "123 Main St"

state string

Example: "NY"

city string

Example: "Anytown"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

cardType string

The type of card used for this transaction:

UNKNOWN - The card type is unknown
DEBIT - Debit Card
VISA - Visa Credit Card
MASTERCARD - MasterCard Credit Card
AMEX - American Express Credit Card
DINERS - Diners Club Credit Card
DISCOVER - Discover Credit Card
JCB - JCB Credit Card
UNIONPAY - UnionPay Credit Card
MAESTRO - Maestro Debit Card
GIFT - Gift Card
CASH - All-cash Transaction
EBT - Electronic Benefits Transfer Card
INTERAC - Interac (Canadian PIN-debit network), Card Present only
OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

For card tokens: Credit or Debit.
For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

cardType CardType

The type of card used for this transaction:

UNKNOWN - The card type is unknown
DEBIT - Debit Card
VISA - Visa Credit Card
MASTERCARD - MasterCard Credit Card
AMEX - American Express Credit Card
DINERS - Diners Club Credit Card
DISCOVER - Discover Credit Card
JCB - JCB Credit Card
UNIONPAY - UnionPay Credit Card
MAESTRO - Maestro Debit Card
GIFT - Gift Card
CASH - All-cash Transaction
EBT - Electronic Benefits Transfer Card
INTERAC - Interac (Canadian PIN-debit network), Card Present only
OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

avsResult AVSResult

The AVS (Address Verification Service) result. Typically returned on Card Not Present transactions.

A - Address matches, ZIP does not. The first five numerical characters contained in the address match those stored at the VIC or issuer's center. However, the ZIP code does not match.
E - Ineligible transaction.
N - Neither address nor ZIP matches. Neither the first five numerical characters contained in the address match with those stored at the VIC nor issuer's center nor the ZIP code match.
R - Retry (system unavailable or timed out).
S - Card type not supported. The card type for this transaction is not supported by AVS. AVS can verify addresses for Visa cards, MasterCard, proprietary cards, and private label transactions.
U - Address information unavailable.
G - Address information unavailable, International - Visa only, The address information was not available at the VIC or issuer's center.
W - Nine-digit ZIP match, address does not. The nine-digit Postal ZIP code matches that stored at the VIC or card issuer's centre. However, the first five numerical characters contained in the address do not match.
X - Exact match (nine digit ZIP and address). Both the nine-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
Y - Address and five-digit ZIP match. Both the five-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
Z - Five-digit ZIP matches, address does not. The five-digit Postal ZIP code matches that stored at the VIC or card issuer's centre.

Allowed: A, E, N, R, S, U, G, W, X, Y, Z

cvvResult CVVResult

The CVV verification result. Typically returned on Card Not Present transactions.

M - CVV Match
N - CVV No Match
P - Not Processed
S - CVV should be on the card but the merchant indicates it is not.
U - User is unregistered

Allowed: M, N, P, S, U

accountType string

The funding-source classification associated with the payment method used in this transaction.

For credit/debit cards: Credit or Debit. May be null when the classification is unavailable, including on older transactions.
For ACH/EFT bank accounts: Checking or Savings.

The immediate hosted ACH response uses lowercase checking or savings. Retrieved transaction responses normally use Checking or Savings.

Allowed: Credit, Debit, Checking, Savings, checking, savings

Example: "Credit"

hostResponseText string

A meaningful text explaining the response code from the host.

Example: "APPROVED 00"

receipt Receipt

Receipt lines for this transaction response. Card-present responses can contain printable receipt lines; other responses can return an empty lines array.

Child attributes

lines array of string required

The receipt lines.

threeDs object

3D Secure authentication data returned by the issuer. Populated when the transaction was initiated with formConfig.enable3DSecure: true. Null on non-3DS transactions or when no authentication data is available.

Child attributes

status string

The authentication outcome to use in your integration. The other threeDs fields provide supporting authentication data.

Allowed: Authenticated, Attempted, NotAuthenticated, Failed, Unavailable, NotEnrolled

Example: "Authenticated"

cavv string

Cardholder Authentication Verification Value. Cryptographic proof that 3DS authentication was performed. Present on frictionless and challenge-completed transactions.

Example: "AAABBkgwVoRhY2tcYlZGAAAAAAA="

eci string

E-commerce Indicator. Indicates 3DS liability-shift status per card scheme:

02 / 05 - Fully authenticated (liability shift to issuer).
01 / 06 - Attempted authentication (partial liability shift).
00 / 07 - Not authenticated (no liability shift).

Example: "05"

xid string

3DS1 transaction identifier. Some issuers still return this under 3DS2 for backward compatibility.

Example: "MDAwMDAwMDAwMDAwMDAwMTM3MDI="

dsTransId string

Directory Server transaction ID (3DS2). Identifies the authentication associated with this card transaction.

Example: "b71a7d5d-cc38-4ce9-80c3-50a7d53271f7"

threeDReasonId string

Issuer-provided reason code when 3DS authentication failed. Populated only on declines. Use status to handle the outcome and threeDReason for the explanation.

Example: "10"

threeDReason string

Human-readable description matching threeDReasonId.

Example: "Stolen Card"

threeDsChallenge ThreeDsChallenge

Present when a token payment requires a cardholder challenge (resultCode: 4100).

Child attributes

redirectUrl string (uri) required

Hosted URL where the cardholder completes the challenge.

followUpToken string required

Opaque token identifying the pending challenge.

A successful response for a Card On File sale transaction.

{
  "id": "trx_01J2F0EKHC7HY2R93C8ENBD1FG",
  "timestamp": "2025-05-27T18:49:31Z",
  "type": "Sale",
  "status": "Completed",
  "accountHolder": {
    "id": "aho_01JRZPRGFF4J2SZC3HMDBYEN2J",
    "externalId": "usr_1234567890123",
    "contact": {
      "name": "John Doe",
      "countryCode": "US",
      "zipCode": "60606",
      "address": "300 S Wacker Dr",
      "state": "IL",
      "city": "Chicago"
    }
  },
  "paymentMethod": {
    "id": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J",
    "type": "Token",
    "currency": "USD",
    "billingContact": {
      "name": "John Doe",
      "countryCode": "US",
      "zipCode": "12345",
      "address": "123 Main St",
      "state": "NY",
      "city": "Anytown"
    },
    "cardType": "AMEX",
    "maskedCardNumber": "3****6452",
    "cardExpDate": "1225"
  },
  "invoiceNumber": "inv_1234567890123456",
  "orderNumber": "order_number_1234",
  "referenceId": "ref_s192i49i",
  "resultCode": 0,
  "resultText": "APPROVED",
  "requestedAmount": 1000,
  "approvedAmount": 1000,
  "balanceAmount": 0,
  "transactionResponses": [
    {
      "responseCode": 1,
      "authCode": "123456",
      "amountApproved": 1000,
      "approvedAmountBreakdown": {
        "amountGoodsAndServices": 1000,
        "tax": 0,
        "cashback": 0,
        "tip": 0
      },
      "paymentMethod": {
        "id": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J",
        "type": "Token",
        "currency": "USD",
        "billingContact": {
          "name": "John Doe",
          "countryCode": "US",
          "zipCode": "12345",
          "address": "123 Main St",
          "state": "NY",
          "city": "Anytown"
        },
        "cardType": "AMEX",
        "maskedCardNumber": "3****6452",
        "cardExpDate": "1225"
      },
      "receipt": {
        "lines": []
      }
    }
  ]
}

400

Request Error

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

401

Unauthorized response due to an invalid or missing API key.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

UnauthorizedError

{
  "code": 1000,
  "status": "Rejected",
  "message": "API key cannot be empty",
  "traceId": "1-6838be96-74c62f8e2804352739e63476",
  "timestamp": "2025-05-29T20:07:50.4723483Z",
  "errorDetails": []
}

409

The token is not ready for payments yet (error code 4001). Retry after a few moments.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

Example

{
  "code": 4001,
  "status": "Rejected",
  "message": "Payment method not yet available",
  "traceId": "1-6838bcce-5c0074e82ac7170d4f990d87",
  "timestamp": "2025-05-29T20:00:15.5752808Z",
  "errorDetails": []
}

Auth (Card Present)

POST/transactions/physical-auth

Create an authorization using a physical payment terminal where the card is present. This will not result in a financial transaction and the card will be tokenized. A capture must be performed to complete the financial transaction.

Webhook Events

The following webhook events will be triggered during the authorization process:

auth.completed - when an authorization is processed and completed.
token.created - when a card is tokenized and stored as a payment method.

Request body

The request to create a Card Present authorization using a physical payment terminal.

application/json · CardPresentRequest

amount Amount required

min 1 · max 999999999

Example: 1000

amountBreakdown AmountBreakdown

Child attributes

amountGoodsAndServices integer

The amount for goods and services.

min 0 · max 999999999

Example: 900

tax integer

The tax amount.

min 0 · max 999999999

Example: 100

cashback integer

The cashback amount.

min 0 · max 999999999

Example: 0

tip integer

The tip amount.

min 0 · max 999999999

Example: 0

paymentMethodId string

The ID of the physical payment terminal that will process this Card Present transaction.

Example format: pmt_trm_01JRZPTMTBN41PC3VPQNZ5T3HF
Omit only when the merchant has a configured default for this operation or a single resolvable payment method.
Otherwise, provide an explicit payment method ID.

You can retrieve all available physical payment terminal IDs for your account using the GET /payment-methods endpoint.

max length 35

Example: "pmt_trm_01JRZPTMTBN41PC3VPQNZ5T3HF"

invoiceNumber InvoiceNumberCardPresent

An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response and will appear on the receipt.

Card Present Limit: Maximum length is 20 characters. If this limit is exceeded, the API will return a validation error.

max length 20

Example: "inv_1234567890123456"

orderNumber OrderNumber

An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.

max length 100

Example: "order_number_1234"

referenceId ReferenceIdForTransactions

max length 100

Example: "ref_s192i49i"

Card Present Authorization request example

{
  "amount": 1000,
  "amountBreakdown": {
    "amountGoodsAndServices": 900,
    "tax": 100,
    "cashback": 0,
    "tip": 0
  },
  "paymentMethodId": "pmt_trm_01JRZPTMTBN41PC3VPQNZ5T3HF",
  "invoiceNumber": "inv_1234567890123456",
  "orderNumber": "order_number_1234",
  "referenceId": "ref_s192i49i"
}

Responses

200

A successful Card Present authorization response

application/json · object

id string

Unique ID for this transaction.

Example: "trx_01J2F0EKHC7HY2R93C8ENBD1FG"

timestamp string (date-time)

Transaction timestamp in UTC

Example: "2025-05-27T18:49:31Z"

type string

Type of transaction.

Treat this list as open: ignore a value your integration does not recognize instead of rejecting the transaction.

Allowed: Sale, Auth, Capture, Refund, Void, Chargeback

Example: "Sale"

status TransactionStatus

Allowed: Unknown, Created, Pending, Submitted, Acknowledged, Processing, AwaitingSettlement, Completed, Failed, Abandoned

Example: "Completed"

accountHolder object

Account holder information associated with the transaction

Child attributes

id string required

Account holder ID assigned by the API.

Example: "aho_01JRZPRGFF4J2SZC3HMDBYEN2J"

externalId string required

External account holder ID assigned by your application.

Example: "usr_1234567890123"

contact object

Contact information for the account holder. Only returned for Card Not Present transactions.

Child attributes

name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "60606"

address string

Example: "300 S Wacker Dr"

state string

Example: "IL"

city string

Example: "Chicago"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

paymentMethod object

The payment method used for this transaction.

Child attributes

id string required

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

This field will be present in three scenarios:

As part of a successful Remove Token endpoint response
In token.removed webhook notifications
In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

Physical - A physical payment terminal for Card Present transactions
Virtual - A hosted payment form/iframe for Card Not Present transactions
VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

Child attributes

name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "12345"

address string

Example: "123 Main St"

state string

Example: "NY"

city string

Example: "Anytown"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

cardType string

The type of card used for this transaction:

UNKNOWN - The card type is unknown
DEBIT - Debit Card
VISA - Visa Credit Card
MASTERCARD - MasterCard Credit Card
AMEX - American Express Credit Card
DINERS - Diners Club Credit Card
DISCOVER - Discover Credit Card
JCB - JCB Credit Card
UNIONPAY - UnionPay Credit Card
MAESTRO - Maestro Debit Card
GIFT - Gift Card
CASH - All-cash Transaction
EBT - Electronic Benefits Transfer Card
INTERAC - Interac (Canadian PIN-debit network), Card Present only
OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

For card tokens: Credit or Debit.
For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

invoiceNumber InvoiceNumber

An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.

max length 100

Example: "inv_1234567890123456"

orderNumber OrderNumber

An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.

max length 100

Example: "order_number_1234"

referenceId ReferenceIdForResponse

max length 100

Example: "ref_s192i49i"

originalTransactionId string

Example: "trx_01JWBPE27KHY2K4J7A13ATQ786"

resultCode ResultCode

Result codes:

0 - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)
1003 - The payment terminal is busy or unavailable. (If this error persists, the user may need to close and re-open the Payment Application on the terminal or restart the terminal)
1005 - The specified terminal could not be found.
1010 - The transaction request is pending to become transaction.
2014 - The payment method or card brand is not enabled for the merchant. resultText carries the message, such as ACH payments are not enabled for this merchant. or Visa cards are not enabled for this merchant. The transaction is Completed and failed; do not retry it with the same payment method.
3000 - An unexpected error occurred. Please try again.
3002 - The transaction could not be completed because the payment terminal could not find the related transaction.
3005 - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.
3006 - The transaction could not be completed because the payment terminal is low on battery.
3009 - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.
3010 - The transaction took too long and was cancelled by the application.
3011 - Invalid transaction request. Please consult the documentation for valid transaction requests.
3012 - Invalid transaction request. paymentMethodId is invalid.
3013 - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.
3014 - Invalid amount. Please try your transaction again with an amount greater than $0.
3020 - An unsupported transaction result was received.
4001 - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.
6800 - 3D Secure authentication was rejected by the issuer's ACS (card auth failed, security failure, stolen card, suspected fraud, etc.). Surfaced on declined CNP transactions when formConfig.enable3DSecure: true and the gateway reports a 3D Secure reason; other failures in a 3D Secure session use 6900-6902. See SDK Error Codes for guidance.
6801 - 3D Secure authentication could not be completed because of an upstream technical issue (ACS timeout, directory server unreachable). Retry later or, if merchant policy allows, retry with 3DS disabled.
6802 - The card is not enrolled in 3D Secure. Retry without 3DS only if merchant policy allows; approval is not guaranteed.
6900 - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText. See SDK Error Codes for guidance.
6901 - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision. See SDK Error Codes for guidance.
6902 - The gateway reported no failure but returned no payment token. See SDK Error Codes for guidance.
9998 - The system is not ready to process a transaction.
9999 - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.
1010 - The transaction request is pending customer interaction.
4100 - Cardholder verification is required. Follow threeDsChallenge.redirectUrl and reconcile the final transaction outcome before retrying.
55 - The customer cancelled the hosted payment attempt.

Example: 0

resultText ResultText

Example: "APPROVED"

requestedAmount integer

The requested amount in minor units. Virtual tokenization uses 0; physical tokenization uses a 1-unit authorization.

Example: 1000

approvedAmount integer

The approved amount in minor units. This is 0 for a decline or an outcome that is still in flight. A terminal may adjust the amount, for example by adding a tip.

Example: 1000

balanceAmount integer

The balance that remains to be paid on the transaction. This amount is always an integer in the smallest denomination of the currency (e.g. cents for USD or CAD).

Example: 0

refundableAmount integer

Example: 1000

transactionResponses array of object

Individual gateway responses, with receipts under each entry. The array can be empty while processing is incomplete.

Child attributes

responseCode ResponseCode

Outcomes:

Approved - 1, 2. For 2, only amountApproved was approved. On a Chargeback transaction, approved means the chargeback took effect: the money went back to the payer.
Declined - 10 to 18. The issuer or bank refused the payment. Do not retry with the same payment details.
Canceled - 54, 55. No money moved.
Pending - 57. The outcome is not final. Wait for the webhook or query the transaction again.
Unknown - 0. No specific code was reported. While status is not Completed, the outcome is not final. On a Completed transaction it is not an approval: read resultCode and resultText for the reason, for example 2014, 6901, or 6902.
Error - every other code. Processing failed for a technical or request reason.

See Transaction response codes.

Response codes:

0 - UNKNOWN
1 - APPROVED - Transaction was approved
2 - PARTIAL_APPROVED - Transaction was partially approved, but not for the full requested amount.
10 - DECLINED - Transaction was declined by the issuer or bank. For Card-Present, the transaction can also be declined offline by the terminal.
11 - INSUFFICIENT_FUNDS - Rejected due to insufficient funds in the account.
12 - CARD_EXPIRED - The card used for the transaction has expired.
13 - FRAUD_SUSPECTED - The transaction was flagged for potential fraud.
14 - INVALID_PAYMENT_INFO - The provided information is invalid (e.g.: card number).
15 - LIMIT_EXCEEDED - Rejected due to reaching a limit (e.g.: credit limit).
16 - VERIFICATION_REQUIRED - Additional customer verification is required for the transaction to proceed (e.g.: 3D Secure).
17 - AUTHENTICATION_FAILED - Rejected due to incorrect PIN or authentication failure.
18 - POLICY_VIOLATION - Rejected due to a violation of the payment gateway's terms of service or policies.
19 - BATCH_EMPTY - Indicates that the batch for processing is empty.
20 - RECORD_NOT_FOUND - Indicates that the requested record for a transaction was not found (e.g.: to VOID a reference).
21 - ALREADY_VOIDED - Indicates that the transaction has already been voided and cannot be processed again.
50 - NETWORK_ERROR - Rejected due to network or communication issues with the payment gateway.
51 - INVALID_ECR_PARAMETER - Payment Terminal or system-specific errors.
52 - NOT_SUPPORTED - Rejected because the requested operation is not supported.
53 - BUSY_OR_UNAVAILABLE - The Payment Terminal, Payment App or system is busy or unavailable.
54 - CANCELLED - Cancelled by the user or merchant.
55 - USER_CANCELLED - Specific to scenarios where the user cancels the transaction.
56 - TIMED_OUT_ON_USER_INPUT - Failed to complete the transaction in time.
57 - PENDING - The transaction is awaiting an asynchronous outcome.

Allowed: 0, 1, 2, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 50, 51, 52, 53, 54, 55, 56, 57

authCode string

The authorization code provided by the card issuer, confirming transaction approval.

Example: "123456"

amountApproved integer

The amount approved for this transaction response.

Example: 1000

approvedAmountBreakdown ApprovedAmountBreakdown

A breakdown of approvedAmount, where each amounts approved on the payment terminal are returned separately. Only returned on Sale, Auth and Capture transactions.

Child attributes

amountGoodsAndServices integer

The approved amount for goods and services.

Example: 900

tax integer

The approved tax amount.

Example: 100

cashback integer

The approved cashback amount.

Example: 0

tip integer

The approved tip amount.

Example: 0

paymentMethod object

The payment method used for this transaction.

Child attributes

id string required

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

This field will be present in three scenarios:

As part of a successful Remove Token endpoint response
In token.removed webhook notifications
In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

Physical - A physical payment terminal for Card Present transactions
Virtual - A hosted payment form/iframe for Card Not Present transactions
VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

Child attributes

name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "12345"

address string

Example: "123 Main St"

state string

Example: "NY"

city string

Example: "Anytown"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

cardType string

The type of card used for this transaction:

UNKNOWN - The card type is unknown
DEBIT - Debit Card
VISA - Visa Credit Card
MASTERCARD - MasterCard Credit Card
AMEX - American Express Credit Card
DINERS - Diners Club Credit Card
DISCOVER - Discover Credit Card
JCB - JCB Credit Card
UNIONPAY - UnionPay Credit Card
MAESTRO - Maestro Debit Card
GIFT - Gift Card
CASH - All-cash Transaction
EBT - Electronic Benefits Transfer Card
INTERAC - Interac (Canadian PIN-debit network), Card Present only
OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

For card tokens: Credit or Debit.
For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

cardType CardType

The type of card used for this transaction:

UNKNOWN - The card type is unknown
DEBIT - Debit Card
VISA - Visa Credit Card
MASTERCARD - MasterCard Credit Card
AMEX - American Express Credit Card
DINERS - Diners Club Credit Card
DISCOVER - Discover Credit Card
JCB - JCB Credit Card
UNIONPAY - UnionPay Credit Card
MAESTRO - Maestro Debit Card
GIFT - Gift Card
CASH - All-cash Transaction
EBT - Electronic Benefits Transfer Card
INTERAC - Interac (Canadian PIN-debit network), Card Present only
OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

avsResult AVSResult

The AVS (Address Verification Service) result. Typically returned on Card Not Present transactions.

A - Address matches, ZIP does not. The first five numerical characters contained in the address match those stored at the VIC or issuer's center. However, the ZIP code does not match.
E - Ineligible transaction.
N - Neither address nor ZIP matches. Neither the first five numerical characters contained in the address match with those stored at the VIC nor issuer's center nor the ZIP code match.
R - Retry (system unavailable or timed out).
S - Card type not supported. The card type for this transaction is not supported by AVS. AVS can verify addresses for Visa cards, MasterCard, proprietary cards, and private label transactions.
U - Address information unavailable.
G - Address information unavailable, International - Visa only, The address information was not available at the VIC or issuer's center.
W - Nine-digit ZIP match, address does not. The nine-digit Postal ZIP code matches that stored at the VIC or card issuer's centre. However, the first five numerical characters contained in the address do not match.
X - Exact match (nine digit ZIP and address). Both the nine-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
Y - Address and five-digit ZIP match. Both the five-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
Z - Five-digit ZIP matches, address does not. The five-digit Postal ZIP code matches that stored at the VIC or card issuer's centre.

Allowed: A, E, N, R, S, U, G, W, X, Y, Z

cvvResult CVVResult

The CVV verification result. Typically returned on Card Not Present transactions.

M - CVV Match
N - CVV No Match
P - Not Processed
S - CVV should be on the card but the merchant indicates it is not.
U - User is unregistered

Allowed: M, N, P, S, U

accountType string

The funding-source classification associated with the payment method used in this transaction.

For credit/debit cards: Credit or Debit. May be null when the classification is unavailable, including on older transactions.
For ACH/EFT bank accounts: Checking or Savings.

The immediate hosted ACH response uses lowercase checking or savings. Retrieved transaction responses normally use Checking or Savings.

Allowed: Credit, Debit, Checking, Savings, checking, savings

Example: "Credit"

hostResponseText string

A meaningful text explaining the response code from the host.

Example: "APPROVED 00"

receipt Receipt

Receipt lines for this transaction response. Card-present responses can contain printable receipt lines; other responses can return an empty lines array.

Child attributes

lines array of string required

The receipt lines.

sourceId string

threeDs ThreeDsAuthentication

Child attributes

status string

The authentication outcome to use in your integration. The other threeDs fields provide supporting authentication data.

Allowed: Authenticated, Attempted, NotAuthenticated, Failed, Unavailable, NotEnrolled

Example: "Authenticated"

cavv string

Cardholder Authentication Verification Value. Cryptographic proof that 3DS authentication was performed. Present on frictionless and challenge-completed transactions.

Example: "AAABBkgwVoRhY2tcYlZGAAAAAAA="

eci string

E-commerce Indicator. Indicates 3DS liability-shift status per card scheme:

02 / 05 - Fully authenticated (liability shift to issuer).
01 / 06 - Attempted authentication (partial liability shift).
00 / 07 - Not authenticated (no liability shift).

Example: "05"

xid string

3DS1 transaction identifier. Some issuers still return this under 3DS2 for backward compatibility.

Example: "MDAwMDAwMDAwMDAwMDAwMTM3MDI="

dsTransId string

Directory Server transaction ID (3DS2). Identifies the authentication associated with this card transaction.

Example: "b71a7d5d-cc38-4ce9-80c3-50a7d53271f7"

threeDReasonId string

Issuer-provided reason code when 3DS authentication failed. Populated only on declines. Use status to handle the outcome and threeDReason for the explanation.

Example: "10"

threeDReason string

Human-readable description matching threeDReasonId.

Example: "Stolen Card"

threeDsChallenge ThreeDsChallenge

Present when a token payment requires a cardholder challenge (resultCode: 4100).

Child attributes

redirectUrl string (uri) required

Hosted URL where the cardholder completes the challenge.

followUpToken string required

Opaque token identifying the pending challenge.

successfulResponse

{
  "id": "trx_01J2F0EKHC7HY2R93C8ENBD1FG",
  "timestamp": "2025-05-27T18:49:31Z",
  "type": "Auth",
  "status": "Completed",
  "accountHolder": {
    "id": "aho_01JRZPRGFF4J2SZC3HMDBYEN2J",
    "externalId": "usr_1234567890123"
  },
  "paymentMethod": {
    "id": "pmt_trm_01JRZPTMTBN41PC3VPQNZ5T3HF",
    "type": "Physical",
    "currency": "USD",
    "description": "Main Store Terminal"
  },
  "invoiceNumber": "inv_1234567890123456",
  "orderNumber": "order_number_1234",
  "referenceId": "ref_s192i49i",
  "resultCode": 0,
  "resultText": "APPROVED",
  "requestedAmount": 1000,
  "approvedAmount": 1000,
  "balanceAmount": 0,
  "transactionResponses": [
    {
      "responseCode": 1,
      "authCode": "123456",
      "amountApproved": 1000,
      "approvedAmountBreakdown": {
        "amountGoodsAndServices": 1000,
        "tax": 0,
        "cashback": 0,
        "tip": 0
      },
      "paymentMethod": {
        "id": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J",
        "type": "Token",
        "currency": "USD",
        "description": "Token for John Doe's Visa",
        "cardType": "VISA",
        "maskedCardNumber": "************0011"
      },
      "cardType": "VISA",
      "accountType": "Credit",
      "hostResponseText": "APPROVED 00",
      "receipt": {
        "lines": [
          "     Test Merchant      ",
          "      300 S Wacker      ",
          "         Loop,          ",
          "                        ",
          "                        ",
          " ",
          "TERM #          11000367",
          "RECORD #         0656191",
          "HOST INVOICE #    000038",
          "HOST SEQ #    1720656191",
          "MERCH",
          "INVOICE inv_123456789012",
          "        3456",
          "------------------------",
          "CARD    ************0011",
          "VISA             Contact",
          "07/10/2024      20:03:05",
          "------------------------",
          "CLERK ID               1",
          "        PRE AUTH        ",
          "",
          "",
          "TOTAL         USD $10.00",
          "------------------------",
          "AUTH#:123456            ",
          "",
          "      APPROVED 00      ",
          "       THANK YOU       ",
          " ",
          "     NO CARDHOLDER     ",
          "      VERIFICATION      ",
          "",
          " ",
          " Visa                    ",
          "AID: A0000000031010     ",
          "TC: 43F4ACF64B07551A    ",
          "TVR: 8000008000         ",
          "TSI: 7800               ",
          "",
          "  Retain this copy for  ",
          "  statement validation  ",
          "",
          "                        ",
          "                        ",
          "                        ",
          "                        ",
          "                        ",
          "     CUSTOMER COPY     ",
          "",
          "     Test Merchant      ",
          "      300 S Wacker      ",
          "         Loop,          ",
          "                        ",
          "                        ",
          " ",
          "TERM #          11000367",
          "RECORD #         0656191",
          "HOST INVOICE #    000038",
          "HOST SEQ #    1720656191",
          "MERCH",
          "INVOICE inv_123456789012",
          "        3456",
          "------------------------",
          "CARD    ************0011",
          "VISA             Contact",
          "07/10/2024      20:03:05",
          "------------------------",
          "CLERK ID               1",
          "        PRE AUTH        ",
          "",
          "",
          "TOTAL         USD $10.00",
          "------------------------",
          "AUTH#:123456            ",
          "",
          "      APPROVED 00      ",
          "       THANK YOU       ",
          " ",
          "     NO CARDHOLDER     ",
          "      VERIFICATION      ",
          "",
          " ",
          " Visa                    ",
          "AID: A0000000031010     ",
          "TC: 43F4ACF64B07551A    ",
          "TVR: 8000008000         ",
          "TSI: 7800               ",
          "",
          "",
          "",
          "                        ",
          "                        ",
          "                        ",
          "                        ",
          "                        ",
          "     MERCHANT COPY     "
        ]
      }
    }
  ]
}

400

Request Error

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

401

Unauthorized response due to an invalid or missing API key.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

UnauthorizedError

{
  "code": 1000,
  "status": "Rejected",
  "message": "API key cannot be empty",
  "traceId": "1-6838be96-74c62f8e2804352739e63476",
  "timestamp": "2025-05-29T20:07:50.4723483Z",
  "errorDetails": []
}

Auth (Card Not Present)

POST/transactions/virtual-auth

Create an authorization using a hosted payment form / iframe where the card is not physically present. This POST request initiates an authorization session and returns a short-lived iframe URL to embed in your payment page, rather than using a static iframe URL.

When the customer submits their payment information, they will be redirected to the returnUrl (if provided) or a postMessage event will be sent to the parent window. The complete authorization result will be delivered via the Auth Completed webhook.

This will not result in a financial transaction and the card will be tokenized. A capture must be performed to complete the financial transaction.

Restrictions

ACH Payment Methods: ACH (VirtualAch) payment methods cannot be used for authorization transactions. ACH only supports sale transactions. Attempting to use an ACH payment method will return an error with code 2010.

Webhook Events

The following webhook events will be triggered during the authorization process:

auth.completed - when an authorization is processed and completed.
token.created - when a card is tokenized and stored as a payment method.

Request body

The request to create a Card Not Present authorization using a hosted payment form / iframe.

application/json · CardNotPresentRequest

amount Amount required

min 1 · max 999999999

Example: 1000

amountBreakdown AmountBreakdown

Child attributes

amountGoodsAndServices integer

The amount for goods and services.

min 0 · max 999999999

Example: 900

tax integer

The tax amount.

min 0 · max 999999999

Example: 100

cashback integer

The cashback amount.

min 0 · max 999999999

Example: 0

tip integer

The tip amount.

min 0 · max 999999999

Example: 0

paymentMethodId string

The ID of the hosted payment form / iframe that will collect card information for this Card Not Present transaction.

Example format: pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS
Omit only when the merchant has a configured default for this operation or a single resolvable payment method.
Otherwise, provide an explicit payment method ID.

You can retrieve all available hosted payment form IDs for your account using the GET /payment-methods endpoint.

max length 35

Example: "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS"

invoiceNumber InvoiceNumber

An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.

max length 100

Example: "inv_1234567890123456"

orderNumber OrderNumber

An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.

max length 100

Example: "order_number_1234"

referenceId ReferenceIdForTransactions

max length 100

Example: "ref_s192i49i"

returnUrl string

max length 1000

Example: "https://merchant.example.com/payment-complete"

useJavaScriptCallback boolean

Example: true

formConfig object

Optional form configuration. Omit to use payment method defaults. If supplied, billingInfoCaptureLevel is required.

Child attributes

billingInfoCaptureLevel string required

Required when formConfig is supplied. Choose Full or Minimal.

Allowed: Minimal, Full

enable3DSecure boolean

When false, 3DS is skipped and liability for fraudulent chargebacks remains with the merchant.

The resulting transaction exposes the authentication outcome in threeDs.status and additional authentication data in threeDs when available.

When omitted, this field inherits the payment method default.

piiFields array of string

Optional additional contact fields to collect. Omitted values inherit the payment method defaults; an empty array requests neither field.

Allowed: Email, Phone

accountHolder object

Optional external customer identifier. Supported by virtual sale and virtual tokenization; ignored by virtual authorization.

Child attributes

externalId string

Your external identifier for this customer. This can be any unique identifier from your system.

If an account holder with this external ID already exists for the merchant identified by your API key, it will be used. Otherwise, a new account holder will be created with this external ID.

max length 255

Example: "customer_abc123xyz"

Card Not Present Authorization request example

{
  "amount": 1000,
  "amountBreakdown": {
    "amountGoodsAndServices": 900,
    "tax": 100,
    "cashback": 0,
    "tip": 0
  },
  "paymentMethodId": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
  "invoiceNumber": "inv_1234567890123456",
  "orderNumber": "order_number_1234",
  "referenceId": "ref_s192i49i",
  "useJavaScriptCallback": true
}

Responses

200

A successful Card Not Present authorization response

application/json · CNPVirtualResponse

id string

Identifier of the hosted session request (ifr_ prefix). This is not a transaction ID.

Example: "ifr_01J2F0ZJ2JW5B63CJFPXRGAB1S"

paymentMethod object

The payment method used for this transaction.

Child attributes

id string required

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

This field will be present in three scenarios:

As part of a successful Remove Token endpoint response
In token.removed webhook notifications
In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

Physical - A physical payment terminal for Card Present transactions
Virtual - A hosted payment form/iframe for Card Not Present transactions
VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

Child attributes

name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "12345"

address string

Example: "123 Main St"

state string

Example: "NY"

city string

Example: "Anytown"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

cardType string

The type of card used for this transaction:

UNKNOWN - The card type is unknown
DEBIT - Debit Card
VISA - Visa Credit Card
MASTERCARD - MasterCard Credit Card
AMEX - American Express Credit Card
DINERS - Diners Club Credit Card
DISCOVER - Discover Credit Card
JCB - JCB Credit Card
UNIONPAY - UnionPay Credit Card
MAESTRO - Maestro Debit Card
GIFT - Gift Card
CASH - All-cash Transaction
EBT - Electronic Benefits Transfer Card
INTERAC - Interac (Canadian PIN-debit network), Card Present only
OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

For card tokens: Credit or Debit.
For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

invoiceNumber InvoiceNumber

An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.

max length 100

Example: "inv_1234567890123456"

orderNumber OrderNumber

An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.

max length 100

Example: "order_number_1234"

referenceId ReferenceIdForResponse

max length 100

Example: "ref_s192i49i"

requestedAmount integer

The amount sent in the transaction request. The amount is always a non-null positive integer in the smallest denomination of the currency (e.g. cents for USD or CAD).

Example: 1000

sessionId string

Opaque session token. Pass this exact unprefixed value to the SDK.

Example: "01JSFAMY0AGW27QKP30C727512"

iframeUrl string

URL for the iframe to collect payment information, or null if iframe could not be created due to invalid credentials, etc.

Example: "https://hpf.integratedcommerce.io/session/01JSFAMY0AGW27QKP30C727512"

expirationTimestamp string (date-time)

Absolute session expiry in UTC, 10 minutes after creation.

Example: "2025-04-17T14:19:03Z"

status string

Status of the iframe session. When created, this will always be pending. The status values will be updated as the customer goes through the iframe process.

Allowed: Pending, Completed, Expired, Error

Example: "Pending"

A successful response for a Card Not Present authorization transaction.

{
  "id": "ifr_01J2F0EKHC7HY2R93C8ENBD1FG",
  "paymentMethod": {
    "id": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
    "type": "Virtual",
    "currency": "USD",
    "description": "Online Checkout Iframe"
  },
  "invoiceNumber": "inv_1234567890123456",
  "orderNumber": "order_number_1234",
  "referenceId": "ref_s192i49i",
  "requestedAmount": 1000,
  "sessionId": "01JSFAMY0AGW27QKP30C727512",
  "iframeUrl": "https://hpf.integratedcommerce.io/session/01JSFAMY0AGW27QKP30C727512",
  "expirationTimestamp": "2025-04-17T14:19:03Z",
  "status": "Pending"
}

400

Request Error

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

401

Unauthorized response due to an invalid or missing API key.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

UnauthorizedError

{
  "code": 1000,
  "status": "Rejected",
  "message": "API key cannot be empty",
  "traceId": "1-6838be96-74c62f8e2804352739e63476",
  "timestamp": "2025-05-29T20:07:50.4723483Z",
  "errorDetails": []
}

Auth (Token)

POST/transactions/token-auth

Create an authorization using a previously tokenized card. This will not result in a financial transaction. A capture must be performed to complete the financial transaction.

Restrictions

ACH Tokens: ACH (bank transfer) tokens cannot be used for authorization transactions. ACH only supports sale transactions. Attempting to use an ACH token will return an error with code 2010 and message indicating the payment method cannot be used for Auth transactions.

Payment method not enabled

If the payment method or the card brand is not enabled for the merchant, the request is rejected with HTTP 400 and error code 2014 (PaymentMethodNotEnabled). The message names what is not enabled, for example Visa cards are not enabled for this merchant. The failed transaction is stored with resultCode 2014 and can be read with GET /transactions, but no webhook is sent for it. Do not retry with the same payment method.

Token not ready

A token that is not yet ready for payments is rejected with HTTP 409 and error code 4001 (Payment method not yet available). Retry after a few moments.

Webhook Events

The following webhook events will be triggered during the authorization process:

auth.completed - when an authorization is processed and completed.

Request body

The request to create a Card On File authorization using a tokenized card.

application/json · CardOnFileRequest

amount Amount required

min 1 · max 999999999

Example: 1000

amountBreakdown AmountBreakdown

Child attributes

amountGoodsAndServices integer

The amount for goods and services.

min 0 · max 999999999

Example: 900

tax integer

The tax amount.

min 0 · max 999999999

Example: 100

cashback integer

The cashback amount.

min 0 · max 999999999

Example: 0

tip integer

The tip amount.

min 0 · max 999999999

Example: 0

paymentMethodId string required

The ID of the token that will be used for this Card On File transaction.

Example format: pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J
ALWAYS REQUIRED when using a token

max length 35

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

invoiceNumber InvoiceNumber

An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.

max length 100

Example: "inv_1234567890123456"

orderNumber OrderNumber

An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.

max length 100

Example: "order_number_1234"

referenceId ReferenceIdForTransactions

max length 100

Example: "ref_s192i49i"

Card On File Authorization request example

{
  "amount": 1000,
  "amountBreakdown": {
    "amountGoodsAndServices": 900,
    "tax": 100,
    "cashback": 0,
    "tip": 0
  },
  "paymentMethodId": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J",
  "invoiceNumber": "inv_1234567890123456",
  "orderNumber": "order_number_1234",
  "referenceId": "ref_s192i49i"
}

Responses

200

A successful Card On File authorization response

application/json · CNPTransactionResponse

id string

Unique ID for this transaction.

Example: "trx_01J2F0EKHC7HY2R93C8ENBD1FG"

sourceId string

The source ID of the transaction.

Example: "trx_01J2F0EKHC7HY2R93C8ENBD1FG"

timestamp string (date-time)

Transaction timestamp in UTC

Example: "2025-05-27T18:49:31Z"

type string

Type of transaction

Allowed: Sale, Auth, Capture, Refund, Void

Example: "Sale"

status TransactionStatus

Allowed: Unknown, Created, Pending, Submitted, Acknowledged, Processing, AwaitingSettlement, Completed, Failed, Abandoned

Example: "Completed"

accountHolder object

Account holder information associated with the transaction

Child attributes

id string required

Account holder ID assigned by the API.

Example: "aho_01JRZPRGFF4J2SZC3HMDBYEN2J"

externalId string required

External account holder ID assigned by your application.

Example: "usr_1234567890123"

contact object

Contact information for the account holder. Only returned for Card Not Present transactions.

Child attributes

name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "60606"

address string

Example: "300 S Wacker Dr"

state string

Example: "IL"

city string

Example: "Chicago"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

paymentMethod object

The payment method used for this transaction.

Child attributes

id string required

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

This field will be present in three scenarios:

As part of a successful Remove Token endpoint response
In token.removed webhook notifications
In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

Physical - A physical payment terminal for Card Present transactions
Virtual - A hosted payment form/iframe for Card Not Present transactions
VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

Child attributes

name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "12345"

address string

Example: "123 Main St"

state string

Example: "NY"

city string

Example: "Anytown"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

cardType string

The type of card used for this transaction:

UNKNOWN - The card type is unknown
DEBIT - Debit Card
VISA - Visa Credit Card
MASTERCARD - MasterCard Credit Card
AMEX - American Express Credit Card
DINERS - Diners Club Credit Card
DISCOVER - Discover Credit Card
JCB - JCB Credit Card
UNIONPAY - UnionPay Credit Card
MAESTRO - Maestro Debit Card
GIFT - Gift Card
CASH - All-cash Transaction
EBT - Electronic Benefits Transfer Card
INTERAC - Interac (Canadian PIN-debit network), Card Present only
OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

For card tokens: Credit or Debit.
For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

invoiceNumber InvoiceNumber

An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.

max length 100

Example: "inv_1234567890123456"

orderNumber OrderNumber

An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.

max length 100

Example: "order_number_1234"

referenceId ReferenceIdForResponse

max length 100

Example: "ref_s192i49i"

resultCode ResultCode

Result codes:

0 - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)
1003 - The payment terminal is busy or unavailable. (If this error persists, the user may need to close and re-open the Payment Application on the terminal or restart the terminal)
1005 - The specified terminal could not be found.
1010 - The transaction request is pending to become transaction.
2014 - The payment method or card brand is not enabled for the merchant. resultText carries the message, such as ACH payments are not enabled for this merchant. or Visa cards are not enabled for this merchant. The transaction is Completed and failed; do not retry it with the same payment method.
3000 - An unexpected error occurred. Please try again.
3002 - The transaction could not be completed because the payment terminal could not find the related transaction.
3005 - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.
3006 - The transaction could not be completed because the payment terminal is low on battery.
3009 - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.
3010 - The transaction took too long and was cancelled by the application.
3011 - Invalid transaction request. Please consult the documentation for valid transaction requests.
3012 - Invalid transaction request. paymentMethodId is invalid.
3013 - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.
3014 - Invalid amount. Please try your transaction again with an amount greater than $0.
3020 - An unsupported transaction result was received.
4001 - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.
6800 - 3D Secure authentication was rejected by the issuer's ACS (card auth failed, security failure, stolen card, suspected fraud, etc.). Surfaced on declined CNP transactions when formConfig.enable3DSecure: true and the gateway reports a 3D Secure reason; other failures in a 3D Secure session use 6900-6902. See SDK Error Codes for guidance.
6801 - 3D Secure authentication could not be completed because of an upstream technical issue (ACS timeout, directory server unreachable). Retry later or, if merchant policy allows, retry with 3DS disabled.
6802 - The card is not enrolled in 3D Secure. Retry without 3DS only if merchant policy allows; approval is not guaranteed.
6900 - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText. See SDK Error Codes for guidance.
6901 - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision. See SDK Error Codes for guidance.
6902 - The gateway reported no failure but returned no payment token. See SDK Error Codes for guidance.
9998 - The system is not ready to process a transaction.
9999 - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.
1010 - The transaction request is pending customer interaction.
4100 - Cardholder verification is required. Follow threeDsChallenge.redirectUrl and reconcile the final transaction outcome before retrying.
55 - The customer cancelled the hosted payment attempt.

Example: 0

resultText ResultText

Example: "APPROVED"

requestedAmount integer

The requested amount in minor units. Virtual tokenization uses 0; physical tokenization uses a 1-unit authorization.

Example: 1000

approvedAmount integer

The approved amount in minor units. This is 0 for a decline or an outcome that is still in flight. A terminal may adjust the amount, for example by adding a tip.

Example: 1000

balanceAmount integer

The balance that remains to be paid on the transaction. This amount is always an integer in the smallest denomination of the currency (e.g. cents for USD or CAD).

Example: 0

refundableAmount integer

Example: 1000

transactionResponses array of TransactionResponse

Individual gateway responses, with receipts under each entry. The array can be empty while processing is incomplete.

Child attributes

responseCode ResponseCode

Outcomes:

Approved - 1, 2. For 2, only amountApproved was approved. On a Chargeback transaction, approved means the chargeback took effect: the money went back to the payer.
Declined - 10 to 18. The issuer or bank refused the payment. Do not retry with the same payment details.
Canceled - 54, 55. No money moved.
Pending - 57. The outcome is not final. Wait for the webhook or query the transaction again.
Unknown - 0. No specific code was reported. While status is not Completed, the outcome is not final. On a Completed transaction it is not an approval: read resultCode and resultText for the reason, for example 2014, 6901, or 6902.
Error - every other code. Processing failed for a technical or request reason.

See Transaction response codes.

Response codes:

0 - UNKNOWN
1 - APPROVED - Transaction was approved
2 - PARTIAL_APPROVED - Transaction was partially approved, but not for the full requested amount.
10 - DECLINED - Transaction was declined by the issuer or bank. For Card-Present, the transaction can also be declined offline by the terminal.
11 - INSUFFICIENT_FUNDS - Rejected due to insufficient funds in the account.
12 - CARD_EXPIRED - The card used for the transaction has expired.
13 - FRAUD_SUSPECTED - The transaction was flagged for potential fraud.
14 - INVALID_PAYMENT_INFO - The provided information is invalid (e.g.: card number).
15 - LIMIT_EXCEEDED - Rejected due to reaching a limit (e.g.: credit limit).
16 - VERIFICATION_REQUIRED - Additional customer verification is required for the transaction to proceed (e.g.: 3D Secure).
17 - AUTHENTICATION_FAILED - Rejected due to incorrect PIN or authentication failure.
18 - POLICY_VIOLATION - Rejected due to a violation of the payment gateway's terms of service or policies.
19 - BATCH_EMPTY - Indicates that the batch for processing is empty.
20 - RECORD_NOT_FOUND - Indicates that the requested record for a transaction was not found (e.g.: to VOID a reference).
21 - ALREADY_VOIDED - Indicates that the transaction has already been voided and cannot be processed again.
50 - NETWORK_ERROR - Rejected due to network or communication issues with the payment gateway.
51 - INVALID_ECR_PARAMETER - Payment Terminal or system-specific errors.
52 - NOT_SUPPORTED - Rejected because the requested operation is not supported.
53 - BUSY_OR_UNAVAILABLE - The Payment Terminal, Payment App or system is busy or unavailable.
54 - CANCELLED - Cancelled by the user or merchant.
55 - USER_CANCELLED - Specific to scenarios where the user cancels the transaction.
56 - TIMED_OUT_ON_USER_INPUT - Failed to complete the transaction in time.
57 - PENDING - The transaction is awaiting an asynchronous outcome.

Allowed: 0, 1, 2, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 50, 51, 52, 53, 54, 55, 56, 57

authCode string

The authorization code provided by the card issuer, confirming transaction approval.

Example: "123456"

amountApproved integer

The amount approved for this transaction response.

Example: 1000

approvedAmountBreakdown ApprovedAmountBreakdown

A breakdown of approvedAmount, where each amounts approved on the payment terminal are returned separately. Only returned on Sale, Auth and Capture transactions.

Child attributes

amountGoodsAndServices integer

The approved amount for goods and services.

Example: 900

tax integer

The approved tax amount.

Example: 100

cashback integer

The approved cashback amount.

Example: 0

tip integer

The approved tip amount.

Example: 0

paymentMethod object

The payment method used for this transaction.

Child attributes

id string required

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

This field will be present in three scenarios:

As part of a successful Remove Token endpoint response
In token.removed webhook notifications
In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

Physical - A physical payment terminal for Card Present transactions
Virtual - A hosted payment form/iframe for Card Not Present transactions
VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

Child attributes

name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "12345"

address string

Example: "123 Main St"

state string

Example: "NY"

city string

Example: "Anytown"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

cardType string

The type of card used for this transaction:

UNKNOWN - The card type is unknown
DEBIT - Debit Card
VISA - Visa Credit Card
MASTERCARD - MasterCard Credit Card
AMEX - American Express Credit Card
DINERS - Diners Club Credit Card
DISCOVER - Discover Credit Card
JCB - JCB Credit Card
UNIONPAY - UnionPay Credit Card
MAESTRO - Maestro Debit Card
GIFT - Gift Card
CASH - All-cash Transaction
EBT - Electronic Benefits Transfer Card
INTERAC - Interac (Canadian PIN-debit network), Card Present only
OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

For card tokens: Credit or Debit.
For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

cardType CardType

The type of card used for this transaction:

UNKNOWN - The card type is unknown
DEBIT - Debit Card
VISA - Visa Credit Card
MASTERCARD - MasterCard Credit Card
AMEX - American Express Credit Card
DINERS - Diners Club Credit Card
DISCOVER - Discover Credit Card
JCB - JCB Credit Card
UNIONPAY - UnionPay Credit Card
MAESTRO - Maestro Debit Card
GIFT - Gift Card
CASH - All-cash Transaction
EBT - Electronic Benefits Transfer Card
INTERAC - Interac (Canadian PIN-debit network), Card Present only
OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

avsResult AVSResult

The AVS (Address Verification Service) result. Typically returned on Card Not Present transactions.

A - Address matches, ZIP does not. The first five numerical characters contained in the address match those stored at the VIC or issuer's center. However, the ZIP code does not match.
E - Ineligible transaction.
N - Neither address nor ZIP matches. Neither the first five numerical characters contained in the address match with those stored at the VIC nor issuer's center nor the ZIP code match.
R - Retry (system unavailable or timed out).
S - Card type not supported. The card type for this transaction is not supported by AVS. AVS can verify addresses for Visa cards, MasterCard, proprietary cards, and private label transactions.
U - Address information unavailable.
G - Address information unavailable, International - Visa only, The address information was not available at the VIC or issuer's center.
W - Nine-digit ZIP match, address does not. The nine-digit Postal ZIP code matches that stored at the VIC or card issuer's centre. However, the first five numerical characters contained in the address do not match.
X - Exact match (nine digit ZIP and address). Both the nine-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
Y - Address and five-digit ZIP match. Both the five-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
Z - Five-digit ZIP matches, address does not. The five-digit Postal ZIP code matches that stored at the VIC or card issuer's centre.

Allowed: A, E, N, R, S, U, G, W, X, Y, Z

cvvResult CVVResult

The CVV verification result. Typically returned on Card Not Present transactions.

M - CVV Match
N - CVV No Match
P - Not Processed
S - CVV should be on the card but the merchant indicates it is not.
U - User is unregistered

Allowed: M, N, P, S, U

accountType string

The funding-source classification associated with the payment method used in this transaction.

For credit/debit cards: Credit or Debit. May be null when the classification is unavailable, including on older transactions.
For ACH/EFT bank accounts: Checking or Savings.

The immediate hosted ACH response uses lowercase checking or savings. Retrieved transaction responses normally use Checking or Savings.

Allowed: Credit, Debit, Checking, Savings, checking, savings

Example: "Credit"

hostResponseText string

A meaningful text explaining the response code from the host.

Example: "APPROVED 00"

receipt Receipt

Receipt lines for this transaction response. Card-present responses can contain printable receipt lines; other responses can return an empty lines array.

Child attributes

lines array of string required

The receipt lines.

threeDs object

Child attributes

status string

The authentication outcome to use in your integration. The other threeDs fields provide supporting authentication data.

Allowed: Authenticated, Attempted, NotAuthenticated, Failed, Unavailable, NotEnrolled

Example: "Authenticated"

cavv string

Cardholder Authentication Verification Value. Cryptographic proof that 3DS authentication was performed. Present on frictionless and challenge-completed transactions.

Example: "AAABBkgwVoRhY2tcYlZGAAAAAAA="

eci string

E-commerce Indicator. Indicates 3DS liability-shift status per card scheme:

02 / 05 - Fully authenticated (liability shift to issuer).
01 / 06 - Attempted authentication (partial liability shift).
00 / 07 - Not authenticated (no liability shift).

Example: "05"

xid string

3DS1 transaction identifier. Some issuers still return this under 3DS2 for backward compatibility.

Example: "MDAwMDAwMDAwMDAwMDAwMTM3MDI="

dsTransId string

Directory Server transaction ID (3DS2). Identifies the authentication associated with this card transaction.

Example: "b71a7d5d-cc38-4ce9-80c3-50a7d53271f7"

threeDReasonId string

Issuer-provided reason code when 3DS authentication failed. Populated only on declines. Use status to handle the outcome and threeDReason for the explanation.

Example: "10"

threeDReason string

Human-readable description matching threeDReasonId.

Example: "Stolen Card"

threeDsChallenge ThreeDsChallenge

Present when a token payment requires a cardholder challenge (resultCode: 4100).

Child attributes

redirectUrl string (uri) required

Hosted URL where the cardholder completes the challenge.

followUpToken string required

Opaque token identifying the pending challenge.

A successful response for a Card On File authorization transaction.

{
  "id": "trx_01J2F0EKHC7HY2R93C8ENBD1FG",
  "timestamp": "2025-05-27T18:49:31Z",
  "type": "Auth",
  "status": "Completed",
  "accountHolder": {
    "id": "aho_01JRZPRGFF4J2SZC3HMDBYEN2J",
    "externalId": "usr_1234567890123",
    "contact": {
      "name": "John Doe",
      "countryCode": "US",
      "zipCode": "60606",
      "address": "300 S Wacker Dr",
      "state": "IL",
      "city": "Chicago"
    }
  },
  "paymentMethod": {
    "id": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J",
    "type": "Token",
    "currency": "USD",
    "billingContact": {
      "name": "John Doe",
      "countryCode": "US",
      "zipCode": "12345",
      "address": "123 Main St",
      "state": "NY",
      "city": "Anytown"
    },
    "cardType": "AMEX",
    "maskedCardNumber": "3****6452",
    "cardExpDate": "1225"
  },
  "invoiceNumber": "inv_1234567890123456",
  "orderNumber": "order_number_1234",
  "referenceId": "ref_s192i49i",
  "resultCode": 0,
  "resultText": "APPROVED",
  "requestedAmount": 1000,
  "approvedAmount": 1000,
  "balanceAmount": 0,
  "transactionResponses": [
    {
      "responseCode": 1,
      "authCode": "123456",
      "amountApproved": 1000,
      "approvedAmountBreakdown": {
        "amountGoodsAndServices": 1000,
        "tax": 0,
        "cashback": 0,
        "tip": 0
      },
      "paymentMethod": {
        "id": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J",
        "type": "Token",
        "currency": "USD",
        "billingContact": {
          "name": "John Doe",
          "countryCode": "US",
          "zipCode": "12345",
          "address": "123 Main St",
          "state": "NY",
          "city": "Anytown"
        },
        "cardType": "AMEX",
        "maskedCardNumber": "3****6452",
        "cardExpDate": "1225"
      },
      "receipt": {
        "lines": []
      }
    }
  ]
}

400

Request Error

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

401

Unauthorized response due to an invalid or missing API key.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

UnauthorizedError

{
  "code": 1000,
  "status": "Rejected",
  "message": "API key cannot be empty",
  "traceId": "1-6838be96-74c62f8e2804352739e63476",
  "timestamp": "2025-05-29T20:07:50.4723483Z",
  "errorDetails": []
}

409

The token is not ready for payments yet (error code 4001). Retry after a few moments.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

Example

{
  "code": 4001,
  "status": "Rejected",
  "message": "Payment method not yet available",
  "traceId": "1-6838bcce-5c0074e82ac7170d4f990d87",
  "timestamp": "2025-05-29T20:00:15.5752808Z",
  "errorDetails": []
}

Capture

POST/transactions/capture

Complete a previously authorized transaction, resulting in a financial transaction. The amount can be equal to or less than the original authorization amount.

Webhook Events

The following webhook events will be triggered during the capture process:

capture.completed - when a transaction capture for a previously authorized transaction is completed.

Request body

The request to capture a previously authorized transaction.

application/json · CaptureRequest

originalTransactionId OriginalTransactionId

The transaction ID (trx_) of the original authorization to capture, or sale/capture to refund. Supply exactly one of originalTransactionId and originalReferenceId.

min length 1 · max length 30

Example: "trx_01J2F0EKHC7HY2R93C8ENBD1FG"

originalReferenceId OriginalReferenceId

The reference ID of the original transaction to be captured or refunded. This should match the referenceId from a previous sale, authorization, or capture transaction (either a custom reference ID you provided or one that was generated automatically by the system). Use this parameter if you want to link transactions using reference IDs rather than system transaction IDs. Either originalTransactionId or originalReferenceId must be provided.

min length 1 · max length 100

Example: "ref_s192i49i"

referenceId ReferenceIdForTransactions

max length 100

Example: "ref_s192i49i"

amount AmountToCapture

The amount to capture. Must be less than or equal to the original authorization amount. If not specified, the full authorized amount will be captured. If you have already performed partial captures on this authorization, you must provide an explicit amount or an error will be returned.

min 1 · max 999999999

Example: 1000

invoiceNumber InvoiceNumber

An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.

max length 100

Example: "inv_1234567890123456"

orderNumber OrderNumber

An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.

max length 100

Example: "order_number_1234"

Capture using original transaction ID

{
  "originalTransactionId": "trx_01J2F0EKHC7HY2R93C8ENBD1FG",
  "amount": 1000,
  "invoiceNumber": "inv_1234567890123456",
  "orderNumber": "order_number_1234",
  "referenceId": "ref_capture_12345"
}

Capture using original reference ID

{
  "originalReferenceId": "ref_s192i49i",
  "amount": 1000,
  "invoiceNumber": "inv_1234567890123456",
  "orderNumber": "order_number_1234",
  "referenceId": "ref_capture_12345"
}

Responses

200

A successful capture response

application/json · CaptureResponse

id string

Unique ID for this capture transaction.

Example: "trx_01J2F0ZJ2JW5B63CJFPXRGAB1S"

timestamp string (date-time)

Transaction timestamp in UTC

Example: "2025-05-27T18:49:31Z"

type string

Type of transaction

Allowed: Sale, Auth, Capture, Refund, Void

Example: "Capture"

status TransactionStatus

Allowed: Unknown, Created, Pending, Submitted, Acknowledged, Processing, AwaitingSettlement, Completed, Failed, Abandoned

Example: "Completed"

accountHolder object

Account holder information associated with the transaction

Child attributes

id string required

Account holder ID assigned by the API.

Example: "aho_01JRZPRGFF4J2SZC3HMDBYEN2J"

externalId string required

External account holder ID assigned by your application.

Example: "usr_1234567890123"

contact object

Contact information for the account holder. Only returned for Card Not Present transactions.

Child attributes

name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "60606"

address string

Example: "300 S Wacker Dr"

state string

Example: "IL"

city string

Example: "Chicago"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

paymentMethod object

The payment method used for this transaction.

Child attributes

id string required

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

This field will be present in three scenarios:

As part of a successful Remove Token endpoint response
In token.removed webhook notifications
In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

Physical - A physical payment terminal for Card Present transactions
Virtual - A hosted payment form/iframe for Card Not Present transactions
VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

Child attributes

name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "12345"

address string

Example: "123 Main St"

state string

Example: "NY"

city string

Example: "Anytown"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

cardType string

The type of card used for this transaction:

UNKNOWN - The card type is unknown
DEBIT - Debit Card
VISA - Visa Credit Card
MASTERCARD - MasterCard Credit Card
AMEX - American Express Credit Card
DINERS - Diners Club Credit Card
DISCOVER - Discover Credit Card
JCB - JCB Credit Card
UNIONPAY - UnionPay Credit Card
MAESTRO - Maestro Debit Card
GIFT - Gift Card
CASH - All-cash Transaction
EBT - Electronic Benefits Transfer Card
INTERAC - Interac (Canadian PIN-debit network), Card Present only
OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

For card tokens: Credit or Debit.
For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

invoiceNumber InvoiceNumber

An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.

max length 100

Example: "inv_1234567890123456"

orderNumber OrderNumber

An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.

max length 100

Example: "order_number_1234"

referenceId ReferenceIdForResponse

max length 100

Example: "ref_s192i49i"

originalTransactionId string

Example: "trx_01JWBPE27KHY2K4J7A13ATQ786"

resultCode ResultCode

Result codes:

0 - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)
1003 - The payment terminal is busy or unavailable. (If this error persists, the user may need to close and re-open the Payment Application on the terminal or restart the terminal)
1005 - The specified terminal could not be found.
1010 - The transaction request is pending to become transaction.
2014 - The payment method or card brand is not enabled for the merchant. resultText carries the message, such as ACH payments are not enabled for this merchant. or Visa cards are not enabled for this merchant. The transaction is Completed and failed; do not retry it with the same payment method.
3000 - An unexpected error occurred. Please try again.
3002 - The transaction could not be completed because the payment terminal could not find the related transaction.
3005 - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.
3006 - The transaction could not be completed because the payment terminal is low on battery.
3009 - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.
3010 - The transaction took too long and was cancelled by the application.
3011 - Invalid transaction request. Please consult the documentation for valid transaction requests.
3012 - Invalid transaction request. paymentMethodId is invalid.
3013 - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.
3014 - Invalid amount. Please try your transaction again with an amount greater than $0.
3020 - An unsupported transaction result was received.
4001 - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.
6800 - 3D Secure authentication was rejected by the issuer's ACS (card auth failed, security failure, stolen card, suspected fraud, etc.). Surfaced on declined CNP transactions when formConfig.enable3DSecure: true and the gateway reports a 3D Secure reason; other failures in a 3D Secure session use 6900-6902. See SDK Error Codes for guidance.
6801 - 3D Secure authentication could not be completed because of an upstream technical issue (ACS timeout, directory server unreachable). Retry later or, if merchant policy allows, retry with 3DS disabled.
6802 - The card is not enrolled in 3D Secure. Retry without 3DS only if merchant policy allows; approval is not guaranteed.
6900 - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText. See SDK Error Codes for guidance.
6901 - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision. See SDK Error Codes for guidance.
6902 - The gateway reported no failure but returned no payment token. See SDK Error Codes for guidance.
9998 - The system is not ready to process a transaction.
9999 - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.
1010 - The transaction request is pending customer interaction.
4100 - Cardholder verification is required. Follow threeDsChallenge.redirectUrl and reconcile the final transaction outcome before retrying.
55 - The customer cancelled the hosted payment attempt.

Example: 0

resultText ResultText

Example: "APPROVED"

requestedAmount integer

The requested amount in minor units. Virtual tokenization uses 0; physical tokenization uses a 1-unit authorization.

Example: 1000

approvedAmount integer

The approved amount in minor units. This is 0 for a decline or an outcome that is still in flight. A terminal may adjust the amount, for example by adding a tip.

Example: 1000

transactionResponses array of TransactionResponse

Individual gateway responses, with receipts under each entry. The array can be empty while processing is incomplete.

Child attributes

responseCode ResponseCode

Outcomes:

Approved - 1, 2. For 2, only amountApproved was approved. On a Chargeback transaction, approved means the chargeback took effect: the money went back to the payer.
Declined - 10 to 18. The issuer or bank refused the payment. Do not retry with the same payment details.
Canceled - 54, 55. No money moved.
Pending - 57. The outcome is not final. Wait for the webhook or query the transaction again.
Unknown - 0. No specific code was reported. While status is not Completed, the outcome is not final. On a Completed transaction it is not an approval: read resultCode and resultText for the reason, for example 2014, 6901, or 6902.
Error - every other code. Processing failed for a technical or request reason.

See Transaction response codes.

Response codes:

0 - UNKNOWN
1 - APPROVED - Transaction was approved
2 - PARTIAL_APPROVED - Transaction was partially approved, but not for the full requested amount.
10 - DECLINED - Transaction was declined by the issuer or bank. For Card-Present, the transaction can also be declined offline by the terminal.
11 - INSUFFICIENT_FUNDS - Rejected due to insufficient funds in the account.
12 - CARD_EXPIRED - The card used for the transaction has expired.
13 - FRAUD_SUSPECTED - The transaction was flagged for potential fraud.
14 - INVALID_PAYMENT_INFO - The provided information is invalid (e.g.: card number).
15 - LIMIT_EXCEEDED - Rejected due to reaching a limit (e.g.: credit limit).
16 - VERIFICATION_REQUIRED - Additional customer verification is required for the transaction to proceed (e.g.: 3D Secure).
17 - AUTHENTICATION_FAILED - Rejected due to incorrect PIN or authentication failure.
18 - POLICY_VIOLATION - Rejected due to a violation of the payment gateway's terms of service or policies.
19 - BATCH_EMPTY - Indicates that the batch for processing is empty.
20 - RECORD_NOT_FOUND - Indicates that the requested record for a transaction was not found (e.g.: to VOID a reference).
21 - ALREADY_VOIDED - Indicates that the transaction has already been voided and cannot be processed again.
50 - NETWORK_ERROR - Rejected due to network or communication issues with the payment gateway.
51 - INVALID_ECR_PARAMETER - Payment Terminal or system-specific errors.
52 - NOT_SUPPORTED - Rejected because the requested operation is not supported.
53 - BUSY_OR_UNAVAILABLE - The Payment Terminal, Payment App or system is busy or unavailable.
54 - CANCELLED - Cancelled by the user or merchant.
55 - USER_CANCELLED - Specific to scenarios where the user cancels the transaction.
56 - TIMED_OUT_ON_USER_INPUT - Failed to complete the transaction in time.
57 - PENDING - The transaction is awaiting an asynchronous outcome.

Allowed: 0, 1, 2, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 50, 51, 52, 53, 54, 55, 56, 57

authCode string

The authorization code provided by the card issuer, confirming transaction approval.

Example: "123456"

amountApproved integer

The amount approved for this transaction response.

Example: 1000

approvedAmountBreakdown ApprovedAmountBreakdown

A breakdown of approvedAmount, where each amounts approved on the payment terminal are returned separately. Only returned on Sale, Auth and Capture transactions.

Child attributes

amountGoodsAndServices integer

The approved amount for goods and services.

Example: 900

tax integer

The approved tax amount.

Example: 100

cashback integer

The approved cashback amount.

Example: 0

tip integer

The approved tip amount.

Example: 0

paymentMethod object

The payment method used for this transaction.

Child attributes

id string required

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

This field will be present in three scenarios:

As part of a successful Remove Token endpoint response
In token.removed webhook notifications
In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

Physical - A physical payment terminal for Card Present transactions
Virtual - A hosted payment form/iframe for Card Not Present transactions
VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

Child attributes

name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "12345"

address string

Example: "123 Main St"

state string

Example: "NY"

city string

Example: "Anytown"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

cardType string

The type of card used for this transaction:

UNKNOWN - The card type is unknown
DEBIT - Debit Card
VISA - Visa Credit Card
MASTERCARD - MasterCard Credit Card
AMEX - American Express Credit Card
DINERS - Diners Club Credit Card
DISCOVER - Discover Credit Card
JCB - JCB Credit Card
UNIONPAY - UnionPay Credit Card
MAESTRO - Maestro Debit Card
GIFT - Gift Card
CASH - All-cash Transaction
EBT - Electronic Benefits Transfer Card
INTERAC - Interac (Canadian PIN-debit network), Card Present only
OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

For card tokens: Credit or Debit.
For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

cardType CardType

The type of card used for this transaction:

UNKNOWN - The card type is unknown
DEBIT - Debit Card
VISA - Visa Credit Card
MASTERCARD - MasterCard Credit Card
AMEX - American Express Credit Card
DINERS - Diners Club Credit Card
DISCOVER - Discover Credit Card
JCB - JCB Credit Card
UNIONPAY - UnionPay Credit Card
MAESTRO - Maestro Debit Card
GIFT - Gift Card
CASH - All-cash Transaction
EBT - Electronic Benefits Transfer Card
INTERAC - Interac (Canadian PIN-debit network), Card Present only
OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

avsResult AVSResult

The AVS (Address Verification Service) result. Typically returned on Card Not Present transactions.

A - Address matches, ZIP does not. The first five numerical characters contained in the address match those stored at the VIC or issuer's center. However, the ZIP code does not match.
E - Ineligible transaction.
N - Neither address nor ZIP matches. Neither the first five numerical characters contained in the address match with those stored at the VIC nor issuer's center nor the ZIP code match.
R - Retry (system unavailable or timed out).
S - Card type not supported. The card type for this transaction is not supported by AVS. AVS can verify addresses for Visa cards, MasterCard, proprietary cards, and private label transactions.
U - Address information unavailable.
G - Address information unavailable, International - Visa only, The address information was not available at the VIC or issuer's center.
W - Nine-digit ZIP match, address does not. The nine-digit Postal ZIP code matches that stored at the VIC or card issuer's centre. However, the first five numerical characters contained in the address do not match.
X - Exact match (nine digit ZIP and address). Both the nine-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
Y - Address and five-digit ZIP match. Both the five-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
Z - Five-digit ZIP matches, address does not. The five-digit Postal ZIP code matches that stored at the VIC or card issuer's centre.

Allowed: A, E, N, R, S, U, G, W, X, Y, Z

cvvResult CVVResult

The CVV verification result. Typically returned on Card Not Present transactions.

M - CVV Match
N - CVV No Match
P - Not Processed
S - CVV should be on the card but the merchant indicates it is not.
U - User is unregistered

Allowed: M, N, P, S, U

accountType string

The funding-source classification associated with the payment method used in this transaction.

For credit/debit cards: Credit or Debit. May be null when the classification is unavailable, including on older transactions.
For ACH/EFT bank accounts: Checking or Savings.

The immediate hosted ACH response uses lowercase checking or savings. Retrieved transaction responses normally use Checking or Savings.

Allowed: Credit, Debit, Checking, Savings, checking, savings

Example: "Credit"

hostResponseText string

A meaningful text explaining the response code from the host.

Example: "APPROVED 00"

receipt Receipt

Receipt lines for this transaction response. Card-present responses can contain printable receipt lines; other responses can return an empty lines array.

Child attributes

lines array of string required

The receipt lines.

sourceId string

Identifier of the session or other source that initiated the transaction.

threeDs ThreeDsAuthentication

Child attributes

status string

The authentication outcome to use in your integration. The other threeDs fields provide supporting authentication data.

Allowed: Authenticated, Attempted, NotAuthenticated, Failed, Unavailable, NotEnrolled

Example: "Authenticated"

cavv string

Cardholder Authentication Verification Value. Cryptographic proof that 3DS authentication was performed. Present on frictionless and challenge-completed transactions.

Example: "AAABBkgwVoRhY2tcYlZGAAAAAAA="

eci string

E-commerce Indicator. Indicates 3DS liability-shift status per card scheme:

02 / 05 - Fully authenticated (liability shift to issuer).
01 / 06 - Attempted authentication (partial liability shift).
00 / 07 - Not authenticated (no liability shift).

Example: "05"

xid string

3DS1 transaction identifier. Some issuers still return this under 3DS2 for backward compatibility.

Example: "MDAwMDAwMDAwMDAwMDAwMTM3MDI="

dsTransId string

Directory Server transaction ID (3DS2). Identifies the authentication associated with this card transaction.

Example: "b71a7d5d-cc38-4ce9-80c3-50a7d53271f7"

threeDReasonId string

Issuer-provided reason code when 3DS authentication failed. Populated only on declines. Use status to handle the outcome and threeDReason for the explanation.

Example: "10"

threeDReason string

Human-readable description matching threeDReasonId.

Example: "Stolen Card"

threeDsChallenge ThreeDsChallenge

Present when a token payment requires a cardholder challenge (resultCode: 4100).

Child attributes

redirectUrl string (uri) required

Hosted URL where the cardholder completes the challenge.

followUpToken string required

Opaque token identifying the pending challenge.

balanceAmount integer

The balance that remains to be paid on the transaction. This amount is always an integer in the smallest denomination of the currency (e.g. cents for USD or CAD).

Example: 0

refundableAmount integer

Example: 1000

successfulResponse

{
  "id": "trx_01J2F0ZJ2JW5B63CJFPXRGAB1S",
  "timestamp": "2025-05-27T18:49:31Z",
  "type": "Capture",
  "status": "Completed",
  "accountHolder": {
    "id": "aho_01JRZPRGFF4J2SZC3HMDBYEN2J",
    "externalId": "usr_1234567890123"
  },
  "referenceId": "ref_s192i49i",
  "paymentMethod": {
    "id": "pmt_trm_01JRZPTMTBN41PC3VPQNZ5T3HF",
    "type": "Physical",
    "currency": "USD",
    "description": "Main Store Terminal"
  },
  "invoiceNumber": "inv_1234567890123456",
  "orderNumber": "order_number_1234",
  "resultCode": 0,
  "resultText": "APPROVED",
  "requestedAmount": 1000,
  "approvedAmount": 1000,
  "transactionResponses": [
    {
      "responseCode": 1,
      "authCode": "123456",
      "amountApproved": 1000,
      "approvedAmountBreakdown": {
        "amountGoodsAndServices": 1000,
        "tax": 0,
        "cashback": 0,
        "tip": 0
      },
      "cardType": "VISA",
      "accountType": "Credit",
      "hostResponseText": "APPROVED",
      "receipt": {
        "lines": [
          "     Test Merchant      ",
          "      300 S Wacker      ",
          "         Loop,          ",
          "                        ",
          "                        ",
          " ",
          "TERM #          11000367",
          "RECORD #         0656191",
          "HOST INVOICE #    000038",
          "HOST SEQ #    1720656191",
          "MERCH",
          "INVOICE inv_123456789012",
          "        3456",
          "------------------------",
          "CARD    ************0011",
          "VISA             Contact",
          "07/10/2024      20:03:05",
          "------------------------",
          "CLERK ID               1",
          "   PRE AUTH COMPLETE   ",
          "",
          "",
          "TOTAL         USD $10.00",
          "------------------------",
          "AUTH#:123456       B:171",
          "",
          "        APPROVED        ",
          "       THANK YOU       ",
          " ",
          "     NO CARDHOLDER     ",
          "      VERIFICATION      ",
          "",
          " ",
          " ",
          "",
          "",
          "  Retain this copy for  ",
          "  statement validation  ",
          "",
          "                        ",
          "                        ",
          "                        ",
          "                        ",
          "                        ",
          "     CUSTOMER COPY     ",
          "",
          "     Test Merchant      ",
          "      300 S Wacker      ",
          "         Loop,          ",
          "                        ",
          "                        ",
          " ",
          "TERM #          11000367",
          "RECORD #         0656191",
          "HOST INVOICE #    000038",
          "HOST SEQ #    1720656191",
          "MERCH",
          "INVOICE inv_123456789012",
          "        3456",
          "------------------------",
          "CARD    ************0011",
          "VISA             Contact",
          "07/10/2024      20:03:05",
          "------------------------",
          "CLERK ID               1",
          "   PRE AUTH COMPLETE   ",
          "",
          "",
          "TOTAL         USD $10.00",
          "------------------------",
          "AUTH#:123456       B:171",
          "",
          "        APPROVED        ",
          "       THANK YOU       ",
          " ",
          "     NO CARDHOLDER     ",
          "      VERIFICATION      ",
          "",
          " ",
          " ",
          "",
          "",
          "",
          "",
          "                        ",
          "                        ",
          "                        ",
          "                        ",
          "                        ",
          "     MERCHANT COPY     "
        ]
      }
    }
  ]
}

400

Request Error

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

Example

{
  "code": 2000,
  "status": "Rejected",
  "message": "Capture request is invalid",
  "traceId": "1-687e6e13-1880890d11a9634059a9e735",
  "timestamp": "2025-06-21T16:42:59.3137438Z",
  "errorDetails": [
    {
      "code": 2000,
      "message": "Capture amount of 1000 exceeds the available balance of 0 for transaction ID trx_01J2F0EKHC7HY2R93C8ENBD1FG"
    }
  ]
}

401

Unauthorized response due to an invalid or missing API key.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

UnauthorizedError

{
  "code": 1000,
  "status": "Rejected",
  "message": "API key cannot be empty",
  "traceId": "1-6838be96-74c62f8e2804352739e63476",
  "timestamp": "2025-05-29T20:07:50.4723483Z",
  "errorDetails": []
}

409

The original transaction or token is not ready. Reconcile the existing request before retrying.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

Refund

POST/transactions/refund

Process a referenced refund or void for a previously completed sale or capture transaction. If the transaction is in the current batch, the system will attempt to void it, otherwise it will be refunded resulting in a financial transaction.

Refund limit

The refund amount cannot exceed the original transaction's refundableAmount. Earlier refunds and an ACH chargeback both reduce it. A request over the limit is rejected with HTTP 400, error code 2000, and the message Refund request is invalid; errorDetails[0].message gives the amount and the available balance. After an earlier refund or a chargeback, send an explicit amount.

Webhook Events

The following webhook events will be triggered during the refund process:

refund.completed - when a transaction void or refund for a previously completed transaction is completed.

Request body

The request to refund or void a previously completed transaction.

application/json · RefundRequest

originalTransactionId OriginalTransactionId

The transaction ID (trx_) of the original authorization to capture, or sale/capture to refund. Supply exactly one of originalTransactionId and originalReferenceId.

min length 1 · max length 30

Example: "trx_01J2F0EKHC7HY2R93C8ENBD1FG"

originalReferenceId OriginalReferenceId

min length 1 · max length 100

Example: "ref_s192i49i"

referenceId ReferenceIdForTransactions

max length 100

Example: "ref_s192i49i"

amount AmountToRefund

The requested amount to refund or void. If not specified, the full transaction amount will be refunded or voided. For partial refunds, must be less than the original transaction amount. If you have already performed partial refunds on this transaction, you must provide an explicit amount or an error will be returned.

min 1 · max 999999999

Example: 1000

invoiceNumber InvoiceNumber

An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.

max length 100

Example: "inv_1234567890123456"

orderNumber OrderNumber

An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.

max length 100

Example: "order_number_1234"

Refund using original transaction ID

{
  "originalTransactionId": "trx_01J2F0EKHC7HY2R93C8ENBD1FG",
  "amount": 1000,
  "invoiceNumber": "inv_1234567890123456",
  "orderNumber": "order_number_1234",
  "referenceId": "ref_refund_12345"
}

Refund using original reference ID

{
  "originalReferenceId": "ref_s192i49i",
  "amount": 1000,
  "invoiceNumber": "inv_1234567890123456",
  "orderNumber": "order_number_1234",
  "referenceId": "ref_refund_12345"
}

Responses

200

A successful refund response

application/json · RefundResponse

id string

Unique ID for this refund transaction.

Example: "trx_01J2F0ZJ2JW5B63CJFPXRGAB1S"

timestamp string (date-time)

Transaction timestamp in UTC

Example: "2025-05-27T18:49:31Z"

type string

Type of transaction

Allowed: Sale, Auth, Capture, Refund, Void

Example: "Refund"

status TransactionStatus

Allowed: Unknown, Created, Pending, Submitted, Acknowledged, Processing, AwaitingSettlement, Completed, Failed, Abandoned

Example: "Completed"

accountHolder object

Account holder information associated with the transaction

Child attributes

id string required

Account holder ID assigned by the API.

Example: "aho_01JRZPRGFF4J2SZC3HMDBYEN2J"

externalId string required

External account holder ID assigned by your application.

Example: "usr_1234567890123"

contact object

Contact information for the account holder. Only returned for Card Not Present transactions.

Child attributes

name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "60606"

address string

Example: "300 S Wacker Dr"

state string

Example: "IL"

city string

Example: "Chicago"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

paymentMethod object

The payment method used for this transaction.

Child attributes

id string required

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

This field will be present in three scenarios:

As part of a successful Remove Token endpoint response
In token.removed webhook notifications
In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

Physical - A physical payment terminal for Card Present transactions
Virtual - A hosted payment form/iframe for Card Not Present transactions
VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

Child attributes

name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "12345"

address string

Example: "123 Main St"

state string

Example: "NY"

city string

Example: "Anytown"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

cardType string

The type of card used for this transaction:

UNKNOWN - The card type is unknown
DEBIT - Debit Card
VISA - Visa Credit Card
MASTERCARD - MasterCard Credit Card
AMEX - American Express Credit Card
DINERS - Diners Club Credit Card
DISCOVER - Discover Credit Card
JCB - JCB Credit Card
UNIONPAY - UnionPay Credit Card
MAESTRO - Maestro Debit Card
GIFT - Gift Card
CASH - All-cash Transaction
EBT - Electronic Benefits Transfer Card
INTERAC - Interac (Canadian PIN-debit network), Card Present only
OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

For card tokens: Credit or Debit.
For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

invoiceNumber InvoiceNumber

An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.

max length 100

Example: "inv_1234567890123456"

orderNumber OrderNumber

An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.

max length 100

Example: "order_number_1234"

referenceId ReferenceIdForResponse

max length 100

Example: "ref_s192i49i"

originalTransactionId string

Example: "trx_01JWBPE27KHY2K4J7A13ATQ786"

resultCode ResultCode

Result codes:

0 - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)
1003 - The payment terminal is busy or unavailable. (If this error persists, the user may need to close and re-open the Payment Application on the terminal or restart the terminal)
1005 - The specified terminal could not be found.
1010 - The transaction request is pending to become transaction.
2014 - The payment method or card brand is not enabled for the merchant. resultText carries the message, such as ACH payments are not enabled for this merchant. or Visa cards are not enabled for this merchant. The transaction is Completed and failed; do not retry it with the same payment method.
3000 - An unexpected error occurred. Please try again.
3002 - The transaction could not be completed because the payment terminal could not find the related transaction.
3005 - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.
3006 - The transaction could not be completed because the payment terminal is low on battery.
3009 - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.
3010 - The transaction took too long and was cancelled by the application.
3011 - Invalid transaction request. Please consult the documentation for valid transaction requests.
3012 - Invalid transaction request. paymentMethodId is invalid.
3013 - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.
3014 - Invalid amount. Please try your transaction again with an amount greater than $0.
3020 - An unsupported transaction result was received.
4001 - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.
6800 - 3D Secure authentication was rejected by the issuer's ACS (card auth failed, security failure, stolen card, suspected fraud, etc.). Surfaced on declined CNP transactions when formConfig.enable3DSecure: true and the gateway reports a 3D Secure reason; other failures in a 3D Secure session use 6900-6902. See SDK Error Codes for guidance.
6801 - 3D Secure authentication could not be completed because of an upstream technical issue (ACS timeout, directory server unreachable). Retry later or, if merchant policy allows, retry with 3DS disabled.
6802 - The card is not enrolled in 3D Secure. Retry without 3DS only if merchant policy allows; approval is not guaranteed.
6900 - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText. See SDK Error Codes for guidance.
6901 - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision. See SDK Error Codes for guidance.
6902 - The gateway reported no failure but returned no payment token. See SDK Error Codes for guidance.
9998 - The system is not ready to process a transaction.
9999 - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.
1010 - The transaction request is pending customer interaction.
4100 - Cardholder verification is required. Follow threeDsChallenge.redirectUrl and reconcile the final transaction outcome before retrying.
55 - The customer cancelled the hosted payment attempt.

Example: 0

resultText ResultText

Example: "APPROVED"

requestedAmount integer

The requested amount in minor units. Virtual tokenization uses 0; physical tokenization uses a 1-unit authorization.

Example: 1000

approvedAmount integer

The approved amount in minor units. This is 0 for a decline or an outcome that is still in flight. A terminal may adjust the amount, for example by adding a tip.

Example: 1000

refundableAmount integer

The amount that remains refundable on the original transaction after this refund, in the smallest denomination of the currency. The balance reflects this refund attempt. When the gateway declines the refund, this equals the balance before the attempt.

Example: 0

transactionResponses array of TransactionResponse

Individual gateway responses, with receipts under each entry. The array can be empty while processing is incomplete.

Child attributes

responseCode ResponseCode

Outcomes:

Approved - 1, 2. For 2, only amountApproved was approved. On a Chargeback transaction, approved means the chargeback took effect: the money went back to the payer.
Declined - 10 to 18. The issuer or bank refused the payment. Do not retry with the same payment details.
Canceled - 54, 55. No money moved.
Pending - 57. The outcome is not final. Wait for the webhook or query the transaction again.
Unknown - 0. No specific code was reported. While status is not Completed, the outcome is not final. On a Completed transaction it is not an approval: read resultCode and resultText for the reason, for example 2014, 6901, or 6902.
Error - every other code. Processing failed for a technical or request reason.

See Transaction response codes.

Response codes:

0 - UNKNOWN
1 - APPROVED - Transaction was approved
2 - PARTIAL_APPROVED - Transaction was partially approved, but not for the full requested amount.
10 - DECLINED - Transaction was declined by the issuer or bank. For Card-Present, the transaction can also be declined offline by the terminal.
11 - INSUFFICIENT_FUNDS - Rejected due to insufficient funds in the account.
12 - CARD_EXPIRED - The card used for the transaction has expired.
13 - FRAUD_SUSPECTED - The transaction was flagged for potential fraud.
14 - INVALID_PAYMENT_INFO - The provided information is invalid (e.g.: card number).
15 - LIMIT_EXCEEDED - Rejected due to reaching a limit (e.g.: credit limit).
16 - VERIFICATION_REQUIRED - Additional customer verification is required for the transaction to proceed (e.g.: 3D Secure).
17 - AUTHENTICATION_FAILED - Rejected due to incorrect PIN or authentication failure.
18 - POLICY_VIOLATION - Rejected due to a violation of the payment gateway's terms of service or policies.
19 - BATCH_EMPTY - Indicates that the batch for processing is empty.
20 - RECORD_NOT_FOUND - Indicates that the requested record for a transaction was not found (e.g.: to VOID a reference).
21 - ALREADY_VOIDED - Indicates that the transaction has already been voided and cannot be processed again.
50 - NETWORK_ERROR - Rejected due to network or communication issues with the payment gateway.
51 - INVALID_ECR_PARAMETER - Payment Terminal or system-specific errors.
52 - NOT_SUPPORTED - Rejected because the requested operation is not supported.
53 - BUSY_OR_UNAVAILABLE - The Payment Terminal, Payment App or system is busy or unavailable.
54 - CANCELLED - Cancelled by the user or merchant.
55 - USER_CANCELLED - Specific to scenarios where the user cancels the transaction.
56 - TIMED_OUT_ON_USER_INPUT - Failed to complete the transaction in time.
57 - PENDING - The transaction is awaiting an asynchronous outcome.

Allowed: 0, 1, 2, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 50, 51, 52, 53, 54, 55, 56, 57

authCode string

The authorization code provided by the card issuer, confirming transaction approval.

Example: "123456"

amountApproved integer

The amount approved for this transaction response.

Example: 1000

approvedAmountBreakdown ApprovedAmountBreakdown

A breakdown of approvedAmount, where each amounts approved on the payment terminal are returned separately. Only returned on Sale, Auth and Capture transactions.

Child attributes

amountGoodsAndServices integer

The approved amount for goods and services.

Example: 900

tax integer

The approved tax amount.

Example: 100

cashback integer

The approved cashback amount.

Example: 0

tip integer

The approved tip amount.

Example: 0

paymentMethod object

The payment method used for this transaction.

Child attributes

id string required

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

This field will be present in three scenarios:

As part of a successful Remove Token endpoint response
In token.removed webhook notifications
In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

Physical - A physical payment terminal for Card Present transactions
Virtual - A hosted payment form/iframe for Card Not Present transactions
VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

Child attributes

name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "12345"

address string

Example: "123 Main St"

state string

Example: "NY"

city string

Example: "Anytown"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

cardType string

The type of card used for this transaction:

UNKNOWN - The card type is unknown
DEBIT - Debit Card
VISA - Visa Credit Card
MASTERCARD - MasterCard Credit Card
AMEX - American Express Credit Card
DINERS - Diners Club Credit Card
DISCOVER - Discover Credit Card
JCB - JCB Credit Card
UNIONPAY - UnionPay Credit Card
MAESTRO - Maestro Debit Card
GIFT - Gift Card
CASH - All-cash Transaction
EBT - Electronic Benefits Transfer Card
INTERAC - Interac (Canadian PIN-debit network), Card Present only
OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

For card tokens: Credit or Debit.
For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

cardType CardType

The type of card used for this transaction:

UNKNOWN - The card type is unknown
DEBIT - Debit Card
VISA - Visa Credit Card
MASTERCARD - MasterCard Credit Card
AMEX - American Express Credit Card
DINERS - Diners Club Credit Card
DISCOVER - Discover Credit Card
JCB - JCB Credit Card
UNIONPAY - UnionPay Credit Card
MAESTRO - Maestro Debit Card
GIFT - Gift Card
CASH - All-cash Transaction
EBT - Electronic Benefits Transfer Card
INTERAC - Interac (Canadian PIN-debit network), Card Present only
OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

avsResult AVSResult

The AVS (Address Verification Service) result. Typically returned on Card Not Present transactions.

A - Address matches, ZIP does not. The first five numerical characters contained in the address match those stored at the VIC or issuer's center. However, the ZIP code does not match.
E - Ineligible transaction.
N - Neither address nor ZIP matches. Neither the first five numerical characters contained in the address match with those stored at the VIC nor issuer's center nor the ZIP code match.
R - Retry (system unavailable or timed out).
S - Card type not supported. The card type for this transaction is not supported by AVS. AVS can verify addresses for Visa cards, MasterCard, proprietary cards, and private label transactions.
U - Address information unavailable.
G - Address information unavailable, International - Visa only, The address information was not available at the VIC or issuer's center.
W - Nine-digit ZIP match, address does not. The nine-digit Postal ZIP code matches that stored at the VIC or card issuer's centre. However, the first five numerical characters contained in the address do not match.
X - Exact match (nine digit ZIP and address). Both the nine-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
Y - Address and five-digit ZIP match. Both the five-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
Z - Five-digit ZIP matches, address does not. The five-digit Postal ZIP code matches that stored at the VIC or card issuer's centre.

Allowed: A, E, N, R, S, U, G, W, X, Y, Z

cvvResult CVVResult

The CVV verification result. Typically returned on Card Not Present transactions.

M - CVV Match
N - CVV No Match
P - Not Processed
S - CVV should be on the card but the merchant indicates it is not.
U - User is unregistered

Allowed: M, N, P, S, U

accountType string

The funding-source classification associated with the payment method used in this transaction.

For credit/debit cards: Credit or Debit. May be null when the classification is unavailable, including on older transactions.
For ACH/EFT bank accounts: Checking or Savings.

The immediate hosted ACH response uses lowercase checking or savings. Retrieved transaction responses normally use Checking or Savings.

Allowed: Credit, Debit, Checking, Savings, checking, savings

Example: "Credit"

hostResponseText string

A meaningful text explaining the response code from the host.

Example: "APPROVED 00"

receipt Receipt

Receipt lines for this transaction response. Card-present responses can contain printable receipt lines; other responses can return an empty lines array.

Child attributes

lines array of string required

The receipt lines.

sourceId string

Identifier of the session or other source that initiated the transaction.

threeDs ThreeDsAuthentication

Child attributes

status string

The authentication outcome to use in your integration. The other threeDs fields provide supporting authentication data.

Allowed: Authenticated, Attempted, NotAuthenticated, Failed, Unavailable, NotEnrolled

Example: "Authenticated"

cavv string

Cardholder Authentication Verification Value. Cryptographic proof that 3DS authentication was performed. Present on frictionless and challenge-completed transactions.

Example: "AAABBkgwVoRhY2tcYlZGAAAAAAA="

eci string

E-commerce Indicator. Indicates 3DS liability-shift status per card scheme:

02 / 05 - Fully authenticated (liability shift to issuer).
01 / 06 - Attempted authentication (partial liability shift).
00 / 07 - Not authenticated (no liability shift).

Example: "05"

xid string

3DS1 transaction identifier. Some issuers still return this under 3DS2 for backward compatibility.

Example: "MDAwMDAwMDAwMDAwMDAwMTM3MDI="

dsTransId string

Directory Server transaction ID (3DS2). Identifies the authentication associated with this card transaction.

Example: "b71a7d5d-cc38-4ce9-80c3-50a7d53271f7"

threeDReasonId string

Issuer-provided reason code when 3DS authentication failed. Populated only on declines. Use status to handle the outcome and threeDReason for the explanation.

Example: "10"

threeDReason string

Human-readable description matching threeDReasonId.

Example: "Stolen Card"

threeDsChallenge ThreeDsChallenge

Present when a token payment requires a cardholder challenge (resultCode: 4100).

Child attributes

redirectUrl string (uri) required

Hosted URL where the cardholder completes the challenge.

followUpToken string required

Opaque token identifying the pending challenge.

balanceAmount integer

The balance that remains to be paid on the transaction. This amount is always an integer in the smallest denomination of the currency (e.g. cents for USD or CAD).

Example: 0

successfulResponse

{
  "id": "trx_01J2F0ZJ2JW5B63CJFPXRGAB1S",
  "timestamp": "2025-05-27T18:49:31Z",
  "type": "Refund",
  "status": "Completed",
  "accountHolder": {
    "id": "aho_01JRZPRGFF4J2SZC3HMDBYEN2J",
    "externalId": "usr_1234567890123"
  },
  "referenceId": "ref_s192i49i",
  "paymentMethod": {
    "id": "pmt_trm_01JRZPTMTBN41PC3VPQNZ5T3HF",
    "type": "Physical",
    "currency": "USD",
    "description": "Main Store Terminal"
  },
  "invoiceNumber": "inv_1234567890123456",
  "orderNumber": "order_number_1234",
  "resultCode": 0,
  "resultText": "APPROVED",
  "requestedAmount": 1000,
  "approvedAmount": 1000,
  "transactionResponses": [
    {
      "responseCode": 1,
      "authCode": "123456",
      "amountApproved": 1000,
      "paymentMethod": {
        "id": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J",
        "type": "Token",
        "currency": "USD",
        "cardType": "VISA",
        "maskedCardNumber": "************0011"
      },
      "receipt": {
        "lines": []
      }
    }
  ],
  "refundableAmount": 0
}

400

Request Error

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

Example

{
  "code": 2000,
  "status": "Rejected",
  "message": "Refund request is invalid",
  "traceId": "1-687e7080-78cb54a51c8121ee32df9e35",
  "timestamp": "2025-06-21T16:53:20.9949208Z",
  "errorDetails": [
    {
      "code": 2000,
      "message": "Refund amount of 1000 exceeds the available balance of 0 for transaction ID trx_01J2F0EKHC7HY2R93C8ENBD1FG"
    }
  ]
}

401

Unauthorized response due to an invalid or missing API key.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

UnauthorizedError

{
  "code": 1000,
  "status": "Rejected",
  "message": "API key cannot be empty",
  "traceId": "1-6838be96-74c62f8e2804352739e63476",
  "timestamp": "2025-05-29T20:07:50.4723483Z",
  "errorDetails": []
}

409

The original transaction or token is not ready. Reconcile the existing request before retrying.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

Void

POST/transactions/void

Process a void for a previously completed sale, authorization or capture transaction. Voids are typically only available for transactions in the current batch (same day). If the batch has been closed, the void will fail.

Restrictions

ACH Transactions: ACH (bank transfer) transactions cannot be voided. Attempting to void an ACH transaction will return an error with code 2010 and message "Cannot void an ACH transaction". Use the refund endpoint instead.
Time Limit: Non-auth transactions can only be voided within 24 hours of the original transaction.

Webhook Events

The following webhook events will be triggered during the void process:

void.completed - when a transaction void for a previously completed transaction is completed.

Request body

The request to void a previously completed transaction.

application/json · VoidRequest

originalTransactionId OriginalTransactionIdForVoid

The unique transaction ID of the original transaction to be voided. This is the 'id' value returned from a previous sale, authorization, or capture transaction. Use this parameter if you prefer to rely on system-generated transaction IDs rather than managing your own reference system. Either originalTransactionId or originalReferenceId must be provided.

The original transaction must belong to the merchant that owns the API key used for this request. A transaction belonging to a different merchant is rejected as not found, exactly as if the ID did not exist.

min length 1 · max length 30

Example: "trx_01J2F0EKHC7HY2R93C8ENBD1FG"

originalReferenceId OriginalReferenceIdForVoid

The reference ID of the original transaction to be voided. This should match the referenceId from a previous sale, authorization, or capture transaction (either a custom reference ID you provided or one that was generated automatically by the system). Use this parameter if you want to link transactions using reference IDs rather than system transaction IDs. Either originalTransactionId or originalReferenceId must be provided.

min length 1 · max length 100

Example: "ref_s192i49i"

referenceId ReferenceIdForVoid

An optional custom reference ID for this void transaction. Include this if you want to use your own reference system for linking transactions together. Use a unique value per merchant. This field is not an idempotency key and reusing it does not replay the prior response. If not provided, a unique reference ID will be generated automatically by the system.

max length 100

Example: "ref_void_12345"

invoiceNumber InvoiceNumber

An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.

max length 100

Example: "inv_1234567890123456"

orderNumber OrderNumber

An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.

max length 100

Example: "order_number_1234"

Void using original transaction ID

{
  "originalTransactionId": "trx_01J2F0EKHC7HY2R93C8ENBD1FG",
  "invoiceNumber": "inv_1234567890123456",
  "orderNumber": "order_number_1234",
  "referenceId": "ref_void_12345"
}

Void using original reference ID

{
  "originalReferenceId": "ref_s192i49i",
  "invoiceNumber": "inv_1234567890123456",
  "orderNumber": "order_number_1234",
  "referenceId": "ref_void_12345"
}

Responses

200

A successful void response

application/json · VoidResponse

id string

Unique ID for this void transaction.

Example: "trx_01J2F0ZJ2JW5B63CJFPXRGAB1S"

timestamp string (date-time)

Transaction timestamp in UTC

Example: "2025-05-27T18:49:31Z"

type string

Type of transaction

Allowed: Sale, Auth, Capture, Refund, Void

Example: "Void"

status TransactionStatus

Allowed: Unknown, Created, Pending, Submitted, Acknowledged, Processing, AwaitingSettlement, Completed, Failed, Abandoned

Example: "Completed"

accountHolder object

Account holder information associated with the transaction

Child attributes

id string required

Account holder ID assigned by the API.

Example: "aho_01JRZPRGFF4J2SZC3HMDBYEN2J"

externalId string required

External account holder ID assigned by your application.

Example: "usr_1234567890123"

contact object

Contact information for the account holder. Only returned for Card Not Present transactions.

Child attributes

name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "60606"

address string

Example: "300 S Wacker Dr"

state string

Example: "IL"

city string

Example: "Chicago"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

paymentMethod object

The payment method used for this transaction.

Child attributes

id string required

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

This field will be present in three scenarios:

As part of a successful Remove Token endpoint response
In token.removed webhook notifications
In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

Physical - A physical payment terminal for Card Present transactions
Virtual - A hosted payment form/iframe for Card Not Present transactions
VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

Child attributes

name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "12345"

address string

Example: "123 Main St"

state string

Example: "NY"

city string

Example: "Anytown"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

cardType string

The type of card used for this transaction:

UNKNOWN - The card type is unknown
DEBIT - Debit Card
VISA - Visa Credit Card
MASTERCARD - MasterCard Credit Card
AMEX - American Express Credit Card
DINERS - Diners Club Credit Card
DISCOVER - Discover Credit Card
JCB - JCB Credit Card
UNIONPAY - UnionPay Credit Card
MAESTRO - Maestro Debit Card
GIFT - Gift Card
CASH - All-cash Transaction
EBT - Electronic Benefits Transfer Card
INTERAC - Interac (Canadian PIN-debit network), Card Present only
OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

For card tokens: Credit or Debit.
For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

invoiceNumber InvoiceNumber

An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.

max length 100

Example: "inv_1234567890123456"

orderNumber OrderNumber

An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.

max length 100

Example: "order_number_1234"

referenceId ReferenceIdForResponse

max length 100

Example: "ref_s192i49i"

originalTransactionId string

Example: "trx_01JWBPE27KHY2K4J7A13ATQ786"

resultCode ResultCode

Result codes:

0 - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)
1003 - The payment terminal is busy or unavailable. (If this error persists, the user may need to close and re-open the Payment Application on the terminal or restart the terminal)
1005 - The specified terminal could not be found.
1010 - The transaction request is pending to become transaction.
2014 - The payment method or card brand is not enabled for the merchant. resultText carries the message, such as ACH payments are not enabled for this merchant. or Visa cards are not enabled for this merchant. The transaction is Completed and failed; do not retry it with the same payment method.
3000 - An unexpected error occurred. Please try again.
3002 - The transaction could not be completed because the payment terminal could not find the related transaction.
3005 - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.
3006 - The transaction could not be completed because the payment terminal is low on battery.
3009 - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.
3010 - The transaction took too long and was cancelled by the application.
3011 - Invalid transaction request. Please consult the documentation for valid transaction requests.
3012 - Invalid transaction request. paymentMethodId is invalid.
3013 - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.
3014 - Invalid amount. Please try your transaction again with an amount greater than $0.
3020 - An unsupported transaction result was received.
4001 - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.
6800 - 3D Secure authentication was rejected by the issuer's ACS (card auth failed, security failure, stolen card, suspected fraud, etc.). Surfaced on declined CNP transactions when formConfig.enable3DSecure: true and the gateway reports a 3D Secure reason; other failures in a 3D Secure session use 6900-6902. See SDK Error Codes for guidance.
6801 - 3D Secure authentication could not be completed because of an upstream technical issue (ACS timeout, directory server unreachable). Retry later or, if merchant policy allows, retry with 3DS disabled.
6802 - The card is not enrolled in 3D Secure. Retry without 3DS only if merchant policy allows; approval is not guaranteed.
6900 - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText. See SDK Error Codes for guidance.
6901 - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision. See SDK Error Codes for guidance.
6902 - The gateway reported no failure but returned no payment token. See SDK Error Codes for guidance.
9998 - The system is not ready to process a transaction.
9999 - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.
1010 - The transaction request is pending customer interaction.
4100 - Cardholder verification is required. Follow threeDsChallenge.redirectUrl and reconcile the final transaction outcome before retrying.
55 - The customer cancelled the hosted payment attempt.

Example: 0

resultText ResultText

Example: "APPROVED"

requestedAmount integer

The requested amount in minor units. Virtual tokenization uses 0; physical tokenization uses a 1-unit authorization.

Example: 1000

approvedAmount integer

The approved amount in minor units. This is 0 for a decline or an outcome that is still in flight. A terminal may adjust the amount, for example by adding a tip.

Example: 1000

transactionResponses array of TransactionResponse

Individual gateway responses, with receipts under each entry. The array can be empty while processing is incomplete.

Child attributes

responseCode ResponseCode

Outcomes:

Approved - 1, 2. For 2, only amountApproved was approved. On a Chargeback transaction, approved means the chargeback took effect: the money went back to the payer.
Declined - 10 to 18. The issuer or bank refused the payment. Do not retry with the same payment details.
Canceled - 54, 55. No money moved.
Pending - 57. The outcome is not final. Wait for the webhook or query the transaction again.
Unknown - 0. No specific code was reported. While status is not Completed, the outcome is not final. On a Completed transaction it is not an approval: read resultCode and resultText for the reason, for example 2014, 6901, or 6902.
Error - every other code. Processing failed for a technical or request reason.

See Transaction response codes.

Response codes:

0 - UNKNOWN
1 - APPROVED - Transaction was approved
2 - PARTIAL_APPROVED - Transaction was partially approved, but not for the full requested amount.
10 - DECLINED - Transaction was declined by the issuer or bank. For Card-Present, the transaction can also be declined offline by the terminal.
11 - INSUFFICIENT_FUNDS - Rejected due to insufficient funds in the account.
12 - CARD_EXPIRED - The card used for the transaction has expired.
13 - FRAUD_SUSPECTED - The transaction was flagged for potential fraud.
14 - INVALID_PAYMENT_INFO - The provided information is invalid (e.g.: card number).
15 - LIMIT_EXCEEDED - Rejected due to reaching a limit (e.g.: credit limit).
16 - VERIFICATION_REQUIRED - Additional customer verification is required for the transaction to proceed (e.g.: 3D Secure).
17 - AUTHENTICATION_FAILED - Rejected due to incorrect PIN or authentication failure.
18 - POLICY_VIOLATION - Rejected due to a violation of the payment gateway's terms of service or policies.
19 - BATCH_EMPTY - Indicates that the batch for processing is empty.
20 - RECORD_NOT_FOUND - Indicates that the requested record for a transaction was not found (e.g.: to VOID a reference).
21 - ALREADY_VOIDED - Indicates that the transaction has already been voided and cannot be processed again.
50 - NETWORK_ERROR - Rejected due to network or communication issues with the payment gateway.
51 - INVALID_ECR_PARAMETER - Payment Terminal or system-specific errors.
52 - NOT_SUPPORTED - Rejected because the requested operation is not supported.
53 - BUSY_OR_UNAVAILABLE - The Payment Terminal, Payment App or system is busy or unavailable.
54 - CANCELLED - Cancelled by the user or merchant.
55 - USER_CANCELLED - Specific to scenarios where the user cancels the transaction.
56 - TIMED_OUT_ON_USER_INPUT - Failed to complete the transaction in time.
57 - PENDING - The transaction is awaiting an asynchronous outcome.

Allowed: 0, 1, 2, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 50, 51, 52, 53, 54, 55, 56, 57

authCode string

The authorization code provided by the card issuer, confirming transaction approval.

Example: "123456"

amountApproved integer

The amount approved for this transaction response.

Example: 1000

approvedAmountBreakdown ApprovedAmountBreakdown

A breakdown of approvedAmount, where each amounts approved on the payment terminal are returned separately. Only returned on Sale, Auth and Capture transactions.

Child attributes

amountGoodsAndServices integer

The approved amount for goods and services.

Example: 900

tax integer

The approved tax amount.

Example: 100

cashback integer

The approved cashback amount.

Example: 0

tip integer

The approved tip amount.

Example: 0

paymentMethod object

The payment method used for this transaction.

Child attributes

id string required

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

This field will be present in three scenarios:

As part of a successful Remove Token endpoint response
In token.removed webhook notifications
In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

Physical - A physical payment terminal for Card Present transactions
Virtual - A hosted payment form/iframe for Card Not Present transactions
VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

Child attributes

name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "12345"

address string

Example: "123 Main St"

state string

Example: "NY"

city string

Example: "Anytown"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

cardType string

The type of card used for this transaction:

UNKNOWN - The card type is unknown
DEBIT - Debit Card
VISA - Visa Credit Card
MASTERCARD - MasterCard Credit Card
AMEX - American Express Credit Card
DINERS - Diners Club Credit Card
DISCOVER - Discover Credit Card
JCB - JCB Credit Card
UNIONPAY - UnionPay Credit Card
MAESTRO - Maestro Debit Card
GIFT - Gift Card
CASH - All-cash Transaction
EBT - Electronic Benefits Transfer Card
INTERAC - Interac (Canadian PIN-debit network), Card Present only
OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

For card tokens: Credit or Debit.
For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

cardType CardType

The type of card used for this transaction:

UNKNOWN - The card type is unknown
DEBIT - Debit Card
VISA - Visa Credit Card
MASTERCARD - MasterCard Credit Card
AMEX - American Express Credit Card
DINERS - Diners Club Credit Card
DISCOVER - Discover Credit Card
JCB - JCB Credit Card
UNIONPAY - UnionPay Credit Card
MAESTRO - Maestro Debit Card
GIFT - Gift Card
CASH - All-cash Transaction
EBT - Electronic Benefits Transfer Card
INTERAC - Interac (Canadian PIN-debit network), Card Present only
OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

avsResult AVSResult

The AVS (Address Verification Service) result. Typically returned on Card Not Present transactions.

A - Address matches, ZIP does not. The first five numerical characters contained in the address match those stored at the VIC or issuer's center. However, the ZIP code does not match.
E - Ineligible transaction.
N - Neither address nor ZIP matches. Neither the first five numerical characters contained in the address match with those stored at the VIC nor issuer's center nor the ZIP code match.
R - Retry (system unavailable or timed out).
S - Card type not supported. The card type for this transaction is not supported by AVS. AVS can verify addresses for Visa cards, MasterCard, proprietary cards, and private label transactions.
U - Address information unavailable.
G - Address information unavailable, International - Visa only, The address information was not available at the VIC or issuer's center.
W - Nine-digit ZIP match, address does not. The nine-digit Postal ZIP code matches that stored at the VIC or card issuer's centre. However, the first five numerical characters contained in the address do not match.
X - Exact match (nine digit ZIP and address). Both the nine-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
Y - Address and five-digit ZIP match. Both the five-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
Z - Five-digit ZIP matches, address does not. The five-digit Postal ZIP code matches that stored at the VIC or card issuer's centre.

Allowed: A, E, N, R, S, U, G, W, X, Y, Z

cvvResult CVVResult

The CVV verification result. Typically returned on Card Not Present transactions.

M - CVV Match
N - CVV No Match
P - Not Processed
S - CVV should be on the card but the merchant indicates it is not.
U - User is unregistered

Allowed: M, N, P, S, U

accountType string

The funding-source classification associated with the payment method used in this transaction.

For credit/debit cards: Credit or Debit. May be null when the classification is unavailable, including on older transactions.
For ACH/EFT bank accounts: Checking or Savings.

The immediate hosted ACH response uses lowercase checking or savings. Retrieved transaction responses normally use Checking or Savings.

Allowed: Credit, Debit, Checking, Savings, checking, savings

Example: "Credit"

hostResponseText string

A meaningful text explaining the response code from the host.

Example: "APPROVED 00"

receipt Receipt

Receipt lines for this transaction response. Card-present responses can contain printable receipt lines; other responses can return an empty lines array.

Child attributes

lines array of string required

The receipt lines.

sourceId string

Identifier of the session or other source that initiated the transaction.

threeDs ThreeDsAuthentication

Child attributes

status string

The authentication outcome to use in your integration. The other threeDs fields provide supporting authentication data.

Allowed: Authenticated, Attempted, NotAuthenticated, Failed, Unavailable, NotEnrolled

Example: "Authenticated"

cavv string

Cardholder Authentication Verification Value. Cryptographic proof that 3DS authentication was performed. Present on frictionless and challenge-completed transactions.

Example: "AAABBkgwVoRhY2tcYlZGAAAAAAA="

eci string

E-commerce Indicator. Indicates 3DS liability-shift status per card scheme:

02 / 05 - Fully authenticated (liability shift to issuer).
01 / 06 - Attempted authentication (partial liability shift).
00 / 07 - Not authenticated (no liability shift).

Example: "05"

xid string

3DS1 transaction identifier. Some issuers still return this under 3DS2 for backward compatibility.

Example: "MDAwMDAwMDAwMDAwMDAwMTM3MDI="

dsTransId string

Directory Server transaction ID (3DS2). Identifies the authentication associated with this card transaction.

Example: "b71a7d5d-cc38-4ce9-80c3-50a7d53271f7"

threeDReasonId string

Issuer-provided reason code when 3DS authentication failed. Populated only on declines. Use status to handle the outcome and threeDReason for the explanation.

Example: "10"

threeDReason string

Human-readable description matching threeDReasonId.

Example: "Stolen Card"

threeDsChallenge ThreeDsChallenge

Present when a token payment requires a cardholder challenge (resultCode: 4100).

Child attributes

redirectUrl string (uri) required

Hosted URL where the cardholder completes the challenge.

followUpToken string required

Opaque token identifying the pending challenge.

balanceAmount integer

The balance that remains to be paid on the transaction. This amount is always an integer in the smallest denomination of the currency (e.g. cents for USD or CAD).

Example: 0

successfulResponse

{
  "id": "trx_01J2F0ZJ2JW5B63CJFPXRGAB1S",
  "timestamp": "2025-05-27T18:49:31Z",
  "type": "Void",
  "status": "Completed",
  "accountHolder": {
    "id": "aho_01JRZPRGFF4J2SZC3HMDBYEN2J",
    "externalId": "usr_1234567890123"
  },
  "referenceId": "ref_s192i49i",
  "paymentMethod": {
    "id": "pmt_trm_01JRZPTMTBN41PC3VPQNZ5T3HF",
    "type": "Physical",
    "currency": "USD",
    "description": "Main Store Terminal"
  },
  "invoiceNumber": "inv_1234567890123456",
  "orderNumber": "order_number_1234",
  "resultCode": 0,
  "resultText": "APPROVED",
  "requestedAmount": 1000,
  "approvedAmount": 1000,
  "transactionResponses": [
    {
      "responseCode": 1,
      "authCode": "123456",
      "amountApproved": 1000,
      "paymentMethod": {
        "id": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J",
        "type": "Token",
        "currency": "USD",
        "cardType": "VISA",
        "maskedCardNumber": "************0011"
      },
      "receipt": {
        "lines": []
      }
    }
  ]
}

400

Request Error

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

Transaction already voided

{
  "code": 2000,
  "status": "Rejected",
  "message": "Void request is invalid",
  "traceId": "1-687d8c7d-1da33e5604b964d92e9b7dd3",
  "timestamp": "2025-06-21T00:40:29.4532741Z",
  "errorDetails": [
    {
      "code": 2000,
      "message": "Original transaction ID trx_01J2F0EKHC7HY2R93C8ENBD1FG has already been voided."
    }
  ]
}

ACH transactions cannot be voided

{
  "code": 2010,
  "status": "Rejected",
  "message": "Cannot void an ACH transaction",
  "traceId": "1-6963f228-5dd5f9b40dda80ed4e181211",
  "timestamp": "2025-06-21T00:40:29.4532741Z",
  "errorDetails": []
}

401

Unauthorized response due to an invalid or missing API key.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

UnauthorizedError

{
  "code": 1000,
  "status": "Rejected",
  "message": "API key cannot be empty",
  "traceId": "1-6838be96-74c62f8e2804352739e63476",
  "timestamp": "2025-05-29T20:07:50.4723483Z",
  "errorDetails": []
}

409

The original transaction or token is not ready. Reconcile the existing request before retrying.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

Unreferenced Refund (Card Present) (unavailable)

POST/transactions/unreferenced-physical-refund

This operation is currently disabled. Every request returns 401 Unauthorized, including requests with a valid API key. Use POST /transactions/refund with an original transaction instead.

Request body

The request to process an unreferenced refund using a physical payment terminal.

application/json · UnreferencedPhysicalRefundRequest

amount AmountToRefundUnreferenced required

The requested amount to refund.

min 1 · max 999999999

Example: 1000

paymentMethodId string

The ID of the physical payment terminal that will process this Card Present unreferenced refund.

Example format: pmt_trm_01JRZPTMTBN41PC3VPQNZ5T3HF
Omit only when the merchant has a configured default for this operation or a single resolvable payment method.
Otherwise, provide an explicit payment method ID.

You can retrieve all available physical payment terminal IDs for your account using the GET /payment-methods endpoint.

max length 35

Example: "pmt_trm_01JRZPTMTBN41PC3VPQNZ5T3HF"

invoiceNumber InvoiceNumberCardPresent

An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response and will appear on the receipt.

Card Present Limit: Maximum length is 20 characters. If this limit is exceeded, the API will return a validation error.

max length 20

Example: "inv_1234567890123456"

orderNumber OrderNumber

An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.

max length 100

Example: "order_number_1234"

referenceId ReferenceIdForTransactions

max length 100

Example: "ref_s192i49i"

Unreferenced Card Present refund request example

{
  "amount": 1000,
  "paymentMethodId": "pmt_trm_01JRZPTMTBN41PC3VPQNZ5T3HF",
  "invoiceNumber": "inv_1234567890123456",
  "orderNumber": "order_number_1234",
  "referenceId": "ref_s192i49i"
}

Responses

401

This operation is disabled.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

Unreferenced Refund (Card Not Present) (unavailable)

POST/transactions/unreferenced-virtual-refund

This operation is currently disabled. Every request returns 401 Unauthorized, including requests with a valid API key. Use POST /transactions/refund with an original transaction instead.

Request body

The request to process an unreferenced refund using a hosted payment form / iframe.

application/json · UnreferencedVirtualRefundRequest

amount AmountToRefundUnreferenced required

The requested amount to refund.

min 1 · max 999999999

Example: 1000

paymentMethodId string

The ID of the hosted payment form / iframe that will collect card information for this Card Not Present unreferenced refund.

Example format: pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS
Omit only when the merchant has a configured default for this operation or a single resolvable payment method.
Otherwise, provide an explicit payment method ID.

You can retrieve all available hosted payment form IDs for your account using the GET /payment-methods endpoint.

max length 35

Example: "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS"

invoiceNumber InvoiceNumber

An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.

max length 100

Example: "inv_1234567890123456"

orderNumber OrderNumber

An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.

max length 100

Example: "order_number_1234"

referenceId ReferenceIdForTransactions

max length 100

Example: "ref_s192i49i"

returnUrl string

max length 1000

Example: "https://merchant.example.com/refund-complete"

useJavaScriptCallback boolean

Example: true

Unreferenced Card Not Present refund request example

{
  "amount": 1000,
  "paymentMethodId": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
  "invoiceNumber": "inv_1234567890123456",
  "orderNumber": "order_number_1234",
  "referenceId": "ref_s192i49i",
  "useJavaScriptCallback": true
}

Responses

401

This operation is disabled.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."