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

# Gift cards

> Buy retail gift cards and eVouchers, charged to your wallet, and read the delivered code.

Retail gift cards and eVouchers from GTW's supplier (Sochitel). The price is
the supplier's price less GTW's discount to you, charged to your **NGN
wallet** by default (or USD if you ask) at GTW's exchange rate.

| Method | Path (API key) | Scope |
| - | - | - |
| GET | `/gift-cards/operators?currency=NGN\|USD` | `giftcards:read` |
| GET | `/gift-cards/operators/:operatorId?currency=` | `giftcards:read` |
| POST | `/gift-cards/purchases` — `operator, product, recipient, amount, currency?, extraParameters?, customerReference?` + **`Idempotency-Key`** | `giftcards:purchase` |
| GET | `/gift-cards/purchases?limit`, `/gift-cards/purchases/:id` | `giftcards:read` |
| GET | `/gift-cards/purchases/:id/code` | `giftcards:purchase` |

The same routes exist for the dashboard under
`/organizations/:orgId/gift-cards/…` (roles with `bookings:read` / `bookings:create`).

**Flow.** `operators` lists each brand with its products. A product's
`amount` is its face value in the brand's currency (`fixed`, or a `range` you
choose within); its `price` is what that costs you, `min` to `max`, in the
wallet currency you asked for. `purchases` takes the face value as `amount`
(a decimal string) and `currency` as the wallet to charge — you never send a
price. `recipient` is who the card is for (an email or phone number, as the
product requires).

* `201` `fulfilled`: delivered. Read the code from `/purchases/:id/code`.
* `202` `pending`: the supplier is still processing; poll the purchase.
* `202` `refunded`: the supplier failed or rejected it; `refunded` is the
  full price, already back in your wallet. (`refund_pending` for the moment
  in between.)
* `202` `needs_attention`: the outcome is unknown after 30 minutes. GTW
  resolves it by hand; it is never refunded automatically, because the card
  may have been delivered.
* `402 insufficient_funds` / `credit_limit_exceeded` / `invoice_overdue`:
  nothing was bought. Top up and retry **with the same Idempotency-Key**.
* `409 idempotency_conflict`: that key was used for a different purchase.
* `503 giftcards_unavailable`: the problem is on GTW's side; retry later.

Retrying with the same `Idempotency-Key` never buys or charges twice. There
is no cancel: a delivered gift card cannot be voided.

**The code.** `GET …/code` returns `{ pin: { number, serial } | null,
instructions }` and is never cached (`409 code_not_ready` until delivered,
`409 no_code` if the purchase failed). It is stored encrypted and appears in
no other response. An API key with `giftcards:purchase` can read any of its
organisation's codes; in the dashboard only the member who bought a card can
read its code.

**Sandbox.** Purchases are simulated. Recipient `fake-pending` stays pending
until the next poll (up to a minute), `fake-failed` and `fake-rejected` are
refunded; any other recipient is delivered at once with a fake code.


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