Accept payments

The flow

• A client requests a paid resource with no payment.
• The server responds 402 Payment Required with one or more acceptable payment options.
• The client pays and retries with an X-PAYMENT proof.
• The server verifies + settles the payment, runs the handler, and returns a receipt.

1. The challenge

A 402 body carries an accepts array. Each entry is a fully-specified payment requirement — amount, asset, recipient, and the resource being bought:

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "stellar-testnet",
      "maxAmountRequired": "0.02",
      "payTo": "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
      "asset": { "code": "USDC", "issuer": "G..." },
      "resource": "/v1/ocr",
      "description": "Extract text from a document",
      "maxTimeoutSeconds": 60
    }
  ]
}

2. The payment

The client builds a signed Stellar payment for maxAmountRequired USDC to payTo, wraps it in the payment envelope, and base64-encodes it into the X-PAYMENT header. The exact scheme means it must pay exactly the amount required — no more, no less.

{
  "x402Version": 1,
  "scheme": "exact",
  "network": "stellar-testnet",
  "payload": { "transaction": "<signed XDR>" }
}

3. Verification & receipt

Tael checks that the proof's scheme and network match the challenge, then delegates to the verifier to settle on-chain. On success it runs your handler and attaches an X-PAYMENT-RESPONSE receipt to the response. A malformed or underpaid proof gets another 402 with an error message rather than reaching your code.

Verifiers

The verifier is the only chain-specific piece, and it's injected so your handler code stays portable:

• createMockVerifier() — accepts any well-formed proof. Use it in dev and tests.
• The Stellar verifier from @tael/stellar — submits and confirms the transaction on the network. Use it in production.

Ready to add this to an endpoint? See Wrap an API.