- Kalixo Checkout takes the shopper’s payment, with Kalixo as merchant of record.
- The Distribution API places the order for the codes and returns them.
Before you start
- Distribution API keys (
kal_test_…,kal_live_…) and your egress IPs whitelisted. See Authentication. - Checkout keys (
kc_sk_test_…,kc_pk_test_…) and your checkout domains registered. See Authentication. - A Checkout webhook endpoint. See Webhooks.
- How Checkout payouts and Distribution orders are settled for your account (wallet or invoice). Your Kalixo account manager confirms this during onboarding.
The two APIs were designed separately: the Distribution API is a server-to-server ordering
API for resellers, and Checkout follows the conventions of common payment APIs. Use a
separate client and separate keys for each.
1. Price the order on your server
Read the products the shopper wants from the Distribution catalog and keep, per line, theproductCode, the row’s countryCode, the catalog price and currencyCode. Decide the
price you charge the shopper. It is your retail price, and it can differ from the
Distribution catalog price, which is what the Distribution order validates.
order-1001). You use
that ID as the Checkout reference and as the Distribution externalOrderCode.
2. Create the checkout session
Amounts are integers in the minor unit. Two EUR 50.00 cards are10000 (EUR 100.00):
session.url.
3. Wait for payment.captured
Fulfil only from the webhook, never from the browser redirect. Read the payment from Kalixo
and check it against your order before you spend money on codes. See
Fulfilment.
4. Place the Distribution order
Use your order ID as theexternalOrderCode. If the job runs twice, or you retry after a
timeout, Distribution returns the existing order instead of buying the codes again. See
Idempotency.
price here, not your retail price: Distribution validates it against the
catalog. Send country for every line; it is required for products with several markets.
If the order is rejected (4xx), nothing was bought: refund the shopper in full (step 6)
and fix the cause, for example a stale price or an insufficient wallet balance.
5. Wait for the codes and deliver them
Poll afterestimatedReadyAt until the order reaches a terminal status. The
Node reference client does this for you:
Store the codes before you show or email them, so a crash cannot lose delivered codes.
6. Refund what you could not deliver
Refund through Checkout, with an idempotency key derived from your order, so a retry never refunds twice. Amounts are in the minor unit: one missing EUR 50.00 card is5000.
pending until refund.succeeded arrives. See
Captures, cancellations and refunds.
Test the whole flow in the sandbox
Use both sandboxes together:- Pay a Checkout sandbox session with the test card
4111 1111 1111 1111. - On
payment.captured, order a Kalixo Test product on the Distribution sandbox. The Partial Completion product with quantity 2 returns one code, so you can test the partial refund. The Async Failure product tests the full refund. See Sandbox. - Use a Checkout amount that matches the test product: for example
998(GBP 9.98) inGBPfor two GBP 4.99 test cards.