> ## 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.

# Gift cards

> Offers, purchase, and receipt (epin / code).

# Gift cards

Scopes: `gift:read`, `gift:purchase`, or `gift:*`.

Catalog availability is controlled per tenant. Disabled catalog → empty offers / `503` / `catalog_disabled`. An emergency kill-switch may return `503` / `gift_disabled`.

## List offers

```http theme={null}
GET https://api.imbawallet.com/partner/gift-offers?brand=Roblox&country=US&limit=50
Authorization: Bearer <access_token>
```

Common query filters: `brand`, `country`, `limit` (max 50), `cursor`.

Offers may be **FIXED** (no `value` on purchase) or **RANGE** (`min_value` / `max_value` / `value_currency` — you must pass `value` on purchase).

## Purchase

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

{
  "ext_id": "gift-20260710-001",
  "offer_id": "gift-roblox-10-usd",
  "required_fields": {},
  "value": null
}
```

| Field             | Notes                                                                           |
| ----------------- | ------------------------------------------------------------------------------- |
| `ext_id`          | Required, idempotent                                                            |
| `offer_id`        | From catalog                                                                    |
| `value`           | Required for RANGE offers (face value in offer currency); omit/ignore for FIXED |
| `required_fields` | Brand-specific fields when the catalog requires them (e.g. email)               |

### Response `202`

```json theme={null}
{
  "ext_id": "gift-20260710-001",
  "purchase_id": "019d0150-cccc-7ddd-8eee-333344445555",
  "offer_id": "gift-roblox-10-usd",
  "debit_amount": "9.80",
  "debit_currency": "USDT",
  "face_value": "10.00",
  "face_currency": "USD",
  "status": "pending",
  "created_at": "2026-07-10T11:00:00.000Z",
  "request_id": "019d0120-7b59-7eab-b837-a7af38ea3db2"
}
```

Webhook `gift_purchase.status_changed` — **without** code/epin.\
Fetch the receipt via GET.

Errors: `catalog_disabled`, `unknown_offer` / `offer_unavailable`, `missing_required_field`, `invalid_value`, `catalog_stale`, `insufficient_balance`, `gift_disabled`, `ext_id_conflict`.

## Get purchase / receipt

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

After `completed`:

```json theme={null}
{
  "purchase_id": "019d0150-cccc-7ddd-8eee-333344445555",
  "ext_id": "gift-20260710-001",
  "offer_id": "gift-roblox-10-usd",
  "status": "completed",
  "face_value": "10.00",
  "face_currency": "USD",
  "receipt": {
    "epin": "XXXX-YYYY-ZZZZ",
    "voucher_id": null,
    "redemption_url": null,
    "expires_at": null,
    "instructions": null
  },
  "created_at": "2026-07-10T11:00:00.000Z",
  "completed_at": "2026-07-10T11:00:45.000Z",
  "request_id": "019d0120-7b59-7eab-b837-a7af38ea3db2"
}
```

The redemption secret field is `epin` (not a generic `code`). Do not log plaintext receipts.