--- title: "Get a cardholder's cards" method: GET path: "/issuing/cardholders/{cardholderId}/cards" tags: ["Cardholders"] --- # Get a cardholder's cards `GET /issuing/cardholders/{cardholderId}/cards` ## Request - Base URL: `https://{prefix}.api.sandbox.checkout.com` - URL: `https://{prefix}.api.sandbox.checkout.com/issuing/cardholders/{cardholderId}/cards` - Auth: OAuth 2 - Client credentials - Token URL: `string` scopes: `issuing:card-management-read` - TypeScript: (a function with typed inputs; its response is checked against the schema) Retrieves the cards issued to the specified cardholder. Card credentials are not returned in the response. The response is limited to a maximum of 150 cards. ## Path parameters - `cardholderId` string, required: The cardholder's unique identifier. ## Query parameters - `statuses` string ## Response `200` Cardholder's cards retrieved successfully - GetCardholderCardsResponse - `cards` GetCardResponse[], required: The list of cards associated with the specified cardholder. - union - object - `id` string, required: The card's unique identifier. - `client_id` string, required: The client's unique identifier. - `entity_id` string, required: The entity's unique identifier. - `cardholder_id` string, required: The cardholder's unique identifier. - `card_product_id` string, required: The card product's unique identifier. - `user_id` string: The Dashboard user's unique identifier. - `last_four` string, required: The last four digits of the card number, also known as the PAN. - `expiry_month` integer, required: The card's expiration month. - `expiry_year` integer, required: The card's expiration year. - `status` 'active' | 'inactive' | 'revoked' | 'suspended', required: The card's status, which determines whether it can approve incoming authorizations: - `inactive`: the default state - authorizations will be declined until the card is activated - `active`: authorization requests can be approved - `suspended`: incoming authorization requests will be declined - the card can be reactivated to accept new authorizations - `revoked`: incoming authorization requests will be permanently declined - the card cannot be reactivated from this state - `display_name` string: The name to display on the card. - `type` 'virtual', required: The card type. - `billing_currency` string, ISO4217, required: The issuing currency, as a three-letter ISO currency code. - `issuing_country` string, required: The issuing country, as a two-letter ISO country code. - `reference` string: Your reference. - `metadata` IssuingCardMetadata: User's metadata. - `udf1` string: User defined field 1 - `udf2` string: User defined field 2 - `udf3` string: User defined field 3 - `udf4` string: User defined field 4 - `udf5` string: User defined field 5 - `revocation_date` string, date: Deprecated. Use `scheduled_revocation_date` instead. Date scheduling the card's automatic revocation. - Supported format: `YYYY-MM-DD` (time is midnight UTC) - `scheduled_activation_date` string: Date scheduling the card's first activation. Only applies to the initial activation of a card. Two formats are supported: - Date only: `YYYY-MM-DD` (treated as midnight UTC) - Date with round hour: `YYYY-MM-DDTHH:mmZ` (UTC) or `YYYY-MM-DDTHH:mm±HH:mm` (offset) Only round hours are allowed when a time is provided (`HH:00`). The value must be at least the next round hour after the request time. - `root_card_id` string: When a card is renewed, the unique identifier of the first card in the renewal history. - `parent_card_id` string: When a card is renewed, the unique identifier of the previous card in the renewal history. - `scheme` 'mastercard' | 'visa', required: the card scheme. - `created_date` string, UTC - `last_modified_date` string, UTC - `_links` CardLinks: The links related to the card. - `self` IssuingLink, required - `href` string, required: The link URL. - `actions` string[], required: The HTTP Methods that can be performed on the link. - `types` string[], required: The Content Types for the link to the resource - `credentials` IssuingLink, required - `href` string, required: The link URL. - `actions` string[], required: The HTTP Methods that can be performed on the link. - `types` string[], required: The Content Types for the link to the resource - `revoke` IssuingLink, required - `href` string, required: The link URL. - `actions` string[], required: The HTTP Methods that can be performed on the link. - `types` string[], required: The Content Types for the link to the resource - `controls` IssuingLink, required - `href` string, required: The link URL. - `actions` string[], required: The HTTP Methods that can be performed on the link. - `types` string[], required: The Content Types for the link to the resource - `is_single_use` boolean: Specifies whether the virtual card is set to expire after a single use. - `scheduled_revocation_date` string, date: The card will be revoked at midnight UTC on the date specified. - Format: `YYYY-MM-DD` - `last_activated_on` string, date-time, nullable: The date and time the card was last activated. If the card has never been activated, this field returns `null`. - object - `id` string, required: The card's unique identifier. - `client_id` string, required: The client's unique identifier. - `entity_id` string, required: The entity's unique identifier. - `cardholder_id` string, required: The cardholder's unique identifier. - `card_product_id` string, required: The card product's unique identifier. - `user_id` string: The Dashboard user's unique identifier. - `last_four` string, required: The last four digits of the card number, also known as the PAN. - `expiry_month` integer, required: The card's expiration month. - `expiry_year` integer, required: The card's expiration year. - `status` 'active' | 'inactive' | 'revoked' | 'suspended', required: The card's status, which determines whether it can approve incoming authorizations: - `inactive`: the default state - authorizations will be declined until the card is activated - `active`: authorization requests can be approved - `suspended`: incoming authorization requests will be declined - the card can be reactivated to accept new authorizations - `revoked`: incoming authorization requests will be permanently declined - the card cannot be reactivated from this state - `display_name` string: The name to display on the card. - `type` 'physical', required: The card type. - `billing_currency` string, ISO4217, required: The issuing currency, as a three-letter ISO currency code. - `issuing_country` string, required: The issuing country, as a two-letter ISO country code. - `reference` string: Your reference. - `metadata` IssuingCardMetadata: User's metadata. - `udf1` string: User defined field 1 - `udf2` string: User defined field 2 - `udf3` string: User defined field 3 - `udf4` string: User defined field 4 - `udf5` string: User defined field 5 - `revocation_date` string, date: Deprecated. Use `scheduled_revocation_date` instead. Date scheduling the card's automatic revocation. - Supported format: `YYYY-MM-DD` (time is midnight UTC) - `scheduled_activation_date` string: Date scheduling the card's first activation. Only applies to the initial activation of a card. Two formats are supported: - Date only: `YYYY-MM-DD` (treated as midnight UTC) - Date with round hour: `YYYY-MM-DDTHH:mmZ` (UTC) or `YYYY-MM-DDTHH:mm±HH:mm` (offset) Only round hours are allowed when a time is provided (`HH:00`). The value must be at least the next round hour after the request time. - `root_card_id` string: When a card is renewed, the unique identifier of the first card in the renewal history. - `parent_card_id` string: When a card is renewed, the unique identifier of the previous card in the renewal history. - `scheme` 'mastercard' | 'visa', required: the card scheme. - `created_date` string, UTC - `last_modified_date` string, UTC - `_links` CardLinks: The links related to the card. - `self` IssuingLink, required - `href` string, required: The link URL. - `actions` string[], required: The HTTP Methods that can be performed on the link. - `types` string[], required: The Content Types for the link to the resource - `credentials` IssuingLink, required - `href` string, required: The link URL. - `actions` string[], required: The HTTP Methods that can be performed on the link. - `types` string[], required: The Content Types for the link to the resource - `revoke` IssuingLink, required - `href` string, required: The link URL. - `actions` string[], required: The HTTP Methods that can be performed on the link. - `types` string[], required: The Content Types for the link to the resource - `controls` IssuingLink, required - `href` string, required: The link URL. - `actions` string[], required: The HTTP Methods that can be performed on the link. - `types` string[], required: The Content Types for the link to the resource - `scheduled_revocation_date` string, date: The card will be revoked at midnight UTC on the date specified. - Format: `YYYY-MM-DD` - `last_activated_on` string, date-time, nullable: The date and time the card was last activated. If the card has never been activated, this field returns `null`. ## Other responses - `401`: Unauthorized - `404`: Cardholder not found - `500`: Internal Server Error --- [API](https://skmtc.dev/checkout/apis/checkout-com-api-reference.md) - [All operations](https://skmtc.dev/checkout/apis/checkout-com-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/checkout/apis/checkout-com-api-reference/revisions/0f1abdb1c3e9?raw)