Create a payment by posting to POST /payments on the Checkout.com Unified Payments API with 'source.type' of 'card' (for raw PAN, requires SAQ-D or a vault token from Frames.js), 'amount' as integer minor units, 'currency' as ISO 4217 uppercase, and 'processing_channel_id' identifying your business.
If the response 'status' is 'Pending' and '_links.redirect.href' is present, redirect the cardholder to complete 3DS; if status is 'Authorized', the payment succeeded without challenge.
Configure a webhook endpoint in the Checkout.com dashboard and subscribe to 'payment_approved', 'payment_declined', 'payment_captured', and 'payment_refunded' event types.
When a webhook arrives, extract the 'authorization' header value — this is an HMAC-SHA256 signature computed by Checkout.com using your webhook signature key over the raw request body.
Verify: compute HMAC-SHA256 of the raw request body bytes using your webhook secret, base64-encode the result, and compare to the 'authorization' header value with a constant-time comparison.
After verification, read 'data.id' (the payment ID) and 'type' to determine the event; call GET /payments/{id} to fetch the canonical payment state before acting on it.
Known gotchas
Checkout.com uses minor units like Stripe — amounts for JPY should not be multiplied by 100, while USD amounts should; confirm each currency's exponent from the API docs.
The webhook 'authorization' header changes format between API versions; the current format is a direct base64-encoded HMAC-SHA256 without a prefix, not a 'sha256=' prefix format used by some other providers.
Payments in 'Pending' status are not yet authorized; capturing or refunding a payment before it reaches 'Authorized' will return a 4xx error — always check the canonical status via GET /payments/{id} before write operations.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp