Skip to main content
A delegation is what lets an agent spend on your behalf without asking every time: a payment method plus a hard spending limit and an expiry. This flow enrolls a card once (the human enters card details in a browser — PCI requires it) and hands the agent a delegationId it reuses until the budget is spent or the delegation expires.

​
Useful for

  • Giving an agent a card to pay with when a plan is fiat (Stripe / Braintree / Visa) rather than stablecoin.
  • Putting a hard cap on what an agent can spend (e.g. $50 over 30 days) — the platform enforces it.
  • Doing the human part once: after enrollment, every purchase is programmatic and reuses the same delegation.
Paying with stablecoins needs no card and no human enrollment — your account’s ERC‑4337 wallet is ready as soon as it’s funded. Use this flow only for card payments. See Buy access for the stablecoin path.

​
Try it yourself

Hand this to your agent. It drives the embedded enrollment handshake, gives you a single URL to open, and captures the result automatically: 
You are my autonomous payments agent. Set up a credit card I can use to pay for Nevermined services in the sandbox environment, with a spending limit of $50 over 30 days.

Use the **latest** Nevermined `nevermined-payments` skill — fetch the current `SKILL.md` and `references/` from https://github.com/nevermined-io/docs/tree/main/skills/nevermined-payments (don't rely on an older installed/cached copy). The card-enrollment endpoints (`POST /embed/session`, the `cards/setup` URL, `delegation/create`) are documented there even though `embed/session` is not in the API's OpenAPI.

Do the work yourself: mint an embedded session with my API key, host a one-shot callback server on 127.0.0.1, and hand me a single card-setup URL to open in my browser. The only thing I should have to do is enter my card. When I'm done, verify the `state` echo, store the `delegationId`, and show me my payment methods and the new delegation's remaining budget.
This points at Sandbox, so card entry uses test cards and no real money moves. Use a live: API key to run it for real.

​
How it works

1

Mint an embedded session

With your API key, mint a session bound to a localhost return URL — so run a tiny one-shot callback server on 127.0.0.1 first:
POST {API_BASE}/embed/session
Authorization: Bearer <api-key>
Content-Type: application/json

{ "returnUrl": "http://127.0.0.1:<port>/callback" }
The response carries a sessionToken. This open endpoint needs no organization — it’s the autonomous-agent path, and the card attaches to your own account. (Org members, e.g. the nvm CLI, can use the org-scoped POST {API_BASE}/widgets/session/self with { orgId, returnUrl } instead.)
2

Hand the human a card-setup URL

The human opens this once in their browser and enters the card:
https://embed.nevermined.app/cards/setup
  ?sessionToken=<sessionToken>
  &returnUrl=http://127.0.0.1:<port>/callback
  &state=<random-nonce>
  &provider=stripe
Generate state as an unguessable nonce. Use provider=stripe (or braintree / visa) to match the card type the target plan accepts.
3

Receive the delegation

When the human finishes, the browser redirects to your returnUrl with paymentMethodId and delegationId. Verify the returned state matches the one you sent (CSRF guard), then store the delegationId — that’s what you pass at purchase time.
paymentMethodId and delegationId arrive in the callback query string. Don’t log the request line, and keep secrets in a secret store, not on disk in the clear.
4

(Optional) Re-budget an enrolled card

Already enrolled and just need a fresh budget? Create another delegation directly — no browser needed:
POST {API_BASE}/delegation/create
Authorization: Bearer <api-key>
Content-Type: application/json

{ "provider": "stripe", "providerPaymentMethodId": "<pm_... from GET /payment-methods>",
  "spendingLimitCents": 5000, "durationSecs": 2592000, "currency": "usd" }
provider, currency, spendingLimitCents, and durationSecs are all required — there is no silent default for provider or currency. The response carries a new delegationId. The delegation is plan-agnostic unless you pass a planId.
Visa is the exception: provider: "visa" needs a browser-produced consumerPrompt + assuranceData from a WebAuthn ceremony, which an agent can’t generate — so create Visa delegations in the app and reuse the delegationId.
5

Reuse it to pay

Pass the stored delegationId whenever you buy — see Buy access. One delegation covers many purchases until its budget is spent or it expires.

Buy access

Use the delegation to buy plan credits with x402.

Card Delegation

The full embedded handshake, widget embedding, and state/CSRF rules.

Card Enrollment

Provider-specific enrollment (Stripe, Braintree, Visa).

Check credits

Inspect delegation budgets and remaining credits.