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, which Atum’s facilitator requires
  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. If settlement takes longer than the gateway waits, it reports settlement_pending with the payment id, and the payer re-attempts the same purchase
A success: false from /settle is not always a failure. x402 has no in-band pending outcome, so a payment that is still settling also comes back as success: false. Read errorReason. What the payer does for each one: When a payment is still settling.

​
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.