Tokens

Endpoints for creating and removing tokenized payment methods

Create Token (Card Present)

POST/payment-methods/physical

Tokenize a card using a physical terminal. A $0 authorization will occur to validate the card. If valid, the card and expiration date will be tokenized and stored and a paymentMethodId will be returned for future Card On File transactions.

Webhook Events

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

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

Request body

The request to tokenize a card using a physical terminal.

application/json · CardOnFileAddRequest

paymentMethodId string

The ID of the payment method (physical terminal) to use for adding a card.

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"

referenceId ReferenceIdForTokens

An optional custom reference ID to tag and track this token operation. 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_add_card_12345"

Card On File Add request example

{
  "paymentMethodId": "pmt_trm_01JRZPTMTBN41PC3VPQNZ5T3HF",
  "referenceId": "ref_add_card_12345"
}

Responses

200

A successful card tokenization response

application/json · CardOnFileAddResponse

id string

Unique ID for this card tokenization 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: "Auth"

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"

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"

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: 1

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: 1

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

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.

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.

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.

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.

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

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"

successfulResponse

{
  "id": "trx_01J2F0ZJ2JW5B63CJFPXRGAB1S",
  "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",
  "referenceId": "ref_add_card_12345",
  "resultCode": 0,
  "resultText": "APPROVED",
  "requestedAmount": 1,
  "approvedAmount": 1,
  "balanceAmount": 0,
  "transactionResponses": [
    {
      "responseCode": 1,
      "authCode": "123456",
      "amountApproved": 1,
      "approvedAmountBreakdown": {
        "amountGoodsAndServices": 1,
        "tax": 0,
        "cashback": 0,
        "tip": 0
      },
      "paymentMethod": {
        "id": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J",
        "type": "Token",
        "currency": "USD",
        "cardType": "VISA",
        "maskedCardNumber": "************0011"
      },
      "cardType": "VISA",
      "accountType": "Credit",
      "receipt": {
        "lines": [
          "     Test Merchant      ",
          "      300 S Wacker      ",
          "         Loop,          ",
          "                        ",
          "                        ",
          " ",
          "TERM #          11000367",
          "RECORD #         0656191",
          "HOST INVOICE #    000038",
          "HOST SEQ #    1720656191",
          "MERCH",
          "INVOICE inv_123456789012",
          "        34567890",
          "------------------------",
          "CARD    ************0011",
          "VISA             Contact",
          "07/10/2024      20:03:05",
          "------------------------",
          "CLERK ID               1",
          "        PRE AUTH        ",
          "",
          "",
          "TOTAL         USD  $0.01",
          "------------------------",
          "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",
          "        34567890",
          "------------------------",
          "CARD    ************0011",
          "VISA             Contact",
          "07/10/2024      20:03:05",
          "------------------------",
          "CLERK ID               1",
          "        PRE AUTH        ",
          "",
          "",
          "TOTAL         USD  $0.01",
          "------------------------",
          "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

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

Example

{
  "code": 2000,
  "status": "Rejected",
  "message": "One or more validation errors occurred.",
  "traceId": "1-6838bcce-5c0074e82ac7170d4f990d87",
  "timestamp": "2025-05-29T20:00:15.5752808Z",
  "errorDetails": [
    {
      "code": 2000,
      "field": "paymentMethodId",
      "message": "Request validation failed",
      "details": "'PaymentMethodId' must not be empty."
    }
  ]
}

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": []
}

Create Token (Card Not Present)

POST/payment-methods/virtual

Tokenize a card or ACH bank account using a hosted payment form/iframe. This POST request initiates a tokenization session and returns a short-lived iframe URL to embed in your 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 tokenization result will be delivered via the Token Created webhook.

Payment Method Types

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

Virtual (Card): A $0 authorization will occur to validate the card. If valid, a tokenized card ID will be stored and a paymentMethodId will be returned for future Card On File transactions.
VirtualAch (ACH Bank Account): The bank account information will be tokenized for future ACH transactions.

ACH Tokenization

When using an ACH payment method (VirtualAch):

No verification is performed on the bank account during tokenization. The account details are stored as provided.
Verification of account validity occurs only when a subsequent sale transaction is processed.
The tokenized ACH payment method can be used for future token sales via the /transactions/token-sale endpoint.
ACH tokens have restrictions and cannot be used for authorization, void, or subscription transactions.

Account Holder Integration

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

Managing payment methods per customer using your own identifiers
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 tokenization process:

auth.completed - when a $0 authorization is processed and completed (card only).
token.created - when a card or ACH account is tokenized and stored as a payment method.

Request body

The request to tokenize a card using a hosted payment form / iframe.

application/json · CardOnFileVirtualAddRequest

paymentMethodId string

The ID of the payment method (hosted payment form/iframe) to use for adding a card.

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 payment method IDs for your account using the GET /payment-methods endpoint.

max length 35

Example: "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS"

referenceId ReferenceIdForTokens

max length 100

Example: "ref_add_card_12345"

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 Token Creation request example

{
  "paymentMethodId": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
  "referenceId": "ref_add_card_12345",
  "useJavaScriptCallback": true
}

Token Creation with minimal billing (country and ZIP/postal code)

{
  "paymentMethodId": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
  "referenceId": "ref_add_card_12345",
  "useJavaScriptCallback": true,
  "formConfig": {
    "billingInfoCaptureLevel": "Minimal"
  }
}

Token Creation with account holder

{
  "paymentMethodId": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
  "referenceId": "ref_add_card_12345",
  "useJavaScriptCallback": true,
  "accountHolder": {
    "externalId": "customer_abc123xyz"
  }
}

Responses

200

A successful Card Not Present tokenization response

application/json · CardOnFileVirtualAddResponse

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"

referenceId ReferenceIdForResponse

max length 100

Example: "ref_s192i49i"

requestedAmount integer

Always 0 when creating a virtual tokenization session.

Example: 0

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 tokenization transaction.

{
  "id": "ifr_01J2F0ZJ2JW5B63CJFPXRGAB1S",
  "paymentMethod": {
    "id": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
    "type": "Virtual",
    "currency": "USD",
    "description": "Online Checkout Iframe"
  },
  "referenceId": "ref_add_card_12345",
  "requestedAmount": 0,
  "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."

Example

{
  "code": 2000,
  "status": "Rejected",
  "message": "One or more validation errors occurred.",
  "traceId": "1-6838bcce-5c0074e82ac7170d4f990d87",
  "timestamp": "2025-05-29T20:00:15.5752808Z",
  "errorDetails": [
    {
      "code": 2000,
      "field": "paymentMethodId",
      "message": "Request validation failed",
      "details": "'PaymentMethodId' must not be empty."
    }
  ]
}

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": []
}

Remove Token

DELETE/payment-methods/token/{id}

Remove a previously tokenized card from the system.

IMPORTANT: Once a payment method token is removed, it cannot be used for any future transactions, including:

New sales or authorizations
Referenced captures of existing authorizations
Referenced refunds of completed transactions
Any other transaction operations

Before removing a token, ensure that:

All pending authorizations have been captured or voided
No future captures or refunds will be needed for transactions using this token
All business processes dependent on this token are complete

Post-removal effects:

The dateDeleted timestamp will be immediately reflected in all future List Transactions responses for transactions that used this token
Sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes
Historical transaction data (amounts, authorization codes, reference IDs) remains intact for reconciliation

Webhook Events

The following webhook events will be triggered during the tokenized card removal process:

token.removed - when a previously tokenized card is removed from the system.

Parameters

Name	In	Type	Description
`id` required	path	string	The ID of the tokenized card to remove.
`referenceId`	query	string	A reference ID to tag and track this transaction for reconciliation.

Responses

200

A successful card removal response

application/json · CardOnFileRemoveResponse

id string

Unique ID for this payment-method operation (ops_ prefix).

Example: "ops_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"

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"

successfulResponse

{
  "id": "ops_01J2F0ZJ2JW5B63CJFPXRGAB1S",
  "paymentMethod": {
    "id": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J",
    "type": "Token",
    "currency": "USD",
    "dateDeleted": "2025-05-11T17:40:33.7688544Z",
    "cardType": "VISA"
  },
  "referenceId": "ref_remove_card_12345",
  "resultCode": 0,
  "resultText": "Card successfully removed"
}

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": "Payment method not found",
  "traceId": "1-6838bcce-5c0074e82ac7170d4f990d87",
  "timestamp": "2025-05-29T20:00:15.5752808Z",
  "errorDetails": [
    {
      "code": 2000,
      "field": "PaymentMethod",
      "message": "Payment method not found"
    }
  ]
}

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": []
}