> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.imbawallet.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cards

> Catalog, issue, get, balance, top up, and freeze.

# Cards

Scopes: `cards:issue`, `cards:read`, `cards:topup`, `cards:freeze` (or `cards:*`).

Cards are issued for **your end customers**. You pass KYC in `cardholder`. One create = one card. Correlate with your `ext_id`, then `card_id`.

## Catalog

```http theme={null}
GET https://api.imbawallet.com/partner/card-products
Authorization: Bearer <access_token>
```

Returns only products enabled for **your** tenant.

```json theme={null}
{
  "products": [
    {
      "card_product": 12,
      "name": "Partner Virtual USD Card",
      "currency": "USD",
      "issue_fee_usdt": "5.00",
      "issue_topup_usdt": "10.00",
      "status": "active"
    }
  ],
  "request_id": "019d0120-7b59-7eab-b837-a7af38ea3db2"
}
```

Catalog fees are informative. The charge at issue time follows the live tariff for that product. Unknown / foreign `card_product` → `422` / `product_unavailable` (no leak of other tenants’ catalogs).

## Issue a card

```http theme={null}
POST https://api.imbawallet.com/partner/cards
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "ext_id": "card-issue-20260710-003",
  "card_product": 12,
  "cardholder": {
    "first_name": "IVAN",
    "middle_name": "IVANOVICH",
    "last_name": "IVANOV",
    "birth_date": "1990-05-17",
    "phone": "+79991234567",
    "email": "ivan@example.com",
    "country": "RU",
    "address": {
      "line1": "Ulitsa Pushkina, d. 1, kv. 12",
      "line2": null,
      "city": "Moskva",
      "region": "Moskva",
      "postal_code": "101000"
    }
  }
}
```

| Field          | Required | Notes                                                                             |
| -------------- | -------- | --------------------------------------------------------------------------------- |
| `ext_id`       | yes      | Your order id                                                                     |
| `card_product` | yes      | From your catalog                                                                 |
| `cardholder.*` | yes\*    | KYC; some fields are product-conditional (`birth_date`, `address`, `middle_name`) |

### Response `202`

```json theme={null}
{
  "ext_id": "card-issue-20260710-003",
  "order_id": "019d0127-fd3c-78cc-ac8e-e36927c03535",
  "card_id": null,
  "card_product": 12,
  "status": "accepted",
  "created_at": "2026-07-10T09:25:00.000Z",
  "request_id": "019d0120-7b59-7eab-b837-a7af38ea3db2"
}
```

### Issue statuses

| `status`       | Meaning                            |
| -------------- | ---------------------------------- |
| `accepted`     | Accepted; funds reserved           |
| `card_issuing` | Issuing in progress                |
| `card_issued`  | Card ready — fetch secrets via GET |
| `failed`       | Failed; reserve released           |

Other intermediate status strings may appear while the order is open — treat anything other than `card_issued` / `failed` as in progress. Prefer webhook `card_issue.status_changed` and document polling.

**Cardholder reuse:** if you previously issued a card for the same `email`+`phone` with matching KYC under your tenant, IMBA may reuse that cardholder (anti-fraud). A different person with the same email+phone gets a new cardholder.

## Get card (secrets)

```http theme={null}
GET https://api.imbawallet.com/partner/cards/{card_id}
Authorization: Bearer <access_token>
```

Default mode is JWE (`card_encrypted`). See [Card encryption](/guides/card-encryption).

```json theme={null}
{
  "card_id": "00112233445566778899aabb",
  "ext_id": "card-issue-20260710-003",
  "card_product": 12,
  "issue_status": "card_issued",
  "status": "active",
  "currency": "USD",
  "number_masked": "411111******1111",
  "card_encrypted": "<compact JWE>",
  "card": null,
  "balance": {
    "available": "100.00",
    "pending": "0.00",
    "cached_at": "2026-07-10T09:31:00.000Z"
  },
  "created_at": "2026-07-10T09:25:00.000Z",
  "updated_at": "2026-07-10T09:31:00.000Z",
  "request_id": "019d0120-7b59-7eab-b837-a7af38ea3db2"
}
```

Card statuses: `issuing`, `active`, `frozen`, `closed`, `failed`.\
Do not log PAN/CVV/JWE plaintext.

Webhooks carry status and ids — **fetch secrets via this GET**, not from webhooks.

## Card balance

```http theme={null}
GET https://api.imbawallet.com/partner/cards/{card_id}/balance
```

```json theme={null}
{
  "card_id": "00112233445566778899aabb",
  "currency": "USD",
  "available": "100.00",
  "pending": "0.00",
  "as_of": "2026-07-10T09:31:00.000Z",
  "request_id": "019d0120-7b59-7eab-b837-a7af38ea3db2"
}
```

## Top up

Debit is in **USDT** from your settlement balance (`amount` + `fee`).

```http theme={null}
POST https://api.imbawallet.com/partner/cards/{card_id}/topups
Content-Type: application/json

{
  "amount_usdt": "250.00",
  "ext_id": "topup-20260710-009"
}
```

```json theme={null}
{
  "ext_id": "topup-20260710-009",
  "topup_id": "019d0128-aaaa-7bbb-8ccc-ddddeeeeffff",
  "card_id": "00112233445566778899aabb",
  "amount": "250.00",
  "fee": "1.25",
  "status": "accepted"
}
```

Terminal result: webhook `card_topup.status_changed` or document poll. Card must be `active`.

## Freeze

```http theme={null}
POST https://api.imbawallet.com/partner/cards/{card_id}/freeze
Content-Type: application/json

{
  "ext_id": "freeze-20260710-001",
  "reason": "user_request"
}
```

Returns `202`. Result via webhook `card_freeze.status_changed` / documents.\
**Unfreeze is not available in v1** of Partner API (contact support / ops).