Payment Flow & Headers

The HTTP 402 challenge-response handshake specification

The Handshake Sequence

Client                                     Gateway                               Upstream
  |                                           |                                     |
  | 1. GET /api/v1/resource                   |                                     |
  |------------------------------------------>|                                     |
  |                                           |                                     |
  | 2. HTTP 402 Payment Required              |                                     |
  |    Header: PAYMENT-REQUIRED (Base64)      |                                     |
  |    Header: WWW-Authenticate: x402         |                                     |
  |<------------------------------------------|                                     |
  |                                           |                                     |
  | [Client signs Soroban auth entry]         |                                     |
  |                                           |                                     |
  | 3. GET /api/v1/resource                   |                                     |
  |    Header: Payment-Signature (Base64)     |                                     |
  |------------------------------------------>|                                     |
  |                                           | 4. Forward with req.x402Payment     |
  |                                           |------------------------------------>|
  |                                           |                                     |
  |                                           | 5. HTTP 200 OK (Response Payload)   |
  |                                           |<------------------------------------|
  | 6. HTTP 200 OK                            |                                     |
  |<------------------------------------------|                                     |

Step-by-Step Breakdown

Step 1: Initial Unauthenticated Request

The client attempts to access a protected route without a payment signature:

GET /api/v1/resource HTTP/1.1
Host: api.example.com

Step 2: HTTP 402 Challenge

The gateway intercepts the call and responds with HTTP 402, returning challenge parameters:

HTTP/1.1 402 Payment Required
Content-Type: application/json
PAYMENT-REQUIRED: eyJ2ZXJzaW9uIjoieDQwMi12MSIsIm5ldHdvcmsiOiJzdGVsbGFyOnRlc3RuZXQi...
WWW-Authenticate: x402 challenge="eyJ2ZXJzaW9uIjoieDQwMi12MSIs..."

{
  "error": "Payment Required",
  "message": "This endpoint requires an x402 payment settled on Stellar",
  "challenge": {
    "version": "x402-v1",
    "network": "stellar:testnet",
    "asset": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
    "price": "0.01",
    "recipient": "GCALKSGAZRJLSUEJT3M5W6LN4R7XQOLIRCOS6ZA6EDZVTZDBIIPPFKJ6",
    "validUntil": 1788269878
  }
}

Step 3: Payment Signature Generation

The client decodes the challenge, checks budget policies, and creates a Soroban cryptographic authorization entry signed by the client’s Stellar secret key.

Step 4: Authenticated Request

The client repeats the request with the Payment-Signature header:

GET /api/v1/resource HTTP/1.1
Host: api.example.com
Payment-Signature: eyJ2ZXJzaW9uIjoieDQwMi12MSIsIm5ldHdvcmsiOiJzdGVsbGFyOnRlc3RuZXQiLCJhdXRoRW50cnlYZHIi...

Step 5: Verification & Forwarding

The gateway decodes the signature, verifies that the network and recipient match, validates the expiration timestamp, attaches req.x402Payment, and forwards the request to the upstream API.