Billing, Metering & Enforcement

This covers how paid requests are metered and how unpaid requests are blocked.

For the 402 challenge and receipt flow, see Payment Negotiation & Request Flow.

Usage metering

Every paid request is metered at the infrastructure layer. Metering captures enough context to reconcile usage without involving business services.

Metering should be idempotent. Use a stable dedupe key such as request_id.

Metering event model (what gets recorded)

{
  "event": "x402.request_metered",
  "request_id": "req_...",
  "api_key_id": "key_...",
  "scope": "endpoint:GET:/v1/...",
  "payment_reference": "rcpt_...",
  "amount": "0.001",
  "currency": "USD",
  "timestamp": "2025-12-18T12:34:56Z",
  "result": "accepted"
}

Field expectations:

• request_id (or trace_id) for correlation and dedupe.

• api_key_id for identity binding.

• scope for product mapping and enforcement.

• payment_reference to link requests to receipts.

• amount + currency as charged.

• timestamp (and optionally region) for reporting.

• result to encode charge semantics (e.g., accepted, rejected).

Enforcement boundary (what payment blocks)

Payment enforcement runs at the gateway after authentication. It happens before routing to internal services.

Unpaid requests should be blocked before:

• Internal service routing.

• Upstream calls to vendors and RPCs.

• Derived analytics and enrichment work.

Enforcement mechanics (how it behaves)

Enforcement is a gate, not a side-effect. The gateway decides “allow” before any downstream work.

• Unpaid calls do not consume internal capacity budgets.

• Paid calls proceed to standard routing and policy evaluation.

• Retries remain safe when idempotency is respected.

Auditability and reconciliation

Payment events are logged with cryptographic references to settlement artifacts. This supports audits and dispute workflows without exposing raw payment payloads.

Store:

• Receipt identifiers, not raw receipt bodies.

• Content hashes of settlement artifacts.

• Signature metadata needed for later verification.

• Minimal PII. Prefer irreversible identifiers.

Reconciliation expectations:

• At-least-once event emission with dedupe.

• Deterministic matching of requests to receipts.

• Forensic traceability from request to settlement proof.