> ## Documentation Index > Fetch the complete documentation index at: https://docs.rail402.dev/llms.txt > Use this file to discover all available pages before exploring further. # Settle a payment > Verifies the payment again and settles it on-chain: a channel account is the transaction source and the fee sponsor pays the fee through a fee bump. Settlement is idempotent per authorization: a repeated request returns the original result and moves funds once. Rejections are HTTP 200 with `success: false`, a stable `errorReason` code and a non-empty `errorMessage`. `settlement_pending` carries the transaction hash; the settlement is finished in the background. When the settled payment carries a `bazaar` extension, the `EXTENSION-RESPONSES` header reports the cataloging outcome. ## OpenAPI ````yaml /api-reference/openapi.yaml post /settle openapi: 3.1.0 info: title: Rail402 version: 0.0.0 summary: x402 facilitator and Bazaar discovery layer for Stellar. description: > The Rail402 HTTP service. `/supported`, `/verify` and `/settle` follow the x402 version 2 facilitator interface; `/discovery/*` serves the Bazaar catalog and search. Every endpoint except `/health`, `/ready` and `/metrics` is rate-limited per client address. A limited request gets HTTP 429 with a `Retry-After` header and the code `rate_limited`. license: name: Apache-2.0 identifier: Apache-2.0 servers: - url: https://testnet.rail402.dev description: Hosted testnet facilitator (stellar:testnet only, no API key) security: [] tags: - name: Facilitator description: x402 facilitator interface. - name: Discovery description: Bazaar catalog and natural-language search. - name: Operations description: Health, readiness, metrics and usage. paths: /settle: post: tags: - Facilitator summary: Settle a payment description: > Verifies the payment again and settles it on-chain: a channel account is the transaction source and the fee sponsor pays the fee through a fee bump. Settlement is idempotent per authorization: a repeated request returns the original result and moves funds once. Rejections are HTTP 200 with `success: false`, a stable `errorReason` code and a non-empty `errorMessage`. `settlement_pending` carries the transaction hash; the settlement is finished in the background. When the settled payment carries a `bazaar` extension, the `EXTENSION-RESPONSES` header reports the cataloging outcome. operationId: settlePayment requestBody: $ref: '#/components/requestBodies/FacilitatorRequest' responses: '200': description: The settlement outcome. headers: EXTENSION-RESPONSES: $ref: '#/components/headers/ExtensionResponses' content: application/json: schema: $ref: '#/components/schemas/SettleResponse' examples: settled: summary: The settlement of the recorded canonical client run value: success: true transaction: >- 9cd39ec85e02bf9d009d3d790801fa860557a3120b06d7b721d2ba55d7631fe5 network: stellar:testnet payer: GDQMM2IJX6XCBTEW7J242PBXG3HQCKIF2N6WDYIQPG6UXPPY3N4VHC75 refused: value: success: false errorReason: invalid_exact_stellar_payload_accepted_mismatch errorMessage: >- The payload's accepted requirements differ from the payment requirements. transaction: '' network: stellar:testnet '400': description: The body is not JSON or lacks a required field (`invalid_payload`). content: application/json: schema: $ref: '#/components/schemas/SettleTransportError' '401': description: >- The network requires an API key and none, or an unknown one, was sent (`unauthorized`). content: application/json: schema: $ref: '#/components/schemas/SettleTransportError' '413': description: The body exceeds `BODY_LIMIT_BYTES` (`payload_too_large`). content: application/json: schema: $ref: '#/components/schemas/SettleTransportError' '415': description: >- The request is not `Content-Type: application/json` (`unsupported_media_type`). content: application/json: schema: $ref: '#/components/schemas/SettleTransportError' example: success: false errorReason: unsupported_media_type errorMessage: >- The request body must be JSON (Content-Type: application/json). transaction: '' network: '' error: code: unsupported_media_type reason: >- The request body must be JSON (Content-Type: application/json). retryable: false '429': description: Rate limited (`rate_limited`). headers: Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/SettleTransportError' '500': description: An unexpected error (`unexpected_settle_error`). content: application/json: schema: $ref: '#/components/schemas/SettleResponse' security: - {} - bearerKey: [] - headerKey: [] components: requestBodies: FacilitatorRequest: required: true content: application/json: schema: $ref: '#/components/schemas/FacilitatorRequest' headers: ExtensionResponses: description: > Base64-encoded JSON keyed by extension name, present when the payment carries a `bazaar` extension: `{"bazaar": CatalogOutcome}`. schema: type: string RetryAfter: description: Seconds until a retry can succeed. schema: type: integer schemas: SettleResponse: type: object required: - success - transaction - network properties: success: type: boolean errorReason: type: string description: A stable code; present when `success` is false. errorMessage: type: string description: A non-empty human-readable reason; present when `success` is false. payer: type: string transaction: type: string description: The settlement transaction hash; empty when nothing was broadcast. network: type: string SettleTransportError: description: >- A transport-level rejection of `/settle`, in the x402 shape plus the `error` object. allOf: - $ref: '#/components/schemas/SettleResponse' - $ref: '#/components/schemas/ErrorBody' FacilitatorRequest: type: object required: - x402Version - paymentPayload - paymentRequirements properties: x402Version: type: integer examples: - 2 paymentPayload: $ref: '#/components/schemas/PaymentPayload' paymentRequirements: $ref: '#/components/schemas/PaymentRequirements' ErrorBody: type: object required: - error properties: error: type: object required: - code - reason - retryable properties: code: type: string reason: type: string retryable: type: boolean details: type: object additionalProperties: true PaymentPayload: type: object description: >- An x402 version 2 payment payload. For `exact` on Stellar, `payload` is `{ transaction }`. required: - x402Version - accepted - payload properties: x402Version: type: integer const: 2 accepted: $ref: '#/components/schemas/PaymentRequirements' payload: type: object properties: transaction: type: string description: >- A base64 transaction envelope with the payer's signed authorization entry. additionalProperties: true resource: type: object description: The paid resource; read for cataloging. additionalProperties: true extensions: type: object description: Extensions echoed from the seller's 402, such as `bazaar`. additionalProperties: true additionalProperties: true PaymentRequirements: type: object description: An x402 version 2 payment option. required: - scheme - network properties: scheme: type: string examples: - exact network: type: string examples: - stellar:testnet asset: type: string description: The SEP-41 token's contract address (`C…`). payTo: type: string description: The recipient, a `G…`, `C…` or `M…` address. amount: type: string description: The amount in the asset's base units. maxTimeoutSeconds: type: integer extra: type: object additionalProperties: true properties: areFeesSponsored: type: boolean additionalProperties: true securitySchemes: bearerKey: type: http scheme: bearer description: An API key whose SHA-256 digest is listed in `API_KEY_SHA256`. headerKey: type: apiKey in: header name: X-API-Key description: An API key whose SHA-256 digest is listed in `API_KEY_SHA256`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.