● Integration guide

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
Create a client sessionBind amount, order reference and customer; receive a client token that expires in 24 hours
2
Render checkoutMount the SDK with your publishable key and the client token; get back a payment_method token
3
Create the paymentServer-side, with an idempotency key and a signature. Routing picks a provider; soft declines cascade automatically
4
Receive webhooksVerify → dedupe → order → return 2xx within 5 seconds
# 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.

LevelApplies toScheme
L0Reads, creating a client sessionTLS + Bearer sk_live_...
L1All writesBearer + HMAC-SHA256 signature
L2Payouts, raw card dataEd25519 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:

ThreatTLSBody 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

AuthorizationBearer sk_live_xxx
X-Signature-Versionv1, so the algorithm can be rotated later
X-TimestampUnix seconds. Rejected beyond ±300s of server time
X-NonceRandom string, unique within 10 minutes, for replay protection
X-Signaturehex(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.

SituationWhat to do
Network timeout, no response receivedRetry with the same key, or call GET /v1/payments/{uid} to find out what actually happened
5xx / 503 returnedRetry with the same key, exponential backoff
4xx returnedThe request itself is wrong. Fix it and send again with a new key
429 returnedStop 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

  • failed and cancelled are 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.
  • timeout is 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

EventDescriptionpayload
payment.status_changedPayment status changed (authorized, captured, failed or cancelled)Payment
refund.status_changedRefund 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_failedA capture, void or refund failed at the providerPayment
payment_attempt.requires_actionAn attempt needs an external action (3DS redirect, QR code, redirect)Attempt
payout.status_changedPayout status changedPayout
dispute.openedA new dispute was opened — note the evidence deadlineDispute
dispute.status_changedDispute status changed (evidence accepted, won, lost)Dispute
routing.evaluation_failedRouting rule evaluation failed (a rule references a disabled provider, or a condition field is misspelled). The default route is used, but you need to knowSimulateResult
settlement.readyA settlement batch has been booked and reconciled; its line items are ready to pullSettlement

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_exponent only 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. →