> 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/payments/account-holders.md).

# 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

```http
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](/get-started/conventions.md#filtering-sorting-and-paging) syntax.

{% hint style="info" %}
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.
{% endhint %}

## Account holder details on a transaction

Where a transaction carries an account holder, it is returned with its contact details:

```json
{
  "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`).

## Related

* [Tokenization](/payments/tokenization.md)
* [Payment methods](/payments/payment-methods.md)