> For the complete documentation index, see [llms.txt](https://docs.omni.integratedcommerce.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.omni.integratedcommerce.io/api-reference/payment-methods.md).
# Payment Methods
Endpoints for managing payment methods
## List 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\`
````json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"tags":[{"name":"Payment Methods","description":"Endpoints for managing payment methods"}],"servers":[{"url":"https://api.omni.integratedcommerce.io/v1"}],"security":[{"ApiKeyHeader":[]}],"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"All API requests must be authenticated using an API key. The API key should be included in the `x-api-key` header of each request.\n\n### API Key Format\n\n```\nx-api-key: \n```\n\n### Resource Scope\n\nAn API key grants access only to the resources owned by its merchant. Every resource identifier you supply - transaction IDs, account holder IDs, payment method tokens, subscription IDs, settlement IDs - is resolved within the scope of the merchant that owns the API key.\n\nSupplying an identifier that belongs to a different merchant produces the same not-found response as an identifier that does not exist at all. Responses do not distinguish between the two cases, so a resource ID cannot be used to determine whether it exists under another merchant.\n\n### Environment-Specific Keys\n\nSeparate API keys identify the sandbox and production environments. The base URL for both environments is the same (`https://api.omni.integratedcommerce.io/v1`), but the keys are different.\n\n#### Sandbox Environment\n- Format: `key_test_.`\n- Use this key for development and testing\n\n#### Production Environment\n- Format: `key_live_.`\n- Use this key for live production traffic\n\nSend the complete key, including the secret after the dot. Legacy keys without a dot remain supported until revoked.\n\n### Error Responses\n\nIf authentication fails because of an invalid or missing API key, you will receive a `401 Unauthorized` response. Check the response message for more details.\n\n## Rate Limiting\n\nIf you receive `429 Too Many Requests`, pause before retrying. Honor `Retry-After` when supplied; otherwise use exponential backoff. The API does not guarantee `X-RateLimit-*` headers.\n"}},"schemas":{"PaymentMethodsListResponse":{"type":"object","description":"Paginated response containing payment methods","properties":{"totalCount":{"type":"integer","description":"Total number of payment methods that match the filter criteria"},"page":{"type":"integer","description":"The current page number (starts at 1)"},"pageSize":{"type":"integer","description":"Number of items per page"},"totalPages":{"type":"integer","description":"Total number of pages available"},"hasNextPage":{"type":"boolean","description":"True if there are more pages of results available"},"hasPreviousPage":{"type":"boolean","description":"True if there are previous pages of results available"},"items":{"type":"array","description":"Array of payment methods for the current page","items":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","properties":{"type":{"type":"string","enum":["Physical","Virtual","VirtualAch","VirtualEft"]}}}]}}},"required":["totalCount","page","pageSize","totalPages","hasNextPage","hasPreviousPage","items"]},"PaymentMethodDetails":{"type":"object","description":"The payment method used for this transaction.","properties":{"id":{"type":"string","description":"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."},"dateDeleted":{"type":"string","format":"date-time","description":"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.\n\nThis field will be present in three scenarios:\n- As part of a successful Remove Token endpoint response\n- In token.removed webhook notifications\n- In List Transactions responses for transactions where the associated token was later removed\n\nWhen this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.\n"},"type":{"type":"string","enum":["Unknown","Physical","Virtual","VirtualAch","VirtualEft","Token"],"description":"The type of payment method:\n- `Physical` - A physical payment terminal for Card Present transactions\n- `Virtual` - A hosted payment form/iframe for Card Not Present transactions\n- `VirtualAch` - A hosted payment form/iframe for ACH (US) bank transfer transactions\n- `Token` - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions\n- `VirtualEft` - A virtual Canadian bank-transfer payment method, when configured.\n- `Unknown` - The payment method type is not known.\n"},"currency":{"type":"string","enum":["USD","CAD"],"description":"The currency of the payment method."},"description":{"type":"string","description":"A human-readable name for the payment method."},"billingContact":{"allOf":[{"$ref":"#/components/schemas/BillingContact"},{"type":"object","description":"Billing contact information. Only returned for tokenized payment methods from Card Not Present transactions."}]},"cardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"maskedCardNumber":{"type":"string","description":"The masked card number. The format may vary (e.g. ************0011, 4****0011, etc.)"},"cardExpDate":{"type":"string","description":"The expiration date of the card in MMYY format."},"accountType":{"type":"string","enum":["Credit","Debit","Checking","Savings"],"description":"Funding-source classification of this token-type payment method.\n- For card tokens: `Credit` or `Debit`.\n- For ACH tokens: `Checking` or `Savings`.\nMay be omitted for older tokens that pre-date this field, for non-token payment methods,\nor when the source did not provide a classification.\n"},"accountNumber":{"type":"string","description":"Masked bank account number, when available for a bank-account token."}},"required":["id","type","currency"]},"BillingContact":{"type":"object","description":"Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}},"Error":{"type":"object","description":"Represents an error that occurred during the request.","properties":{"code":{"type":"integer","enum":[0,1000,1001,2000,2010,2011,2012,2013,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],"description":"Numeric error code. These are grouped into ranges for easier identification and troubleshooting.\n\n * `0` - Unknown\n * `1000` - AuthenticationGenericError\n * `1001` - MerchantNotAuthorizedForResource\n * `2000` - RequestValidationGenericError\n * `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.\n * `2011` - InvalidTransactionType\n * `2012` - InvalidAmount\n * `2013` - PaymentMethodUsageRestricted\n * `2020` - InvalidPaymentMethodOwner\n * `2021` - InvalidAccountHolderOwner\n * `2100` - InvalidAccountHolderInformation\n * `2101` - InvalidCountryCode\n * `2102` - InvalidZipCode\n * `2103` - MissingCountryCodeOrZipCode\n * `2105` - InvalidEmailAddress\n * `2201` - MissingUniqueToken\n * `2202` - TransactionDeclinedError\n * `2900` - RequestValidationUnsupportedPayload\n * `2901` - RequestValidationWebhookMissingTypeAndDmnType\n * `2902` - RequestValidationUnsupportedWebhookTokenization\n * `2903` - RequestValidationUnsupportedWebhookType\n * `3000` - UnknownServerGenericError\n * `3201` - InvalidOrExpiredSession\n * `3202` - FailedToCreateSessionInAdapter\n * `3203` - ErrorWhileTokenizingCard\n * `3204` - FailedToLoadThirdPartySdk\n * `3205` - SessionExpired\n * `3299` - JavaScriptError\n * `3400` - ResourceNotReadyError\n * `3401` - TransactionNotCompleteYet\n * `3501` - CouldNotCreateBillingSubscription\n * `3502` - CouldNotCancelBillingSubscription\n * `3503` - BillingSubscriptionInvalidStatus\n * `4000` - ResourceNotFound\n * `4001` - TokenizedCardNotFound\n * `4002` - PaymentMethodNotFound\n * `4003` - AccountHolderNotFound\n * `4004` - BillingSubscriptionNotFound\n * `6000` - SdkGenericError\n * `6001` - SdkJavaScriptError\n * `6100` - SdkSessionLoadFailed\n * `6101` - SdkSessionExpired\n * `6102` - SdkSessionNotInitialized\n * `6103` - SdkEnvironmentMismatch\n * `6200` - SdkCardFieldsInvalid\n * `6201` - SdkCardTokenizationFailed\n * `6202` - SdkCardInitFailed\n * `6203` - SdkCardProcessingFailed\n * `6300` - SdkAchFieldsInvalid\n * `6301` - SdkAchProcessingFailed\n * `6400` - SdkEftProcessingFailed\n * `6500` - SdkWalletError\n * `6501` - SdkWalletProcessingFailed\n * `6600` - SdkThirdPartySdkLoadFailed\n * `6700` - SdkFormValidationFailed\n * `6701` - SdkBillingValidationFailed\n * `6800` - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when `formConfig.enable3DSecure: true`.\n * `6801` - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.\n * `6802` - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.\n * `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`.\n * `6901` - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.\n * `6902` - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.\n * `9000` - UnhandledGenericError\n * `9999` - MaxErrorCode\n"},"status":{"type":"string","enum":["Completed","Rejected","Interrupted","Unknown"],"description":"Execution status of the request sent to the payment gateway.\n\n * Completed - The request completed successfully.\n * Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.\n * 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.\n * Unknown\n"},"message":{"type":"string","description":"Developer-facing error message."},"traceId":{"type":"string","description":"Unique trace identifier for tracking and debugging this request."},"timestamp":{"type":"string","format":"date-time","description":"The timestamp when the error occurred (UTC)."},"errorDetails":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"ErrorDetail":{"type":"object","description":"Represents a validation error that occurred during the request.","properties":{"code":{"type":"integer","description":"Error code"},"field":{"type":"string","description":"The field with the error"},"message":{"type":"string","description":"Error message"},"details":{"type":"string","description":"Additional details about the error"}}}},"responses":{"UnauthorizedError":{"description":"Unauthorized response due to an invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/payment-methods":{"get":{"operationId":"getPaymentMethods","summary":"List Payment Methods","description":"Returns a paginated list of payment methods that have been configured in the system for the authenticated merchant.\n\nIDs 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.\n\n### Filtering and Sorting\n\nYou can filter and sort the results using query parameters:\n\n#### Available Filter/Sort Fields:\n- `id` - Payment method ID\n- `paymentMethodType` - Type of payment method (Physical, Virtual, VirtualAch)\n- `currency` - Currency (USD, CAD)\n- `description` - Payment method description\n- `ownerId` - The Merchant ID that owns this Payment Method ID\n\n#### Filter Operators:\n\n| Operator | Meaning |\n|----------|---------|\n| `==` | Equals |\n| `!=` | Not equals |\n| `>` | Greater than |\n| `<` | Less than |\n| `>=` | Greater than or equal to |\n| `<=` | Less than or equal to |\n| `@=` | Contains |\n| `_=` | Starts with |\n| `_-=` | Ends with |\n| `!@=` | Does not Contains |\n| `!_=` | Does not Starts with |\n| `!_-=` | Does not Ends with |\n| `@=*` | Case-insensitive string Contains |\n| `_=*` | Case-insensitive string Starts with |\n| `_-=*` | Case-insensitive string Ends with |\n| `==*` | Case-insensitive string Equals |\n| `!=*` | Case-insensitive string Not equals |\n| `!@=*` | Case-insensitive string does not Contains |\n| `!_=*` | Case-insensitive string does not Starts with |\n\n#### Examples:\n- Filter by type: `?filters=paymentMethodType==Physical`\n- Multiple filters: `?filters=paymentMethodType==Physical,currency==USD`\n- Sort results: `?sorts=paymentMethodType,description`\n- Combined: `?filters=currency==USD&sorts=description`\n","parameters":[{"name":"filters","in":"query","required":false,"description":"Filter criteria in the format: field==value,field!=value\nMultiple filters can be separated by commas.\nAvailable fields: id, paymentMethodType, currency, description, ownerId\n","schema":{"type":"string"}},{"name":"sorts","in":"query","required":false,"description":"Sort criteria as comma-separated field names.\nAvailable fields: id, paymentMethodType, currency, description, ownerId\n","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number to retrieve (starts at 1).\nFor example, if you have 100 records with 10 per page, page 2 gives you records 11 to 20.\n","schema":{"type":"integer","minimum":1,"default":1}},{"name":"pageSize","in":"query","required":false,"description":"Number of records per page.\nFor example, if you have 100 records with 10 per page, page 2 gives you records 11 to 20.\n","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}}],"tags":["Payment Methods"],"responses":{"200":{"description":"A successful paginated response containing available payment methods","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentMethodsListResponse"}}}},"400":{"description":"Invalid request or query parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}}}}
````
## List Account Holder Payment Methods
> 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.
````json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"tags":[{"name":"Payment Methods","description":"Endpoints for managing payment methods"}],"servers":[{"url":"https://api.omni.integratedcommerce.io/v1"}],"security":[{"ApiKeyHeader":[]}],"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"All API requests must be authenticated using an API key. The API key should be included in the `x-api-key` header of each request.\n\n### API Key Format\n\n```\nx-api-key: \n```\n\n### Resource Scope\n\nAn API key grants access only to the resources owned by its merchant. Every resource identifier you supply - transaction IDs, account holder IDs, payment method tokens, subscription IDs, settlement IDs - is resolved within the scope of the merchant that owns the API key.\n\nSupplying an identifier that belongs to a different merchant produces the same not-found response as an identifier that does not exist at all. Responses do not distinguish between the two cases, so a resource ID cannot be used to determine whether it exists under another merchant.\n\n### Environment-Specific Keys\n\nSeparate API keys identify the sandbox and production environments. The base URL for both environments is the same (`https://api.omni.integratedcommerce.io/v1`), but the keys are different.\n\n#### Sandbox Environment\n- Format: `key_test_.`\n- Use this key for development and testing\n\n#### Production Environment\n- Format: `key_live_.`\n- Use this key for live production traffic\n\nSend the complete key, including the secret after the dot. Legacy keys without a dot remain supported until revoked.\n\n### Error Responses\n\nIf authentication fails because of an invalid or missing API key, you will receive a `401 Unauthorized` response. Check the response message for more details.\n\n## Rate Limiting\n\nIf you receive `429 Too Many Requests`, pause before retrying. Honor `Retry-After` when supplied; otherwise use exponential backoff. The API does not guarantee `X-RateLimit-*` headers.\n"}},"schemas":{"AccountHolderPaymentMethodsListResponse":{"type":"object","description":"Paginated response containing account holder payment methods","properties":{"totalCount":{"type":"integer","description":"Total number of payment methods that match the filter criteria"},"page":{"type":"integer","description":"The current page number (starts at 1)"},"pageSize":{"type":"integer","description":"Number of items per page"},"totalPages":{"type":"integer","description":"Total number of pages available"},"hasNextPage":{"type":"boolean","description":"True if there are more pages of results available"},"hasPreviousPage":{"type":"boolean","description":"True if there are previous pages of results available"},"items":{"type":"array","description":"List of tokenized payment methods for the account holder","items":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","properties":{"type":{"type":"string","enum":["Token"]}}}]}}},"required":["totalCount","page","pageSize","totalPages","hasNextPage","hasPreviousPage","items"]},"PaymentMethodDetails":{"type":"object","description":"The payment method used for this transaction.","properties":{"id":{"type":"string","description":"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."},"dateDeleted":{"type":"string","format":"date-time","description":"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.\n\nThis field will be present in three scenarios:\n- As part of a successful Remove Token endpoint response\n- In token.removed webhook notifications\n- In List Transactions responses for transactions where the associated token was later removed\n\nWhen this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.\n"},"type":{"type":"string","enum":["Unknown","Physical","Virtual","VirtualAch","VirtualEft","Token"],"description":"The type of payment method:\n- `Physical` - A physical payment terminal for Card Present transactions\n- `Virtual` - A hosted payment form/iframe for Card Not Present transactions\n- `VirtualAch` - A hosted payment form/iframe for ACH (US) bank transfer transactions\n- `Token` - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions\n- `VirtualEft` - A virtual Canadian bank-transfer payment method, when configured.\n- `Unknown` - The payment method type is not known.\n"},"currency":{"type":"string","enum":["USD","CAD"],"description":"The currency of the payment method."},"description":{"type":"string","description":"A human-readable name for the payment method."},"billingContact":{"allOf":[{"$ref":"#/components/schemas/BillingContact"},{"type":"object","description":"Billing contact information. Only returned for tokenized payment methods from Card Not Present transactions."}]},"cardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"maskedCardNumber":{"type":"string","description":"The masked card number. The format may vary (e.g. ************0011, 4****0011, etc.)"},"cardExpDate":{"type":"string","description":"The expiration date of the card in MMYY format."},"accountType":{"type":"string","enum":["Credit","Debit","Checking","Savings"],"description":"Funding-source classification of this token-type payment method.\n- For card tokens: `Credit` or `Debit`.\n- For ACH tokens: `Checking` or `Savings`.\nMay be omitted for older tokens that pre-date this field, for non-token payment methods,\nor when the source did not provide a classification.\n"},"accountNumber":{"type":"string","description":"Masked bank account number, when available for a bank-account token."}},"required":["id","type","currency"]},"BillingContact":{"type":"object","description":"Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}},"Error":{"type":"object","description":"Represents an error that occurred during the request.","properties":{"code":{"type":"integer","enum":[0,1000,1001,2000,2010,2011,2012,2013,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],"description":"Numeric error code. These are grouped into ranges for easier identification and troubleshooting.\n\n * `0` - Unknown\n * `1000` - AuthenticationGenericError\n * `1001` - MerchantNotAuthorizedForResource\n * `2000` - RequestValidationGenericError\n * `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.\n * `2011` - InvalidTransactionType\n * `2012` - InvalidAmount\n * `2013` - PaymentMethodUsageRestricted\n * `2020` - InvalidPaymentMethodOwner\n * `2021` - InvalidAccountHolderOwner\n * `2100` - InvalidAccountHolderInformation\n * `2101` - InvalidCountryCode\n * `2102` - InvalidZipCode\n * `2103` - MissingCountryCodeOrZipCode\n * `2105` - InvalidEmailAddress\n * `2201` - MissingUniqueToken\n * `2202` - TransactionDeclinedError\n * `2900` - RequestValidationUnsupportedPayload\n * `2901` - RequestValidationWebhookMissingTypeAndDmnType\n * `2902` - RequestValidationUnsupportedWebhookTokenization\n * `2903` - RequestValidationUnsupportedWebhookType\n * `3000` - UnknownServerGenericError\n * `3201` - InvalidOrExpiredSession\n * `3202` - FailedToCreateSessionInAdapter\n * `3203` - ErrorWhileTokenizingCard\n * `3204` - FailedToLoadThirdPartySdk\n * `3205` - SessionExpired\n * `3299` - JavaScriptError\n * `3400` - ResourceNotReadyError\n * `3401` - TransactionNotCompleteYet\n * `3501` - CouldNotCreateBillingSubscription\n * `3502` - CouldNotCancelBillingSubscription\n * `3503` - BillingSubscriptionInvalidStatus\n * `4000` - ResourceNotFound\n * `4001` - TokenizedCardNotFound\n * `4002` - PaymentMethodNotFound\n * `4003` - AccountHolderNotFound\n * `4004` - BillingSubscriptionNotFound\n * `6000` - SdkGenericError\n * `6001` - SdkJavaScriptError\n * `6100` - SdkSessionLoadFailed\n * `6101` - SdkSessionExpired\n * `6102` - SdkSessionNotInitialized\n * `6103` - SdkEnvironmentMismatch\n * `6200` - SdkCardFieldsInvalid\n * `6201` - SdkCardTokenizationFailed\n * `6202` - SdkCardInitFailed\n * `6203` - SdkCardProcessingFailed\n * `6300` - SdkAchFieldsInvalid\n * `6301` - SdkAchProcessingFailed\n * `6400` - SdkEftProcessingFailed\n * `6500` - SdkWalletError\n * `6501` - SdkWalletProcessingFailed\n * `6600` - SdkThirdPartySdkLoadFailed\n * `6700` - SdkFormValidationFailed\n * `6701` - SdkBillingValidationFailed\n * `6800` - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when `formConfig.enable3DSecure: true`.\n * `6801` - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.\n * `6802` - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.\n * `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`.\n * `6901` - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.\n * `6902` - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.\n * `9000` - UnhandledGenericError\n * `9999` - MaxErrorCode\n"},"status":{"type":"string","enum":["Completed","Rejected","Interrupted","Unknown"],"description":"Execution status of the request sent to the payment gateway.\n\n * Completed - The request completed successfully.\n * Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.\n * 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.\n * Unknown\n"},"message":{"type":"string","description":"Developer-facing error message."},"traceId":{"type":"string","description":"Unique trace identifier for tracking and debugging this request."},"timestamp":{"type":"string","format":"date-time","description":"The timestamp when the error occurred (UTC)."},"errorDetails":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"ErrorDetail":{"type":"object","description":"Represents a validation error that occurred during the request.","properties":{"code":{"type":"integer","description":"Error code"},"field":{"type":"string","description":"The field with the error"},"message":{"type":"string","description":"Error message"},"details":{"type":"string","description":"Additional details about the error"}}}}},"paths":{"/payment-methods/account-holder/{accountHolderId}":{"get":{"operationId":"getAccountHolderPaymentMethods","summary":"List Account Holder Payment Methods","description":"Returns a paginated list of tokenized payment methods (cards) associated with a specific account holder.\n\nYou can specify either the account holder ID assigned by the API or the external account holder ID assigned by your system.\n\nThe endpoint supports filtering and sorting to help you organize and retrieve payment methods efficiently.\n","parameters":[{"name":"accountHolderId","in":"path","required":true,"description":"The account holder ID to retrieve payment methods for. Can be either:\n- API-assigned ID: `aho_01JRZPRGFF4J2SZC3HMDBYEN2J`\n- External ID format: `usr_1757945457790` (assigned by your system)\n\nThe 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.\n","schema":{"type":"string"}},{"name":"sorts","in":"query","required":false,"description":"Comma-separated list of fields to sort by. Prefix with `-` for descending order.\nAvailable fields: id, type, currency, cardType, maskedCardNumber, cardExpDate, dateCreated\n","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number to retrieve (starts at 1).\nFor example, if you have 100 records with 10 per page, page 2 gives you records 11 to 20.\n","schema":{"type":"integer","minimum":1,"default":1}},{"name":"pageSize","in":"query","required":false,"description":"Number of records per page.\nFor example, if you have 100 records with 10 per page, page 2 gives you records 11 to 20.\n","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}}],"tags":["Payment Methods"],"responses":{"200":{"description":"A successful paginated response containing account holder payment methods","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountHolderPaymentMethodsListResponse"}}}},"400":{"description":"Invalid request or query parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"status":{"type":"string"},"message":{"type":"string"},"traceId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"errorDetails":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"}}}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"status":{"type":"string"},"message":{"type":"string"},"traceId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"errorDetails":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"}}}}}}}}}}}}
````