> ## Documentation Index
> Fetch the complete documentation index at: https://developer.payem.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Cards

> Issue and manage cards through the Partner API

Card **reads** require `PARTNER_API_V1_BASIC`. Card **writes and actions** (create, update, lock, unlock, terminate) require `PARTNER_API_V1_CARDS`.

## Common flows

### List / retrieve cards

```bash theme={null}
GET /api/partner/v1/cards?page=1
GET /api/partner/v1/cards/{id}
```

Requires `PARTNER_API_V1_BASIC`.

List filters use public Partner API names:

| Query parameter | Behavior |
| - | - |
| `card_type` | `EMPLOYEE`, `VENDOR`, or `SINGLE-USE` |
| `card_owner_id` | Narrows `card_type` to one owner. Send it with `card_type`; without `card_type`, it is ignored. |
| `subsidiary_id` | Narrows results to one subsidiary |
| `status` | Narrows results to one card status |
| `last_four` | Matches the last four card digits |

```bash theme={null}
GET /api/partner/v1/cards?card_type=EMPLOYEE&card_owner_id=123&subsidiary_id=7
```

### Create a card

```bash theme={null}
POST /api/partner/v1/cards
```

Requires `PARTNER_API_V1_CARDS`. Request body shape is defined by `CreateCardRequest` in the OpenAPI schema.

`type` is the only field marked `required` in the schema, but each card type requires additional fields at request time. Sending a schema-valid payload without them returns a `400` `ValidationError`:

| Card type | Additionally required | Notes |
| - | - | - |
| `EMPLOYEE` | `employee_details` (`id` or `email`) | Must resolve to exactly one active user |
| `VENDOR` | `vendor_details` (`id` or `name`) **and** `subsidiary_details` (`id` or `name`) | Each must resolve to exactly one active vendor / subsidiary |
| `SINGLE-USE` | `subsidiary_details` (`id` or `name`) | Must resolve to exactly one active subsidiary |

These lookups happen against live data, so even a well-formed `employee_details`/`vendor_details`/`subsidiary_details` object is rejected if it doesn't resolve to a single active record.

To retry card creation safely, optionally send an `Idempotency-Key` header:

```bash theme={null}
POST /api/partner/v1/cards
Idempotency-Key: 7d26f350-0ca5-4f42-a29f-52e57168d80e
```

After a successful request, the same key and payload replay the stored response with `200 OK` without creating another card. Reusing the key with a different payload returns `409 Conflict`. Records are retained for seven days and then removed by scheduled cleanup.

Only successful `2xx` responses are cached. If you receive a definite non-`2xx` response, use a new key for the retry. If the outcome is unknown, such as after a timeout, retry the same key to avoid creating a duplicate card.

Keys must contain 1–255 printable ASCII characters, without spaces, double quotes, or control characters.

### Update a card

```bash theme={null}
PUT /api/partner/v1/cards/{id}
```

Requires `PARTNER_API_V1_CARDS`.

### Lock / unlock / terminate

```bash theme={null}
PUT /api/partner/v1/cards/{id}/lock
PUT /api/partner/v1/cards/{id}/unlock
PUT /api/partner/v1/cards/{id}/terminate
```

Requires both `PARTNER_API_V1_BASIC` and `PARTNER_API_V1_CARDS`.

See the interactive examples under **API Reference → cards**.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.