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

# Get payment status

> Returns the current status of a payment. Use this endpoint to poll for the
terminal outcome of a payment that returned HTTP 202 (pending) from
settlement.

Status values are `pending`, `completed`, or `failed`. Poll at the
interval indicated by `retryAfterMs` on the initial pending response.




## OpenAPI

````yaml openapi/facilitator-service.yaml get /v1/facilitator/x402/status/{paymentId}
openapi: 3.0.3
info:
  title: Facilitator Service
  version: 1.0.0
  description: >
    Facilitator Service is Circle's hosted x402 facilitator. Sellers

    call Facilitator Service to verify and settle x402 payments in USDC on Arc,
    Base, and

    Polygon PoS without operating their own relayer, gas wallet, or sanctions

    screening.


    Facilitator Service implements the x402 v2 `exact` scheme and settles USDC
    through

    EIP-3009 authorizations.
servers:
  - url: https://api.circle.com
    description: Production
  - url: https://api-sandbox.circle.com
    description: Sandbox
security:
  - CircleApiKey: []
  - FacilitatorSellerProof: []
tags:
  - name: Payments
    description: |
      x402 payment verification, settlement, and status.
  - name: Seller accounts
    description: |
      Seller account binding to a Circle account for API key authentication.
  - name: Supported payment kinds
    description: |
      x402 payment kinds and extensions Facilitator Service accepts.
paths:
  /v1/facilitator/x402/status/{paymentId}:
    get:
      tags:
        - Payments
      summary: Get payment status
      description: >
        Returns the current status of a payment. Use this endpoint to poll for
        the

        terminal outcome of a payment that returned HTTP 202 (pending) from

        settlement.


        Status values are `pending`, `completed`, or `failed`. Poll at the

        interval indicated by `retryAfterMs` on the initial pending response.
      operationId: GetPaymentStatus
      parameters:
        - name: paymentId
          in: path
          required: true
          description: The `paymentId` returned by `/settle` on a pending response.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Payment status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          description: |
            Missing or invalid authentication. Returned when neither a valid
            Circle API key nor a valid seller proof is present, or when the
            seller proof's nonce has been replayed with a different digest.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            Payment not found or not visible to the caller. Unknown IDs and
            out-of-scope IDs return the same response to avoid enumeration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - CircleApiKey: []
        - FacilitatorSellerProof: []
components:
  schemas:
    StatusResponse:
      type: object
      required:
        - paymentId
        - status
        - network
      properties:
        paymentId:
          type: string
          format: uuid
          description: Facilitator Service payment identifier.
          example: 5b3f6c1e-9d2a-4f08-b1c7-2e9a14d0c3aa
        status:
          type: string
          enum:
            - pending
            - completed
            - failed
          description: Current lifecycle state of the payment.
        reason:
          type: string
          nullable: true
          enum:
            - outcome_unknown
          description: Additional detail about the payment status.
          example: outcome_unknown
        transaction:
          type: string
          nullable: true
          description: Transaction hash once available.
          example: 0x6f9e1d...
        network:
          type: string
          description: CAIP-2 network identifier for the payment.
          example: eip155:5042002
        amount:
          type: string
          description: Amount in atomic USDC units.
          example: '1000000'
        payer:
          type: string
          nullable: true
          description: Buyer address on the settled transfer.
          example: null
        nextAction:
          type: string
          nullable: true
          description: The next action.
          example: null
        retryAfterMs:
          type: integer
          nullable: true
          description: Milliseconds before retry.
          example: null
        expiresAt:
          type: string
          format: date-time
          nullable: true
          description: |
            Timestamp after which you can stop polling for a terminal state on
            this pending payment. Present only while `status` is `pending`.
        updatedAt:
          type: string
          format: date-time
          description: Timestamp of the most recent state transition.
          example: '2026-06-11T22:30:11Z'
    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          description: HTTP status code echoed in the body for programmatic handling.
          example: 403
        message:
          type: string
          description: >-
            Human-readable summary of the error, suitable for display to end
            users.
          example: Registration required to continue settling on this address
        errors:
          type: array
          description: Per-issue reason codes.
          items:
            type: object
            required:
              - reason
            properties:
              reason:
                type: string
                description: |
                  Machine-readable reason code.
                enum:
                  - registration_required
                  - authorization_expired
                  - payment_identifier_conflict
                  - credential_bound_elsewhere
                  - credential_payer_conflict
                example: registration_required
  securitySchemes:
    CircleApiKey:
      type: http
      scheme: bearer
      description: >
        Bearer token authentication with a Circle API key. Use this for

        production settlement after claiming your Facilitator Service seller
        account.
    FacilitatorSellerProof:
      type: apiKey
      in: header
      name: Facilitator-Seller-Proof
      description: |
        Base64url-encoded envelope carrying an EIP-712 signature that proves
        the caller controls the `payTo` address. Use this for the keyless
        trial before claiming your Facilitator Service seller account.

````