> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atum.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> The standard x402 v2 facilitator interface served by atum-escrow

## What is the x402 facilitator?

The x402 Facilitator API implements the standard [x402](https://x402.org) v2 facilitator interface for the `atum-escrow` scheme. A resource server calls [/verify](/api-reference/x402/verify) then [/settle](/api-reference/x402/settle) to validate and settle a payment credential. Any facilitator that serves this contract is interchangeable behind it.

<Note>
  There is no separate facilitator host: these operations are served by the **Payment Gateway** under the `/x402/v1` prefix. See [Base URLs](#base-urls).
</Note>

## How it works

1. **Payer constructs a payment** — signed credential (`AtumEscrowPayload`) plus the selected `PaymentRequirements` from the HTTP 402 response, including a [purchase identifier](/get-started/reference/glossary#purchase-identifier) when the acceptance side requires the `payment-identifier` extension
2. **Resource server calls [/verify](/api-reference/x402/verify)** — the facilitator validates the credential, settlement-vault terms, and identity binding without moving funds
3. **Resource server calls [/settle](/api-reference/x402/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](/payment-protocols/idempotency)

<Warning>
  **A `success: false` from [/settle](/api-reference/x402/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](/payment-protocols/mpp/overview) if you need the merchant to poll the gateway to a terminal state. See [Idempotency](/payment-protocols/idempotency).
</Warning>

## Endpoints

| Method | Path                                        | Purpose                                               |
| ------ | ------------------------------------------- | ----------------------------------------------------- |
| `POST` | [/verify](/api-reference/x402/verify)       | Validate a payment credential. Does not move funds.   |
| `POST` | [/settle](/api-reference/x402/settle)       | Submit a validated payment for settlement.            |
| `GET`  | [/supported](/api-reference/x402/supported) | Discover supported scheme/network/token combinations. |

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

| Environment | Facilitator base URL                                     |
| ----------- | -------------------------------------------------------- |
| Testnet     | `https://payment-gw.production-testnet.atum.xyz/x402/v1` |
| Mainnet     | `https://payment-gw.production-mainnet.atum.xyz/x402/v1` |

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](/get-started/reference/endpoints) for every hosted URL.