Skip to main content
If you sell Kalixo catalog products, such as gift cards and game keys, you use both products:
  • 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.
This guide connects the two: pay, receive the webhook, order the codes, deliver them, and refund what could not be delivered.

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 differ in a few conventions. Keep them apart in your code: 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, the productCode, 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.
Store an order in your database first, with its own ID (for example 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 are 10000 (EUR 100.00):
Show it with Kalixo.js or redirect to 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.
Placing the Distribution order in a background job keeps the webhook response under 10 seconds. See Webhooks.

4. Place the Distribution order

Use your order ID as the externalOrderCode. If the job runs twice, or you retry after a timeout, Distribution returns the existing order instead of buying the codes again. See Idempotency.
Send the catalog 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 after estimatedReadyAt 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 is 5000.
The refund is pending until refund.succeeded arrives. See Captures, cancellations and refunds.

Test the whole flow in the sandbox

Use both sandboxes together:
  1. Pay a Checkout sandbox session with the test card 4111 1111 1111 1111.
  2. 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.
  3. Use a Checkout amount that matches the test product: for example 998 (GBP 9.98) in GBP for two GBP 4.99 test cards.