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

> ## Agent Instructions
> Rail402 is an x402 payment facilitator, Stellar-native Bazaar discovery layer, and agent tooling for the Stellar network. It currently targets stellar:testnet.
> The live testnet facilitator is https://facilitator.rail402.dev with endpoints /verify, /settle, /supported, /health, and /discovery/*.
> Payment amounts use 7-decimal SEP-41 integer (stroop) arithmetic. Never use floating-point math for amounts.
> Every rejection returns a machine-readable error code and a non-null human-readable reason. When explaining a failure, surface both.

# Verify a payment authorization

> Checks that a payment authorization is valid without submitting it. The stock
`@x402/stellar` client builds the `paymentPayload`; you do not assemble it by hand.




## OpenAPI

````yaml /api-reference/facilitator.openapi.yaml post /verify
openapi: 3.1.0
info:
  title: Rail402 Facilitator API
  version: '2.0'
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  description: >
    The Rail402 x402 facilitator and Bazaar discovery layer on
    `stellar:testnet`.

    Verify and settle x402 payments, read what the facilitator supports, and
    browse or

    search the discovery catalog. Speaks the x402 v2 wire format, so a stock
    `@x402` client

    interoperates with no Rail402-specific code.


    Amounts are integer strings in atomic units at 7 decimals: one USDC is
    `10000000`, so

    `500000` is 0.05 USDC. Every rejection carries a machine `code`, a non-null
    `reason`, and a

    `retryable` flag.
servers:
  - url: https://facilitator.rail402.dev
    description: stellar:testnet
security: []
tags:
  - name: Payments
    description: Verify and settle payments
  - name: Discovery
    description: Browse and search the Bazaar catalog
  - name: Info
    description: Capabilities, health, and metrics
paths:
  /verify:
    post:
      tags:
        - Payments
      summary: Verify a payment authorization
      description: >
        Checks that a payment authorization is valid without submitting it. The
        stock

        `@x402/stellar` client builds the `paymentPayload`; you do not assemble
        it by hand.
      operationId: verifyPayment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FacilitatorRequest'
      responses:
        '200':
          description: >
            The verification result. On a scheme rejection, `isValid` is `false`
            and the machine

            code is in `invalidReason` with the human reason in
            `invalidMessage`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyResponse'
              examples:
                valid:
                  value:
                    isValid: true
                    payer: GBOXS4J3...
                rejected:
                  value:
                    isValid: false
                    invalidReason: invalid_exact_stellar_payload_wrong_amount
                    invalidMessage: >-
                      The transfer amount does not exactly match the amount in
                      the payment requirements.
        '400':
          description: >-
            The request never reached the scheme (malformed body, unknown
            network or scheme).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/X402Error'
components:
  schemas:
    FacilitatorRequest:
      type: object
      required:
        - paymentPayload
        - paymentRequirements
      properties:
        x402Version:
          type: integer
          example: 2
        paymentPayload:
          $ref: '#/components/schemas/PaymentPayload'
        paymentRequirements:
          $ref: '#/components/schemas/PaymentRequirements'
    VerifyResponse:
      type: object
      properties:
        isValid:
          type: boolean
        invalidReason:
          type: string
          description: Machine code, present when isValid is false
        invalidMessage:
          type: string
          description: Human reason, present when isValid is false
        payer:
          type: string
    X402Error:
      type: object
      required:
        - code
        - reason
        - retryable
      properties:
        code:
          type: string
          example: invalid_network
        reason:
          type: string
        retryable:
          type: boolean
        details:
          type: object
          additionalProperties: true
    PaymentPayload:
      type: object
      description: >-
        The buyer-signed payload. For exact/stellar, `payload.transaction` is a
        base64 Stellar transaction XDR.
      properties:
        x402Version:
          type: integer
          example: 2
        accepted:
          $ref: '#/components/schemas/PaymentRequirements'
        payload:
          type: object
          properties:
            transaction:
              type: string
              description: base64 Stellar transaction XDR
        extensions:
          type: object
          additionalProperties: true
    PaymentRequirements:
      type: object
      properties:
        scheme:
          type: string
          example: exact
        network:
          type: string
          example: stellar:testnet
        asset:
          type: string
          example: CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA
        amount:
          type: string
          description: Atomic units, integer string
          example: '500000'
        payTo:
          type: string
          example: GBOQSB3F...QR2
        maxTimeoutSeconds:
          type: integer
          example: 60
        extra:
          type: object
          additionalProperties: true

````