Payment validation

Your origin receives payment authorization in the PAYMENT-CONTEXT header. Validate this context before serving paid content.

The header contains a JSON Web Token (JWT). Validate it with a recommended JWT library.

Use only the pinned JSON Web Key Set (JWKS) ↗︎. Require Ed25519 signatures, and cache keys according to the endpoint's Cache-Control header.

Do not parse the token without verifying its signature. Reject requests when JWT validation fails.

Recommended libraries include:

Fixed pricing uses the x402 exact scheme. The following decoded example authorizes 25,000 atomic units for one audience:

{
	"iat": 1770000000,
	"nbf": 1770000000,
	"exp": 1770000120,
	"aud": "https://api.example.com/premium-data",
	"scheme": "exact",
	"amount": "25000"
}

Do not set PAYMENT-SETTLEMENT for fixed pricing. Monetization Gateway settles the signed amount.

Variable pricing uses the x402 upto scheme. The amount claim contains the authorized maximum.

The following decoded example authorizes up to 100,000 atomic units:

{
	"iat": 1770000000,
	"nbf": 1770000000,
	"exp": 1770000120,
	"aud": "https://api.example.com/generate",
	"scheme": "upto",
	"amount": "100000"
}

Calculate an actual amount where 0 <= actual <= authorized maximum. Express the amount in atomic units.

If the actual amount exceeds the authorized maximum, Monetization Gateway settles the authorized maximum instead. Nothing will be settled if the specified amount is zero.

Set PAYMENT-SETTLEMENT only for a successful upto response. Set it before sending response headers.

Use a JSON value containing the actual amount as a string. This standalone example reports 1,000,000 atomic units:

{ "amount": "1000000" }

Do not set PAYMENT-SETTLEMENT when the response status is 400 or greater. Do not create a PAYMENT-RESPONSE header.

Monetization Gateway creates the payment receipt after settlement. It removes PAYMENT-SETTLEMENT from the response sent to the buyer.