Pay with DNA

A 402 from a site on DNA means the page has a price and a person must approve it. The agent can't sign in or pay. It shows the person a link, waits for approval, then fetches the page. A whole-site approval mints a session, and later pages are charged against it; a one-page approval covers that page only.

A 402 can list two methods: d3-pay (this page) and x402. Use the first one you support.

The 402 response

Only a person's own browser, navigating, is redirected to payUrl. A recognised agent, or any request carrying a credential, gets the 402.

For some verified agents, DNA answers an unpaid request with a 302 to payUrl, or a 200 carrying the same JSON body without error. Handle a body with payUrl and handoff the same way whatever its status. A refused credential always gets the 402.

Headers

Body

{
  "error": "payment_required",
  "preferred": "d3-pay",
  "methods": ["d3-pay", "x402"],
  "priceUsd": "0.001",
  "payUrl": "https://pay.d3.com/pay?handoff=kQ7mP2vXr9LwZ4tB8nHcYs.aG9uZXN0bHktdGhpcy1pcy1qdXN0LWFuLWV4YW1wbGU",
  "handoff": {
    "token": "kQ7mP2vXr9LwZ4tB8nHcYs.aG9uZXN0bHktdGhpcy1pcy1qdXN0LWFuLWV4YW1wbGU",
    "fetchUrl": "https://example.com/premium?d3pay_handoff=kQ7mP2vXr9LwZ4tB8nHcYs.aG9uZXN0bHktdGhpcy1pcy1qdXN0LWFuLWV4YW1wbGU",
    "param": "d3pay_handoff",
    "status": "pending",
    "expiresAt": "2026-10-14T18:02:11.000Z",
    "retryAfterSeconds": 5
  },
  "how": "This response is meant for software. ..."
}

Handle the 402

1. Give the person payUrl to open in their own browser. They haven't seen the site's response. Don't sign in or pay for them, and don't fetch payUrl as the page.
2. Re-fetch handoff.fetchUrl every retryAfterSeconds, or re-send the page with Payment-Authorization: Payment <handoff.token>. Until the person approves, it returns 402 handoff_pending with the same handoff.
   • Don't retry the bare page. That mints a new handoff, and the person is asked twice.
3. The first response from fetchUrl that isn't a 402 is the page. Read its headers before fetching anything else on the site; they carry the session.

To get these steps as JSON, either:

• GET <payUrl> with Accept: application/json and no text/html.
• GET https://pay.d3.com/pay/instructions?handoff=<token>.

The JSON fields are state, site, page, priceUsd, approveBy, approvalUrl, fetchUrl, scope, instructions (one string), and steps (the same text as a list). state is ready, approved, taken, expired, invalid, or unavailable.

Use the session

The page returned from fetchUrl sets a cookie for the site and carries a receipt.

Send the cookie on later requests to the site. If your client doesn't keep cookies, send the session token from the receipt:

Payment-Authorization: Payment <session>

• A session token is 43 base64url characters. The header value is capped at 128.
• One session covers one site. Each page is charged at its own price.
• Every fetch of fetchUrl after the first is another paid request. Fetch it once, then use the cookie.
• With more than one credential, the order is: handoff in the URL, then Payment-Authorization, then the cookie. A stale cookie never overrides a new approval.
• On a paid response, the site's Cache-Control is narrowed to private. A read answered from your client's cache isn't charged, and the receipt never enters a shared cache.

Scope

The person chooses the scope when approving.

With a single-request grant:

• A retry after a lost response serves the page again without a second charge.
• Any other page on the site returns wrong_page. A new 402 for that page asks the person again.

Errors

• Every 402 carries a new handoff, except handoff_pending, which echoes the one you sent.
• Unknown and expired handoffs also return handoff_pending, so the response never reveals whether a handoff exists.
• A request carrying a credential never fails open. A 502 is a refusal.