Account holders
Group a customer's stored payment methods under an API-assigned ID or your own customer ID.
The API supports account holder management for organizing and retrieving tokenized payment methods. For POST /transactions/virtual-sale and POST /payment-methods/virtual, pass accountHolder: { "externalId": "ext_customer_123" } to find or create the account holder. POST /transactions/virtual-auth ignores this field. Physical sale and authorization requests do not accept account holder input.
This enables you to:
- Retrieve all payment methods associated with a specific account holder
- Organize customer payment methods by the API-assigned account holder ID or your own external ID
- Query an account holder's payment methods with filtering and sorting capabilities
Two ways to address an account holder
| Form | Example | Assigned by |
|---|---|---|
| API-assigned ID | aho_01JRZPRGFF4J2SZC3HMDBYEN2J |
The API |
| External ID | usr_1757945457790 |
Your system |
Both work anywhere an accountHolderId is accepted. Using your own external ID means you do not have to store a mapping - you can look up a customer's saved cards with the same identifier your application already uses.
Retrieving an account holder's payment methods
GET /payment-methods/account-holder/{accountHolderId}
The API returns a list of all tokenized payment methods associated with that account holder, and supports the shared filter, sort, and paging syntax.
The account holder must belong to the merchant that owns the API key used for the request. An account holder belonging to a different merchant returns 404 Resource not found, exactly as if the ID did not exist.
Account holder details on a transaction
Where a transaction carries an account holder, it is returned with its contact details:
{
"accountHolder": {
"id": "aho_01JRZPRGFF4J2SZC3HMDBYEN2J",
"externalId": "ext_customer_123",
"contact": {
"name": "Jane Doe",
"countryCode": "US",
"zipCode": "30303",
"address": "123 Peachtree St",
"address2": "Suite 200",
"state": "GA",
"city": "Atlanta"
}
}
}
Invalid account holder data is rejected with codes in the 2100 range - 2100 (InvalidAccountHolderInformation), 2101 (InvalidCountryCode), 2102 (InvalidZipCode), 2103 (MissingCountryCodeOrZipCode), and 2105 (InvalidEmailAddress). An account holder owned by another merchant is 2021 (InvalidAccountHolderOwner).