Skip to main content

​
What is the x402 facilitator?

The x402 Facilitator API implements the standard x402 v2 facilitator interface for the atum-escrow scheme. A resource server calls /verify then /settle to validate and settle a payment credential. Any facilitator that serves this contract is interchangeable behind it.
There is no separate facilitator host: these operations are served by the Payment Gateway under the /x402/v1 prefix. See Base URLs.

​
How it works

  1. Payer constructs a payment — signed credential (AtumEscrowPayload) plus the selected PaymentRequirements from the HTTP 402 response, including a purchase identifier when the acceptance side requires the payment-identifier extension
  2. Resource server calls /verify — the facilitator validates the credential, settlement-vault terms, and identity binding without moving funds
  3. Resource server calls /settle — the facilitator submits to the Atum network. Within the ~30s synchronous window it returns success; past that window it reports settlement_pending with the payment id so the payer can re-attempt the same purchase
A success: false from /settle is not always a failure. The facilitator confirms settlement only within a short synchronous window (~30s); x402 has no in-band pending outcome, so a still-settling payment travels as success: false too. Check errorReason:
  • settlement_pending — accepted, still settling → re-attempt the same purchase (fresh 402, re-signed credential, same purchase identifier)
  • settlement_failed — terminal → that identifier is spent; start a new purchase identifier for the same goods
  • settlement_not_accepted — nothing reached the network → retry as a fresh payment
  • any other gateway code — refused, nothing charged → fix and reuse the same identifier. The exception is IDEMPOTENCY_TERMS_MISMATCH: the identifier was reused with different money, so send the original details or use a new identifier
Do not poll inside the open request, and do not treat pending as a cue to open a second payment. Verify on-chain before paying again under a new identifier. Use MPP if you need the merchant to poll the gateway to a terminal state. See Idempotency.

​
Endpoints

​
Base URLs

Paths above are relative to a base URL that includes the /x402/v1 prefix, so /verify is https://payment-gw.production-testnet.atum.xyz/x402/v1/verify. The gateway’s own REST base URL stays a bare host — the one thing that’s easy to get wrong now that both point at the same machine. The prefix is versioned against the published facilitator contract rather than the gateway’s REST API, so a future gateway /v2 won’t move it. See Endpoints for every hosted URL.