docs(x402): state the settle success criterion per billing model

[r-marques]

The problem, in plain terms

On a pay-as-you-go plan, a settle that charged the buyer $1.00 comes back like this:

{ "success": true, "network": "stripe", "billingModel": "pay-as-you-go",
  "creditsRedeemed": "0", "remainingBalance": "0",
  "orderTx": "pi_3U6tgrBYvSRKcV421ehH4bnX" }

Those plans hold no credit balance — each settle is one direct charge, referenced by orderTx (fiat rails) or transaction (crypto rails). So the success check a credits integration already has, success === true && creditsRedeemed > 0, is unreachable there: it reports a real charge as a decline. On a card rail that invites a retry of a payment that already went through, and repeated attempts feed issuer fraud scoring.

Several pages here published exactly that wrong check. The payments skill's SKILL.md said:

Proof of purchase = success: true with creditsRedeemed > 0 and a remainingBalance

and references/autonomous-operations.md and references/client-integration.md said the same. Those files are shipped to AI coding assistants through four distribution routes, so the wrong criterion was being handed to agents writing integrations.

What changed

The API shape did not change — billingModel has always been on the response. Every affected page now states the criterion per billing model:

billingModel	Success criterion	Credit fields
credits	success === true and creditsRedeemed > 0	creditsRedeemed is the amount burned, remainingBalance what is left
pay-as-you-go	success === true and a non-empty orderTx (fiat) / transaction (crypto)	always the string "0" — no balance exists on this plan shape

...plus the type trap, called out explicitly: the values are strings, so "0" is truthy while Number("0") > 0 is false.

Pages touched:

• Skill — skills/nevermined-payments/SKILL.md and its autonomous-operations, client-integration and mcp-paywall references.
• IDE rule files — the five that list the settle response fields (AGENTS.md, .cursor, .windsurf, .clinerules, .github/copilot-instructions.md). .amazonq does not list them and was left alone. The Windsurf payments file is 3,938 of its 6,000-character cap after the edit (its router sibling is untouched at 5,984).
• Specs — specs/x402-card-delegation.mdx and specs/x402-smart-accounts.mdx: receipt-format tables plus a new "Was the buyer charged?" subsection each, and a pay-as-you-go PAYMENT-RESPONSE example alongside the credits one.
• Guides — products/x402-facilitator/how-it-works.mdx, agents-guide/check-credits.mdx, solutions/api-providers.mdx, integrate/patterns/charge-credits.mdx (a scoping note: those patterns assume a credits plan), development-guide/nevermined-x402.mdx (pass billingModel through the receipt the agent builds).

integrations/youdotcom.mdx already carried the correct guidance — no change needed there.

One thing beyond the strict brief

api-reference/openapi.json is hand-maintained, and its SettlePermissionResponse schema did not match the endpoint at all: it named permissionHash, creditsSettled, remainingCredits and txHash — three of which the API does not return — and typed the credit fields as integers rather than strings. This is the published interactive API reference and clients are generated from it, so an integrator looking up "what does settle return" got a wholly fictional answer. It now describes the real response (success, errorReason, payer, transaction, network, billingModel, creditsRedeemed, remainingBalance, orderTx), with the criterion on the schema description. Edited as text, not round-tripped through a JSON serializer.

Flagging separately, and not fixed here: the neighbouring x402 schemas look similarly stale (/x402/permissions is documented as returning permissionHash / maxCredits, where the real endpoint returns accessToken). That is a bigger, separate cleanup.

Drive-by fix, folded in

All six occurrences of settlement.txHash / settlement.tx_hash in this repo are fixed. That field exists on neither SDK's settle result — both return transaction — so every one of these examples logged undefined (or raised AttributeError) when copied as written.

File	What it was
development-guide/nevermined-x402.mdx	receipt construction, TS + Python
products/x402-facilitator/how-it-works.mdx	receipt construction, TS + Python
integrate/add-to-your-agent/express.mdx	onAfterSettle hook
skills/nevermined-payments/references/express-integration.md	onAfterSettle hook

The two Express ones are hook callbacks, so the object is whatever the middleware passes rather than a direct settle return — checked, not assumed. Both rails are safe: the x402 branch passes the resolved value of settlePermissions (a SettlePermissionsResult), and the MPP branch passes MppSettleResult, which extends it. transaction exists on both; txHash appears nowhere in the SDK's x402 or MPP surface.

Only the value changes. transactionHash stays as the integrator's own key name in the receipt they build — renaming that would change what their buyers parse, which is a different call from fixing a field access.

The express skill reference is the one that made this worth folding in rather than deferring: it ships to AI coding assistants over the same four routes as the skill itself, so leaving it would keep handing agent builders a field that does not exist.

Verification

• mintlify broken-links — no broken links.
• ⚠️ Note for the reviewer: broken-links does not validate in-page anchors — I mutation-tested it with a deliberately bogus #definitely-not-a-real-anchor-xyz and it still reported success. The one new intra-page anchor (#66-was-the-buyer-charged, into ### 6.6 Was the buyer charged?) was therefore verified separately against github-slugger, the slugifier Mintlify uses.
• No hand-edits to api-reference/typescript/** or api-reference/python/** — those are generated from the SDK repos, and the matching source changes are in feat(x402): surface billingModel so a pay-as-you-go settle can be read as paid payments#432 and feat(x402): surface billing_model so a pay-as-you-go settle can be read as paid payments-py#272.

Refs nevermined-io/nvm-monorepo#2999

🤖 Generated with Claude Code

https://claude.ai/code/session_01CVpimo1dBXnTJo9tQSy8SA

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
Nevermined	🟢 Ready	View Preview	Sep 8, 2026, 1:33 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[aaitor]

No description provided.