Five endpoints, one signing scheme, and one rule that governs everything else:
an order is a fulfilment instruction, and it is accepted before it is
finished.
This is a separate service from the Partner API. It does not use API-KEY,
it is not under /api/v0, and it does not take an Api-Version header.
Requests are signed with HMAC-SHA256, and money is in integer minor units
rather than decimal strings.
The five endpoints
The integration in three steps
- Read the catalogue and cache it.
GET /catalog/products
tells you which canonical_sku values exist and which amounts each accepts.
- Place the order with an
Idempotency-Key. You get an order_id back
immediately, in state PENDING.
- Poll, then retrieve. When the order reaches
FULFILLED, the codes are
available from the voucher endpoint.
There is no confirmation step and no cancellation endpoint. An accepted
order either fulfils or produces a refund obligation, so validate before you
send rather than after.
The rule that costs money if you miss it
An item can reach FULFILLED having produced fewer vouchers than ordered.
Three cards were sourced; two were not. The shortfall carries a refund
obligation.
Bill your customer from voucher_count and the vouchers you actually
retrieved, not from what you ordered. They are usually the same number, which
is exactly why the failure is easy to miss.
Where to next
- Signing requests — the canonical string, and the four rules that decide whether it verifies
- Conventions — money, identifiers, rate limits, pagination
- Order lifecycle — the six states and how to poll them
- Worked flows — the happy path, recovering a lost response, and a short fulfilment
