Skip to main content

​
Payment Flow

The facilitator enables seamless payment processing through a well-defined sequence of interactions 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 the payment requirements for the requested resource (network, token, amount, recipient).The facilitator enriches these requirements with the blockchain-specific details the client needs to construct a valid payment.
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 uses the enriched requirements to create a payment proof — a signed authorization that allows the facilitator to settle the payment on-chain.
5

Client Retries with Payment

The client retries the request with the payment proof attached.
6

Resource Server Calls /settle

The middleware calls the facilitator’s /settle endpoint with the client’s payment proof and the original requirements.The facilitator validates the proof and executes the on-chain transaction, sponsoring any required gas or transaction fees.
7

Facilitator Returns Transaction Hash

On success, the facilitator returns a transaction hash confirming the payment was settled on-chain.
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 + payment ->|                        |                        |
  |                           |                           |                        |
  |                           |--- POST /settle --------->|                        |
  |                           |                           |--- Submit tx --------->|
  |                           |                           |<-- Confirmation -------|
  |                           |<-- { success, txHash } ---|                        |
  |                           |                           |                        |
  |<----- Protected Resource -|                           |                        |
  |                           |                           |                        |

​
Key Interactions

​
Resource Server

The resource server makes two API calls to the facilitator:
  1. POST /accepts — Retrieves enriched payment requirements before returning 402 to the client
  2. POST /settle — Validates and executes payment after receiving the client’s payment proof
The resource server never needs to hold cryptocurrency, manage private keys, or interact with blockchain infrastructure directly.

​
Client

The client doesn’t communicate with the facilitator directly. It receives the enriched requirements through the 402 response and sends its payment proof through the retry request. The resource server acts as a relay between the two.

​
Facilitator

The facilitator handles all on-chain settlement: validating the payment proof, sponsoring transaction fees, and submitting the transaction to the blockchain. For protocol-level details on payment formats and signing, see the Faremeter protocol docs.