SixPay sends order and subscription lifecycle events to the active webhook endpoint configured for a merchant tenant. Treat these signed events, rather than browser UI state or a submitted transaction, as payment confirmation.

​
Required handling

  1. Preserve the raw HTTP request body before parsing JSON.
  2. Fetch and cache signing keys from GET /v1/signing-keys.
  3. Verify x-sixpay-signature, x-sixpay-keyid, x-sixpay-timestamp, and x-sixpay-nonce against the raw body.
  4. Reject replayed nonces and stale requests according to the signature policy.
  5. Deduplicate deliveries using the payload’s id.
  6. Route the event by type, then update the merchant order or subscription state idempotently.

​
Delivery guarantees

Every delivery is a JSON POST with the following headers: SixPay considers any 2xx response delivered. Non-2xx, network, and timeout failures are retried with exponential backoff, up to the configured delivery limit. A delivery can be repeated, so id must be your idempotency key.

​
Correlate an order

Use order.intentId as the primary SixPay payment key. Use order.merchantOrderId to locate the merchant order created before checkout session creation. Store both values, the event id, event timestamp, status, and relevant transaction hashes. Do not mark an order paid from a modal close or client-side callback alone.

​
Correlate a subscription

Subscription events carry subscriptionId, chainId, and transactionHash at the top level. Persist the subscription ID alongside the merchant’s own account or entitlement record. A successful recurring payment is authoritative only after the corresponding subscription.payment_succeeded event. See Subscription payments for the distinction between subscription creation and a successful collection.

​
Event types

Order events: order.locked, order.paid, order.delivered, order.force_delivered, order.refunded, and order.expired. Subscription events: subscription.created, subscription.payment_succeeded, subscription.failed, subscription.cancelled, and subscription.expired. The payload fields are documented in Webhook events and Subscription webhook events. Process redeliveries safely: an already-applied id must have no additional effect.