Skip to main content
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. 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.