💡
Try the live demo!

This overview is written for the merchant — the resource server (seller) that integrates the facilitator into its paywall. You never sign the buyer's transfer or interact with the blockchain; the facilitator does the on-chain work. Your job is three calls:

GET /supported once at startup, to learn the fee-payer address and which (scheme, network) pairs you can charge on.
POST /verify when a buyer presents a payment, to check it's good before you do any work.
POST /settle to broadcast the payment on-chain and get a transaction signature back.

A buyer hits your protected resource, you reply 402 Payment Required with your paymentRequirements, the buyer signs a transfer and sends it back in an X-PAYMENT header. You pass that header into a paymentPayload, then call /verify and /settle with the same (paymentPayload, paymentRequirements) pair.

sequenceDiagram
    participant A as Client / Agent
    participant M as Merchant<br/>(resource server)
    participant F as Facilitator
    participant C as Solana<br/>(blockchain)

    Note over M,F: At startup
    M->>F: GET /supported
    F-->>M: kinds + feePayer address

    Note over A,C: Per payment
    A->>M: GET /protected-resource
    M-->>A: 402 Payment Required + paymentRequirements
    A->>A: Sign USDC transfer (facilitator set as fee-payer)
    A->>M: GET /protected-resource + X-PAYMENT header

    M->>F: POST /verify (paymentPayload, paymentRequirements)
    F->>F: Screen payer + payee, verify payment paymentPayload against paymentRequirements
    F->>C: Simulate transaction
    C-->>F: ok
    F-->>M: { isValid: true }

    M->>F: POST /settle (same payload + requirements)
		F->>F: Re-verify + deduplicate settlements
    F->>C: Co-sign as fee-payer + broadcast
    C-->>F: Transaction signature
    F-->>M: { success: true, transaction }

    M-->>A: 200 OK + protected resource

Conventions for all three endpoints:

Send Content-Type: application/json on the two POSTs.
A protocol-level rejection (bad payment, sanctioned address, duplicate) is HTTP 200 with { "isValid": false, ... } or { "success": false, ... }. Only a structurally malformed request body is HTTP 400. Don't treat a 200 as success — read the body.
Pass an x-request-id header to correlate logs; if you omit it the facilitator generates one and echoes it back on the response.

For background on the solana:… network identifier and the fee-payer address, see Key concepts.