Integration guide
Walked through in SDK mode. For HPP, replace step 2 with a redirect; for H2H, replace step 2 with collecting the card yourself and encrypting the fields. Everything else is identical.
1. Four calls, end to end
# 1) Server-side: create a client session, get a client token
curl -X POST https://api.baton.example/v1/checkout/sessions \
-H "Authorization: Bearer sk_live_xxx" \
-H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
-H "Content-Type: application/json" \
-d '{"reference_id":"OR20261116000104","amount":8900,"currency":"USD"}'
# 2) Client-side: render checkout with the client_token, receive a payment_method token
# Card fields live in an iframe on our origin — never your page, never your servers
# 3) Server-side: create the payment
curl -X POST https://api.baton.example/v1/payments \
-H "Authorization: Bearer sk_live_xxx" \
-H "Idempotency-Key: 01J8ZQ4T7M2K9F3C" \
-H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a9c2e" -H "X-Signature: v1=..." \
-H "Content-Type: application/json" \
-d '{"reference_id":"OR20261116000104","amount":8900,"currency":"USD",
"payment_method":{"token":"pm_7c2a91f4"}}'
# 4) Receive the webhook. The final outcome is the webhook, not step 3's response. Never store or reuse a client token. It is bound to one pending payment; leaking it hands over the right to initiate that payment.
2. Authentication and signing
Reads need only the bearer token; every write must also be signed. Payouts and raw card data go one level further, with Ed25519 signatures and field-level digital envelopes.
| Level | Applies to | Scheme |
|---|---|---|
L0 | Reads, creating a client session | TLS + Bearer sk_live_... |
L1 | All writes | Bearer + HMAC-SHA256 signature |
L2 | Payouts, raw card data | Ed25519 signature + field encryption |
What the signature actually protects (no, HTTPS is not enough)
TLS secures the link across the public internet. The signature is end-to-end — it covers the things TLS cannot:
| Threat | TLS | Body signature |
|---|---|---|
| Eavesdropping or tampering on the public link | ✅ | ✅ (second layer) |
| Tampering after TLS terminates: the hop from CDN / WAF / gateway to your backend is plaintext, and a corporate TLS-inspecting proxy can rewrite it too | ❌ | ✅ |
| Replay: resending a refund you legitimately sent earlier | ❌ | ✅ via timestamp + nonce |
Cross-endpoint replay: taking the signature from /refund and firing it at /capture | ❌ | ✅ via METHOD and path in the signing string |
| Non-repudiation: a later dispute claiming "we never sent that" | ❌ | ✅ the stored signature is the evidence |
Leaving METHOD or path out of the signing string is a real source of incidents. Sign the body alone and the same signature over {"amount":2000} works for both a refund and a capture. That is why the signing string has six segments rather than just the body.
Why payouts switch to asymmetric signing
HMAC means both sides hold the same key: if our database is breached, your requests can be forged. With Ed25519 the private key never leaves you and we store only the public key — we can verify, we cannot sign. Payouts carry the largest loss exposure, and that is worth the extra complexity.
The signing string
Six segments joined by newlines, in a fixed order. The sixth is the hex SHA-256 of the raw request bytes — do not deserialise and re-serialise before hashing. JSON key order, whitespace and escaping differ between languages, so any round-trip guarantees a mismatch.
v1 POST /v1/payments 1763280000 7f3a9c2e e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
Headers
Authorization | Bearer sk_live_xxx |
X-Signature-Version | v1, so the algorithm can be rotated later |
X-Timestamp | Unix seconds. Rejected beyond ±300s of server time |
X-Nonce | Random string, unique within 10 minutes, for replay protection |
X-Signature | hex(hmac_sha256(secret, signing string)). Compared in constant time |
We do not encrypt the whole payload: the gateway could not route it, logs could not be debugged, your integration cost would double, and the benefit over TLS is marginal. Only card numbers, CVVs and payout account details go through envelope encryption.
3. Idempotency and retries
Every POST must carry an Idempotency-Key; derive it from your own order reference. Replaying the same key within 24 hours returns the original result; the same key with a different body returns 409 rather than quietly creating a second payment.
| Situation | What to do |
|---|---|
| Network timeout, no response received | Retry with the same key, or call GET /v1/payments/{uid} to find out what actually happened |
5xx / 503 returned | Retry with the same key, exponential backoff |
4xx returned | The request itself is wrong. Fix it and send again with a new key |
429 returned | Stop immediately and wait for Retry-After. Continuing will get you temporarily blocked |
On a retry, X-Nonce and X-Timestamp must be new while Idempotency-Key must stay the same. They do opposite jobs — do not mix them up.
4. Three state rules that will never change
failedandcancelledare terminal. A late success webhook will not flip them back — if one genuinely has to be reversed, it goes through manual remediation, never an automatic path.timeoutis not a failure. It means "outcome unknown". Retrying it as a failure risks a double charge; query the payment to converge, or wait for reconciliation.- Never retry a hard decline. With
decline_type=hard(lost, stolen, blocked by risk) a retry only makes the risk profile worse, so we stop cascading immediately.
To decide what you may do next, read available_actions and is_terminal from the response — do not infer it from the status enum yourself. Those two are computed server-side, and the enum will grow.
5. Webhooks
A synchronous response is the state *right now*; the final outcome comes from the webhook. Webhooks are signed with HMAC, because that is the cheapest thing for you to verify:
X-Signature: t=1763280000,v1=5d41402a...,v1=7d793037...
The signing string is {timestamp}.{raw body}. v1 appears twice during rotation — old and new key each sign once, and verifying against either is enough, so you never need downtime to rotate.
Four hard requirements on your endpoint
- Verify before you parse. On a bad signature return 401 and discard — do not persist it.
- Dedupe on the event
id. Events are redelivered; processing one refund twice is real money. - Order by
updated. Delivery order is not guaranteed; drop stale states by timestamp, never by arrival order. - Return 2xx within 5 seconds. Slower counts as a failure and is redelivered at 1 / 2 / 3 / 4 minutes; repeated failures suspend delivery and raise an alert in the console.
Events
| Event | Description | payload |
|---|---|---|
payment.status_changed | Payment status changed (authorized, captured, failed or cancelled) | Payment |
refund.status_changed | Refund status changed. **A provider may reject a refund days after you requested it, and this event is the only way you will know** | Refund |
payment.operation_failed | A capture, void or refund failed at the provider | Payment |
payment_attempt.requires_action | An attempt needs an external action (3DS redirect, QR code, redirect) | Attempt |
payout.status_changed | Payout status changed | Payout |
dispute.opened | A new dispute was opened — note the evidence deadline | Dispute |
dispute.status_changed | Dispute status changed (evidence accepted, won, lost) | Dispute |
routing.evaluation_failed | Routing rule evaluation failed (a rule references a disabled provider, or a condition field is misspelled). The default route is used, but you need to know | SimulateResult |
settlement.ready | A settlement batch has been booked and reconciled; its line items are ready to pull | Settlement |
6. Pre-launch checklist
- Idempotency keys are derived from your order reference, not generated randomly and thrown away — otherwise you cannot reproduce the key on a retry.
- Your webhook endpoint dedupes and orders events, and verifies the signature before parsing.
- Amounts are integers in the minor unit everywhere, converted with
currency_exponentonly at display time. Never do money arithmetic in the browser. - No keys in the repository, the frontend bundle or the logs; logging has a regex-based redaction fallback.
- You have exercised the failure paths in test: hard decline, timeout, duplicate webhook, over-refund. Testing only the happy path is not testing.
When something does not add up: send us the request_id from the response, or check the error code reference first — nine times out of ten it is in that table. →