Payment Negotiation & Request Flow

Acceso’s x402 Micropayment Infrastructure enables usage-based, pay-per-request API access using HTTP 402 Payment Required. It targets automated consumers like agents, bots, and backend services.

Payment verification is integrated into the request lifecycle. Business logic stays decoupled from payment handling.

This describes how payment-aware requests are processed end-to-end.

For accounting and enforcement details, see Billing, Metering & Enforcement.

Design goals

• Keep request latency low.

• Make payment requirements machine-readable.

• Preserve verifiability without per-request on-chain blocking.

• Enforce at the gateway. Keep services clean.

When the gateway returns 402

When a client hits a protected endpoint without valid payment context, the gateway returns HTTP 402. The response includes a deterministic challenge describing the required payment.

Clients should rely on structured fields. Avoid parsing free-form strings.

Challenge model

• Required payment amount.

• Accepted payment method or facilitator.

• Request scope being accessed.

Challenge payload (recommended shape) This lets automated clients resolve payment requirements programmatically.

{
  "payment_required": true,
  "amount": "0.001",
  "currency": "USD",
  "scope": "endpoint:GET:/v1/...",
  "facilitator": {
    "type": "receipt-based",
    "id": "facilitator-1"
  },
  "challenge": {
    "nonce": "b64url(...)",
    "expires_at": "2025-12-18T12:34:56Z"
  }
}

Field expectations:

• amount + currency define the price.

• scope binds payment to what is being accessed.

• facilitator tells the client where to settle.

• challenge.nonce enables replay defense.

• challenge.expires_at limits challenge lifetime.

Challenges should be safe to cache until expires_at. Never include raw payment credentials in the challenge.

Request flow (happy path)

1

1) Client calls a paid endpoint

The request arrives without a valid receipt. The gateway determines the request scope.

2

2) Gateway returns a 402 challenge

The response includes amount, facilitator details, and scope. The client can now settle programmatically.

3

3) Client settles with the facilitator

The client pays through the configured facilitator. The facilitator returns a receipt (settlement proof).

4

4) Client retries with the receipt attached

The retry includes the same API key and the receipt. The gateway verifies before routing to internal services.

5

5) Gateway allows execution and records usage

Once verified, the request executes normally. Metering and audit signals are emitted.

Facilitator settlement model

Acceso uses facilitator-assisted settlement rather than direct on-chain execution per request. This avoids blocking API calls on chain confirmation times.

Settlement flow:

• Client initiates payment via facilitator.

• Payment proof or receipt is generated.

• Receipt is attached to a subsequent API request.

• Gateway verifies settlement before allowing execution.

Trust boundary:

• The facilitator issues receipts.

• The gateway verifies receipts.

• Internal services never handle payment proofs.

What the gateway verifies

Receipts are validated deterministically:

• Receipt signature matches facilitator keys.

• Receipt is unexpired (expires_at).

• Receipt scope matches the requested scope.

• Amount and currency match the challenge.

• API key binding is satisfied.

• Replay defense rules are satisfied (single-use or bounded reuse).

Once verified, access is granted for the specific request or a scoped time window. Validation happens at the gateway before request routing.

Receipt verification should be stateless for clients. A bounded replay cache can still be used for reuse prevention.

Common failure modes (client-visible)

• Missing receipt on retry.

• Expired challenge or expired receipt.

• Invalid signature or corrupted receipt.

• Scope mismatch.

• Receipt reuse when single-use is required.

Example: retry request with a receipt header

GET /v1/... HTTP/1.1
Host: <YOUR_ACCESO_API_HOST>
Authorization: Bearer <YOUR_API_KEY>
X-Payment-Receipt: <RECEIPT>