Skip to main content
Fulfilment is the one step you must get right. Browser events and redirects tell the shopper what happened; they are not proof of payment. Confirm every order on your server, from Kalixo’s records, before you deliver.
Never fulfil from payment.completed in Kalixo.js, a return_url redirect, or checkout_session.status. Anyone can open your return_url with a session ID. Treat a webhook as a trigger to check the payment, not as the proof itself.

The rule

Deliver an order only when the payment you read with GET /v1/payments/{id} has:
  • status captured (or authorized with manual capture, if you ship before you capture),
  • amount_captured (or amount_authorized) equal to your order total, in the minor unit: 4999 for EUR 49.99,
  • currency equal to your order currency,
  • amount_mismatch false.

The flow

1

Create the session on your server

Set the amount, currency and your reference. This amount is the only amount Kalixo will charge. See the Quickstart.
2

Receive the webhook

Listen for payment.captured on your webhook endpoint. Verify the Kalixo-Signature against the raw body, answer 2xx within 10 seconds, then process asynchronously.
3

Read the payment

Call GET /v1/payments/{id} with the ID from the event and apply the rule above to Kalixo’s record, not to the webhook body.
4

Fulfil exactly once

Key fulfilment on the payment ID or your reference, so a duplicate delivery or a replay never delivers twice.
5

Reconcile

Match captures, refunds and chargebacks to your orders with the financial_transactions report.

Verify and fulfil

Manual capture

With capture_method: "manual" you can ship on payment.authorized and capture when you ship. Apply the same check to status: authorized and amount_authorized. Capture promptly: authorisations expire after a few days, depending on the payment method. See Captures, cancellations and refunds.

Other outcomes

Missed webhooks

Delivery is at least once, and Kalixo retries for about 3 days. If your endpoint was down longer, list events with GET /v1/events (kept for 30 days) or read the payment directly, and apply the same rule.