> ## Documentation Index
> Fetch the complete documentation index at: https://next-developers.opencard.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Cards

> Register and maintain cards on the OpenCard Issuer API — create, update, list, get, and delete cards under /api/v1/issuers/{slug}/cards.

The cards endpoints maintain the set of cards enrolled in OpenCard per customer organisation. Register cards before sending transaction states — `{card_id}` in the transaction path is **your** card id from the create payload.

**Base path:**

```
{base_url}/api/v1/issuers/{slug}/cards
```

***

## Endpoints

The boilerplate documents the **full** card API. OpenCard enables only the operations your integration needs — confirm which methods are live for your `{slug}` before go-live.

| Method   | Path               | Scope (typical)              | Boilerplate     | Minimal integration |
| -------- | ------------------ | ---------------------------- | --------------- | ------------------- |
| `POST`   | `/cards`           | `issuer-{slug}-cards-write`  | ✅ Create        | ✅ Create            |
| `DELETE` | `/cards/{card_id}` | `issuer-{slug}-cards-delete` | ✅ Delete        | ✅ Delete            |
| `PUT`    | `/cards/{card_id}` | `issuer-{slug}-cards-write`  | ✅ Update        | —                   |
| `GET`    | `/cards/{card_id}` | `issuer-{slug}-cards-read`   | ✅ Get one       | —                   |
| `GET`    | `/cards`           | `issuer-{slug}-cards-read`   | ✅ List / filter | —                   |

**Minimal integration** = create + delete + transaction states. Use that when you only register and close cards via API and manage changes by delete + re-create.

**Full boilerplate** = all five operations above — update holder or company in place, query and inspect cards without posting again.

<Note>
  If an endpoint returns `404` or `405` on your slug, it is not enabled for your integration. The OpenAPI reference shows the full boilerplate surface; your credentials and scope list reflect what you can actually call.
</Note>

***

## Create card

```
POST /api/v1/issuers/{slug}/cards
Scope: issuer-{slug}-cards-write
```

```json theme={null}
{
  "id": "12345",
  "last_four": "1234",
  "bin_number": "123456",
  "liability": "corporate_with_personal_invoice",
  "scheme": "visa",
  "funding": "credit",
  "issuer_organization_number": "5555555551",
  "issuer_country_code": "SE",
  "identity": {
    "ssn": "190001011111",
    "ssn_country_code": "SE",
    "name": "Test Testsson",
    "company_organization_number": "5555555555",
    "company_country_code": "SE"
  }
}
```

| Field                                  | Required | Notes                                                             |
| -------------------------------------- | -------- | ----------------------------------------------------------------- |
| `id`                                   | ✅        | **Your** unique card id — used as `{card_id}` in transaction URLs |
| `last_four`                            | ✅        | Last four digits                                                  |
| `bin_number`                           | ✅        | BIN, max 12 characters                                            |
| `liability`                            | ✅        | `personal`, `corporate`, or `corporate_with_personal_invoice`     |
| `scheme`                               | ✅        | e.g. `visa`, `mastercard`                                         |
| `funding`                              | ✅\*      | `debit` or `credit` — appears on EMS webhooks as `card_funding`   |
| `issuer_organization_number`           | ✅        | Your organisation number (seller party)                           |
| `issuer_country_code`                  | ✅        | ISO 3166-1 alpha-2                                                |
| `identity.ssn`                         | ✅        | Cardholder national id                                            |
| `identity.ssn_country_code`            | ✅        | ISO 3166-1 alpha-2                                                |
| `identity.name`                        | ✅        | Cardholder display name                                           |
| `identity.company_organization_number` | ✅        | Customer company org number (buyer party)                         |
| `identity.company_country_code`        | ✅        | ISO 3166-1 alpha-2                                                |

\*Required on integrations that expose `funding` (confirm with OpenCard for your `{slug}`).

**Responses:**

| Code  | Meaning                                      |
| ----- | -------------------------------------------- |
| `201` | Card created                                 |
| `200` | Card already exists (idempotent — same `id`) |

Create is **idempotent** on `id`. Re-posting the same card returns the existing record.

***

## Update card

<Note>
  **Boilerplate only** — not all issuer slugs expose `PUT`. If you only have create + delete, close the old card and create a new one when details change.
</Note>

```
PUT /api/v1/issuers/{slug}/cards/{card_id}
Scope: issuer-{slug}-cards-write
```

Same body shape as create (except `id` comes from the path). Supports moving a card between identities/companies when holder or employer changes.

**Response `200`** with `updated: true`.

***

## Get card

<Note>
  **Boilerplate only** — optional on minimal integrations.
</Note>

```
GET /api/v1/issuers/{slug}/cards/{card_id}
Scope: issuer-{slug}-cards-read
```

***

## List cards

<Note>
  **Boilerplate only** — optional on minimal integrations.
</Note>

```
GET /api/v1/issuers/{slug}/cards
Scope: issuer-{slug}-cards-read
```

Query parameters: `last_four`, `buyer_party`, `seller_party`, `bin_number`, `id`, `active`, `per_page` (1–100, default 15), `page`.

***

## Delete card

```
DELETE /api/v1/issuers/{slug}/cards/{card_id}
Scope: issuer-{slug}-cards-delete
```

Soft-deletes the card and marks it inactive. **Response `204`** with empty body.

***

## Why the registry matters

OpenCard matches every transaction state to a registered card and identity. Without an up-to-date registry:

* Transaction posts return `card_not_found`
* EMS apps never see data for unknown cards

Keep cards in sync when issued, replaced, or closed at your end.