Payment Methods

Endpoints for managing payment methods

List Payment Methods

GET/payment-methods

Returns a paginated list of payment methods that have been configured in the system for the authenticated merchant.

IDs of both "Physical" payment terminals that can be used to process Card Present transactions and IDs of "Virtual" payment methods (hosted payment forms / iframes) that can be used to process Card Not Present and bank transfer transactions (ACH) will be returned.

Filtering and Sorting

You can filter and sort the results using query parameters:

Available Filter/Sort Fields:

id - Payment method ID
paymentMethodType - Type of payment method (Physical, Virtual, VirtualAch)
currency - Currency (USD, CAD)
description - Payment method description
ownerId - The Merchant ID that owns this Payment Method ID

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

Examples:

Filter by type: ?filters=paymentMethodType==Physical
Multiple filters: ?filters=paymentMethodType==Physical,currency==USD
Sort results: ?sorts=paymentMethodType,description
Combined: ?filters=currency==USD&sorts=description

Parameters

Name	In	Type	Description
`filters`	query	string	Filter criteria in the format: field==value,field!=value Multiple filters can be separated by commas. Available fields: id, paymentMethodType, currency, description, ownerId
`sorts`	query	string	Sort criteria as comma-separated field names. Available fields: id, paymentMethodType, currency, description, ownerId
`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 available payment methods

application/json · PaymentMethodsListResponse

totalCount integer required

Total number of payment methods that match the filter criteria

Example: 2

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 object required

Array of payment methods for the current page

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"

Single payment method result

{
  "totalCount": 1,
  "page": 1,
  "pageSize": 10,
  "totalPages": 1,
  "hasNextPage": false,
  "hasPreviousPage": false,
  "items": [
    {
      "id": "pmt_trm_01JRZPTMTBN41PC3VPQNZ5T3HF",
      "type": "Physical",
      "currency": "USD",
      "description": "Main Store Terminal"
    }
  ]
}

Multiple payment methods result

{
  "totalCount": 3,
  "page": 1,
  "pageSize": 10,
  "totalPages": 1,
  "hasNextPage": false,
  "hasPreviousPage": false,
  "items": [
    {
      "id": "pmt_trm_01JRZPTMTBN41PC3VPQNZ5T3HF",
      "type": "Physical",
      "currency": "USD",
      "description": "Main Store Terminal"
    },
    {
      "id": "pmt_trm_01JRZQW7FXMG62D8HJTPK3Y5VB",
      "type": "Physical",
      "currency": "USD",
      "description": "Secondary Store Terminal"
    },
    {
      "id": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
      "type": "Virtual",
      "currency": "USD",
      "description": "Online Checkout Iframe"
    }
  ]
}

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

List Account Holder Payment Methods

GET/payment-methods/account-holder/{accountHolderId}

Returns a paginated list of tokenized payment methods (cards) associated with a specific account holder.

You can specify either the account holder ID assigned by the API or the external account holder ID assigned by your system.

The endpoint supports filtering and sorting to help you organize and retrieve payment methods efficiently.

Parameters

Name	In	Type	Description
`accountHolderId` required	path	string	The account holder ID to retrieve payment methods for. Can be either: API-assigned ID: `aho_01JRZPRGFF4J2SZC3HMDBYEN2J` External ID format: `usr_1757945457790` (assigned by your system) The account holder must belong to the merchant that owns the API key used for this request. An account holder belonging to a different merchant returns `404 Resource not found`, exactly as if the ID did not exist.
`sorts`	query	string	Comma-separated list of fields to sort by. Prefix with `-` for descending order. Available fields: id, type, currency, cardType, maskedCardNumber, cardExpDate, dateCreated
`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 account holder payment methods

application/json · AccountHolderPaymentMethodsListResponse

totalCount integer required

Total number of payment methods that match the filter criteria

Example: 2

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 object required

List of tokenized payment methods for the account holder

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"

List of an Account Holder's Payment Methods

{
  "totalCount": 3,
  "page": 1,
  "pageSize": 10,
  "totalPages": 1,
  "hasNextPage": false,
  "hasPreviousPage": false,
  "items": [
    {
      "id": "pmt_tkn_01JRZPMK5YQ1N8S7CXFVG2H9TB",
      "type": "Token",
      "currency": "USD",
      "billingContact": {
        "name": "Jane Smith",
        "countryCode": "US",
        "zipCode": "10001",
        "address": "123 Broadway Ave",
        "state": "NY",
        "city": "New York"
      },
      "cardType": "MASTERCARD",
      "maskedCardNumber": "5****1234",
      "cardExpDate": "0927"
    },
    {
      "id": "pmt_tkn_01JRZPN8K2R7M4J9BWEX3A6QFC",
      "type": "Token",
      "currency": "USD",
      "billingContact": {
        "name": "Jane Smith",
        "countryCode": "US",
        "zipCode": "10001",
        "address": "123 Broadway Ave",
        "state": "NY",
        "city": "New York"
      },
      "cardType": "VISA",
      "maskedCardNumber": "4****9876",
      "cardExpDate": "1226"
    },
    {
      "id": "pmt_tkn_01JRZPPV9X3K7K2DMQTY8Z5RGH",
      "type": "Token",
      "currency": "USD",
      "billingContact": {
        "name": "Jane Smith",
        "countryCode": "US",
        "zipCode": "10001",
        "address": "123 Broadway Ave",
        "state": "NY",
        "city": "New York"
      },
      "cardType": "DISCOVER",
      "maskedCardNumber": "6****5555",
      "cardExpDate": "0328"
    }
  ]
}

401

Unauthorized - Missing or invalid API key

application/json · object

code integer

Example: 1000

status string

Example: "Rejected"

message string

Example: "API key cannot be empty"

traceId string

Example: "1-6838be96-74c62f8e2804352739e63476"

timestamp string (date-time)

Example: "2025-05-29T20:07:50.472348Z"

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

Missing or invalid API key

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

404

Resource not found

application/json · object

code integer

Example: 4000

status string

Example: "Rejected"

message string

Example: "Resource not found"

traceId string

Example: "1-68c8732b-3bbe2a8223345463532cef92"

timestamp string (date-time)

Example: "2025-09-15T20:12:27.846948Z"

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

No user provided in path

{
  "code": 4000,
  "status": "Rejected",
  "message": "Resource not found",
  "traceId": "1-68c8732b-3bbe2a8223345463532cef92",
  "timestamp": "2025-09-15T20:12:27.8469482Z",
  "errorDetails": []
}

Account holder not found

{
  "code": 4000,
  "status": "Rejected",
  "message": "Account holder with external ID usr_1234567890123 not found",
  "traceId": "1-68c87350-11897437327b7fdb7611df33",
  "timestamp": "2025-09-15T20:13:04.9126994Z",
  "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."