Overview

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:

1. GET /supported once at startup, to learn the fee-payer address and which (scheme, network) pairs you can charge on.
2. POST /verify when a buyer presents a payment, to check it's good before you do any work.
3. 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 PAYMENT-SIGNATURE header. You pass that header into a paymentPayload, then call /verify and /settle with the same(paymentPayload, paymentRequirements) pair.

Solana(blockchain)FacilitatorMerchantBuyerSolana(blockchain)FacilitatorMerchantBuyerAt startupPer paymentGET /supportedkinds + feePayer addressGET /protected-resource402 PAYMENT-REQUIRED + accepts[]Select paymentDetailsfrom accepts[]Create Payment PayloadSign transaction(facilitator set as fee-payer)GET /protected-resourcePAYMENT-SIGNATURE: paymentPayloadPOST /verify(paymentPayload, paymentRequirements)Screen buyer + merchantVerify paymentPayload againstpaymentRequirementsSimulate transactionokVerification ResponseisValid truePerform work to fulfill requestPOST /settle(same payload + requirements)Re-verify + deduplicate settlementsSubmit paymentco-sign as fee-payer + broadcastTransaction signatureWait for blockchain confirmationConfirmedsuccess: true with transaction hash200 OK + protected resourcePAYMENT-RESPONSE paymentResponse

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 CAIP-2 and use the table below:

Updated 25 days ago