Payment validation

Last updated Sep 30, 2026 Your origin receives payment authorization in the PAYMENT-CONTEXT header. Validate this context before serving paid content.

Validate the context

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:

Caution

If PAYMENT-CONTEXT is absent, treat the request as unpaid and unverified. Do not serve paid content or set PAYMENT-SETTLEMENT.

Read fixed claims

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.

Read variable claims

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.

Report variable settlement

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.

Was this helpful?

YesNo

On this page

Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/monetization-gateway/configuration/payment-validation/#page","headline":"Payment validation","description":"Verify paid requests and report variable settlements.","url":"https://developers.cloudflare.com/monetization-gateway/configuration/payment-validation/","inLanguage":"en","image":"https://developers.cloudflare.com/monetization-gateway/configuration/payment-validation/og.png?v=d0d090985e3607f0","dateModified":"2026-09-30","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Set prices and control which requests require payment. title: Monetization rules image: https://developers.cloudflare.com/monetization-gateway/configuration/rules/og.png?v=ce80fde58746724b

Skip to content

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/monetization-gateway/llms.txt
Use this file to discover all available pages before exploring further.