> ## 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. # Settle payment > Submits the request to the Atum network for settlement and resolves synchronously when the payment is delivered, within the requirement's maxTimeoutSeconds. Returns the settlement transaction and network plus the settlement receipt (also carried to the payer in the PAYMENT-RESPONSE header). Asynchronous settlement beyond the synchronous window is a deferred extension. ## OpenAPI ````yaml POST /settle openapi: 3.1.0 info: title: x402 Facilitator API (atum-escrow) version: 1.0.0 description: > The standard x402 v2 facilitator API as served for the atum-escrow scheme. A resource server calls /verify then /settle to validate and settle a payment credential, and /supported to discover which scheme/network/token combinations the facilitator can handle. The atum-escrow request/response shapes are defined by referenced JSON Schemas; this document specifies the endpoints and the atum-escrow-specific behavior. Any facilitator that serves this contract is interchangeable behind it. servers: - url: https://payment-gw.production-mainnet.atum.xyz/x402/v1 description: Mainnet - url: https://payment-gw.production-testnet.atum.xyz/x402/v1 description: Testnet security: [] paths: /settle: post: summary: Submit a validated payment for settlement. description: > Submits the request to the Atum network for settlement and resolves synchronously when the payment is delivered, within the requirement's maxTimeoutSeconds. Returns the settlement transaction and network plus the settlement receipt (also carried to the payer in the PAYMENT-RESPONSE header). Asynchronous settlement beyond the synchronous window is a deferred extension. operationId: settle requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/FacilitatorRequest' responses: '200': description: The synchronous settlement result. content: application/json: schema: $ref: '#/components/schemas/SettleResponse' components: schemas: FacilitatorRequest: type: object description: The shared request body for /verify and /settle. required: - x402Version - paymentPayload - paymentRequirements properties: x402Version: type: integer const: 2 paymentPayload: $ref: '#/components/schemas/AtumEscrowPayload' description: > The payer's signed credential. Its payload.paymentRequest conforms to the canonical PaymentRequest declaration and carries the PaymentRequestEnvelope (PRE) identity binding. paymentRequirements: $ref: '#/components/schemas/PaymentRequirements' description: The single requirement the payer selected from the 402. SettleResponse: type: object description: > The synchronous settlement result — the standard x402 SettleResponse fields plus the Atum settlement receipt. required: - success - transaction - network properties: success: type: boolean transaction: type: string description: Destination settlement transaction hash. network: type: string description: CAIP-2 destination chain id. payer: type: string errorReason: type: string description: Present when success is false. extensions: type: object description: Facilitator-specific members. See AtumExtension for the atum one. properties: atum: $ref: '#/components/schemas/AtumExtension' fulfillmentConfirmation: type: object additionalProperties: true description: >- Full settlement receipt; also returned to the payer in PAYMENT-RESPONSE. AtumEscrowPayload: title: AtumEscrowPayload description: >- The PAYMENT-SIGNATURE credential body for the atum-escrow x402 scheme — a v2 PaymentPayload whose `accepted` echoes the selected requirement and whose `payload.paymentRequest` is the signed payment request. The inner paymentRequest conforms to the canonical PaymentRequest declaration (declarations/PaymentRequest/v1); only the scheme-critical fields the facilitator checks are constrained here and the rest is permitted, so a full PaymentRequest validates without being restated. The identity-binding `presentation` (PaymentRequestEnvelope) is REQUIRED for atum-escrow conformance but is optional at the schema level so a request may be validated before the envelope is attached; the facilitator enforces its presence and re-verifies it. Addresses are chain-general: an EVM `0x`-hex address (20 bytes) or a base58-encoded address (Solana/Tron), per the field's CAIP-2 chain. type: object additionalProperties: true required: - x402Version - accepted - payload properties: x402Version: const: 2 description: x402 protocol version; always 2. accepted: type: object additionalProperties: true description: >- Echo of the selected 402 requirement, checked for equality against the separately-supplied requirement at verify time. required: - scheme - network - asset - payTo - amount - maxTimeoutSeconds - extra properties: scheme: const: atum-escrow network: type: string pattern: ^[-a-z0-9]+:.+$ asset: type: string pattern: ^(0x[0-9a-fA-F]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$ payTo: type: string pattern: ^(0x[0-9a-fA-F]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$ amount: type: string pattern: ^[0-9]+$ maxTimeoutSeconds: type: integer minimum: 1 extra: type: object required: - atum properties: atum: type: object extensions: type: object additionalProperties: true description: >- x402 extension data, echoed from the `extensions` map the resource server advertised in its 402 response with the payer's own values added. Per the x402 specification a client must include at least the information it received and may append to it, but may not remove or overwrite it. Kept open so that extensions unrelated to this scheme pass through untouched. The `atum-escrow` scheme uses the standard `payment-identifier` extension as the payment's idempotency key. It is REQUIRED for atum-escrow conformance but optional at the schema level, so that a payload can be validated before its extensions are attached; the facilitator enforces its presence and re-derives `request_id` from it. properties: payment-identifier: type: object additionalProperties: true description: >- The payment's idempotency key, as defined by the x402 payment-identifier extension. properties: info: type: object $comment: >- additionalProperties is deliberately left IMPLICIT here rather than stated as `true`, even though the surrounding objects state it. Both mean the same thing to a validator, but go-jsonschema emits an UnmarshalJSON for an open object that also carries a constrained property which references an undeclared `raw` variable, so the generated Go package does not compile. It only declares `raw` for an object with required properties, and this one has none. `id`'s length and pattern constraints are worth more than the generated AdditionalProperties convenience field, so the constraints stay and the keyword goes. description: >- The extension's data. The resource server advertises `required`; the payer adds `id`. properties: required: type: boolean description: >- Whether the resource server requires payers to supply an identifier. Always true for atum-escrow, which cannot make a payment retry-safe without one. id: type: string minLength: 16 maxLength: 128 pattern: ^[a-zA-Z0-9_-]+$ description: >- The payer's identifier for the purchase being paid for: one value per purchase, the same value on every re-attempt of that purchase, and never shared between two purchases. `request_id` is derived from this value together with the source account, and the network de-duplicates on `request_id` — so reusing it on a re-attempt resolves to the original payment instead of taking a second one, while a fresh value starts a new payment. payload: type: object additionalProperties: false required: - paymentRequest properties: paymentRequest: type: object additionalProperties: true description: >- The signed payment request; conforms to the canonical PaymentRequest declaration (declarations/PaymentRequest/v1). Only the scheme-critical fields the facilitator checks are required here, the rest is permitted. required: - version - request_id - source - destination - fulfillment_amount - max_source_amount - quote_deadline - fulfillment_deadline - sender_auth properties: version: type: string request_id: type: string source: type: object additionalProperties: true required: - asset_identifier - account properties: asset_identifier: type: string account: type: string pattern: ^(0x[0-9a-fA-F]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$ destination: type: array minItems: 1 items: type: object additionalProperties: true required: - asset_identifier - account properties: asset_identifier: type: string account: type: string pattern: ^(0x[0-9a-fA-F]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$ fulfillment_amount: type: string pattern: ^[0-9]+$ max_source_amount: type: string pattern: ^[0-9]+$ quote_deadline: type: string format: date-time fulfillment_deadline: type: string format: date-time sender_auth: type: object additionalProperties: true required: - message_scheme - signed_messages properties: message_scheme: enum: - EVM_PERMIT2 - EVM_PERMIT2_ESCROW - SOLANA - TRON description: >- Sender-auth signature scheme. Wire-valid values mirror the canonical PaymentRequest SenderAuthMessageScheme; which of them a given facilitator actually verifies is a capability the facilitator enforces, not a schema constraint. signed_messages: type: array minItems: 1 items: type: object additionalProperties: true required: - message - signature properties: message: type: string message_prehash: {} signature: type: string presentation: type: object additionalProperties: true description: >- Identity binding — a holder-signed W3C VerifiablePresentation (PaymentRequestEnvelope; conforms to declarations/PaymentRequestEnvelope/v1) that binds this request to the payer. REQUIRED for atum-escrow conformance; optional at the schema level so a request may be validated before the envelope is attached. Only the binding-critical fields are constrained here; the full envelope validates against the canonical declaration. The facilitator re-verifies it: proofPurpose 'authentication', proof.challenge equals the request's request_hash (content hash of the request), proof.domain the network-wide verifier id, and holder equal to source.account. required: - type - holder - verifiableCredential - proof properties: type: type: array description: >- MUST contain 'VerifiablePresentation' per W3C VC Data Model v1.1. contains: const: VerifiablePresentation items: type: string holder: type: string pattern: ^did:pkh:[a-z][a-z0-9]*:[a-zA-Z0-9._:%-]+$ description: did:pkh of the payer; MUST equal source.account. verifiableCredential: type: array minItems: 1 items: type: object additionalProperties: true proof: type: object additionalProperties: true required: - proofPurpose - challenge - domain properties: proofPurpose: const: authentication description: >- Always 'authentication' for a VerifiablePresentation proof. challenge: type: string minLength: 1 description: >- Equals the request's request_hash (content hash of the request). domain: type: string minLength: 1 description: >- Network-wide verifier identifier, did:web:.atum.xyz. PaymentRequirements: type: object description: > One atum-escrow payment requirement (a 402 accepts[] entry). payTo is the source-chain escrow contract, not the payee; the payee is extra.atum.destination.address. required: - scheme - network - asset - payTo - amount - maxTimeoutSeconds - extra properties: scheme: type: string const: atum-escrow network: type: string description: CAIP-2 source chain id. asset: type: string description: Source token contract address. payTo: type: string description: Source-chain escrow contract address. amount: type: string description: Advisory source spend cap in atomic units. maxTimeoutSeconds: type: integer minimum: 1 description: Relative bound on the synchronous settlement hold. extra: type: object required: - atum properties: atum: $ref: '#/components/schemas/AtumEscrowExtra' AtumExtension: type: object description: > What this facilitator has to say beyond the standard members. It rides under `extensions.atum` rather than beside `errorReason` because the x402 response shape is fixed by the specification and `extensions` is what it provides for a facilitator with something of its own to add. A client that does not know the member ignores it. properties: paymentId: type: string description: > The Atum payment this answer is about. Present only once the network has named one, because a merchant correlates its fulfilment against it and an id-shaped blank correlates against nothing. state: type: string description: The payment's state as the network last reported it. statusUrl: type: string description: Where to poll the payment, when a public origin is configured. retryClassification: $ref: '#/components/schemas/RetryClassification' AtumEscrowExtra: title: AtumEscrowExtra description: >- The `extra.atum` object carried inside an atum-escrow x402 PaymentRequirements entry (accepts[]): the merchant's receive-side plus the contract/role addresses and deadline budgets. Scheme-specific data the standard x402 `extra` bag treats as opaque, so it is owned here and shared by all role mechanisms. Addresses are chain-general: an EVM `0x`-hex address (20 bytes) or a base58-encoded address (Solana/Tron), per the field's CAIP-2 chain. type: object additionalProperties: false required: - destination - fulfillmentAmount - escrow - fulfillmentProxy - reserver - releaser - fulfillmentVerifierEndpoint - quoteDeadlineSeconds - fulfillmentDeadlineSeconds properties: destination: type: object additionalProperties: false description: Where the merchant receives (CAIP-2 chain, token, address). required: - network - asset - address properties: network: type: string pattern: ^[-a-z0-9]+:.+$ description: CAIP-2 destination chain id (e.g. eip155:42161). asset: type: string pattern: ^(0x[0-9a-fA-F]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$ description: >- Destination token contract address (EVM hex or base58, per the destination chain). address: type: string pattern: ^(0x[0-9a-fA-F]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$ description: >- Merchant receive address (EVM hex or base58, per the destination chain). fulfillmentAmount: type: string pattern: ^[0-9]+$ description: Exact amount the merchant receives, in atomic token units. escrow: type: string pattern: ^(0x[0-9a-fA-F]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$ description: >- Source-chain escrow contract (the x402 payTo); EVM hex or base58, per the source chain. fulfillmentProxy: type: string pattern: ^(0x[0-9a-fA-F]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$ description: >- Destination-chain fulfillment proxy contract (EVM hex or base58, per the destination chain). reserver: type: string pattern: ^(0x[0-9a-fA-F]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$ description: >- Atum reserver role address (escrow deposit witness); EVM hex or base58, per the source chain. releaser: type: string pattern: ^(0x[0-9a-fA-F]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$ description: >- Atum releaser role address (escrow deposit witness); EVM hex or base58, per the source chain. fulfillmentVerifierEndpoint: type: string format: uri description: >- Source-chain fulfillment-verifier endpoint the payment request carries. The verifier account and the quote_selector are the releaser and reserver respectively (the network derives the deposit witness roles from them), so only the endpoint is not otherwise present in this object. quoteDeadlineSeconds: type: integer minimum: 1 description: >- Recommended quote-deadline budget in seconds, relative to signing time. fulfillmentDeadlineSeconds: type: integer minimum: 1 description: >- Recommended fulfillment-deadline budget in seconds, relative to signing time. svmSignatureClusterId: type: string description: >- Solana source only: cluster name used to build the 32-byte cluster_id in the V3 escrow signature domain. Optional; the facilitator requires it for a Solana source. svmSignatureDomainVersion: type: integer minimum: 1 maximum: 255 description: >- Solana source only: escrow signature-domain version (V3 domain separation). Optional; required for a Solana source. RetryClassification: type: string description: > What the merchant should do about the reason alongside it, drawn from the same closed set Atum's own error responses use. Without it a merchant reading `errorReason` or `invalidReason` has a label and no instruction. Present on every answer that is not a success, including the refusals that name no payment. Absent on a success: there is nothing to retry. A pattern-constrained string rather than an enum, so a client whose generated model closes the set does not reject the whole response on a value added later. pattern: ^[A-Z][A-Z0-9_]*$ example: NOT_RETRYABLE_FIX_REQUEST ````