Skip to main content

​
Payment Flow

The facilitator enables seamless payment processing through a well-defined sequence of API calls between the client, resource server, and facilitator.
1

Client Requests Resource

A client makes a request to a protected API endpoint without a payment header.
2

Resource Server Calls /accepts

The resource server middleware calls the facilitator’s /accepts endpoint with partial payment requirements:
  • Scheme (e.g., exact)
  • Network (e.g., solana-devnet, base-sepolia)
  • Asset (token mint/contract address)
  • Amount, recipient, resource URL
The facilitator enriches these requirements with blockchain-specific details:
  • Solana: Fee payer address, token decimals, recent blockhash
  • EVM: EIP-712 domain parameters (name, version, chainId, verifyingContract)
3

Server Returns 402 Payment Required

The resource server returns a 402 status with the enriched payment requirements in the response body.
4

Client Prepares Payment

The client creates a payment proof based on the requirements:
  • Solana: Creates and partially signs a transaction that transfers tokens to the merchant
  • EVM: Signs an EIP-3009 authorization using EIP-712 typed data
5

Client Retries with Payment Header

The client retries the request with an X-PAYMENT header containing the base64-encoded payment payload.
6

Resource Server Calls /settle

The middleware calls the facilitator’s /settle endpoint with:
  • The payment header from the client
  • The original payment requirements
The facilitator validates and executes the payment:
  • Solana: Verifies the transaction, co-signs as fee payer, submits to blockchain
  • EVM: Verifies the authorization signature, calls the token contract, pays gas
7

Facilitator Returns Transaction Hash

On success, the facilitator returns:
  • success: true
  • txHash: The blockchain transaction hash
  • networkId: The network identifier
8

Resource Delivered

The resource server allows the request through and returns the protected resource to the client.

​
Sequence Diagram

Client                 Resource Server              Facilitator              Blockchain
  |                           |                           |                        |
  |------ GET /resource ----->|                           |                        |
  |                           |                           |                        |
  |                           |--- POST /accepts -------->|                        |
  |                           |<-- Enriched requirements -|                        |
  |                           |                           |                        |
  |<--- 402 Payment Required -|                           |                        |
  |                           |                           |                        |
  | (Client prepares payment) |                           |                        |
  |                           |                           |                        |
  |-- GET /resource + X-PAYMENT ->|                       |                        |
  |                           |                           |                        |
  |                           |--- POST /settle --------->|                        |
  |                           |                           |--- Submit tx --------->|
  |                           |                           |<-- Confirmation -------|
  |                           |<-- { success, txHash } ---|                        |
  |                           |                           |                        |
  |<----- Protected Resource -|                           |                        |
  |                           |                           |                        |

​
Key Interactions

​
Resource Server ↔ Facilitator

The resource server makes two API calls to the facilitator:
  1. POST /accepts - Retrieves enriched payment requirements before returning 402 to client
  2. POST /settle - Validates and executes payment after receiving client’s payment proof
The resource server never needs to:
  • Hold cryptocurrency or private keys
  • Understand blockchain transaction formats
  • Interact with blockchain RPC endpoints
  • Manage gas fees or transaction signing

​
Client ↔ Facilitator

The client doesn’t directly communicate with the facilitator. All interaction happens through:
  1. The 402 response body (containing enriched requirements from facilitator)
  2. The X-PAYMENT request header (containing payment proof for facilitator)
The resource server acts as a proxy, forwarding data between client and facilitator.

​
Facilitator ↔ Blockchain

The facilitator handles all transaction settlement with blockchain networks:
  • Solana: Co-signs transactions as fee payer and submits to Solana RPC
  • EVM: Calls transferWithAuthorization on token contracts and pays gas
Clients prepare signed payment proofs off-chain. Solana clients may optionally query blockchain RPC for current parameters (blockhash, token decimals) if not provided by the facilitator in the enriched requirements.