Skip to main content
Card sessions let an agent pay with a card without ever seeing the real card number (PAN), by checking out through a browser proxy. Each card session (csn_*) covers one purchase. The agent gets a stand-in card number and a proxy login, fills in the merchant’s checkout with the stand-in, and routes its browser through the proxy. When the checkout sends the card to one of the session’s allowed hosts, the proxy swaps in the real card on the way. Anywhere else, or after the session expires, the stand-in is useless. Card sessions are for agents: call them with an agent key. Creating and claiming a session also needs the X-Instance-ID header. Card sessions work with cards a user saved on the dashboard. Support for Natural-issued cards is coming soon.

​
Flow

  1. Find a card. GET /card-external-accounts lists the cards the user saved on the dashboard (eac_*), with brand and last four digits. The agent key needs the wallets.read scope.
  2. Open a session. POST /card-sessions with the cardId, the purchase (merchant name, amount, currency) and the allowedHosts that may receive the real card. For a saved card, the response includes an approvalUrl. Send it to the user: it’s returned only once.
  3. Wait for approval. The user opens the link, checks the purchase and approves it with the card’s security code. Poll GET /card-sessions/{sessionId} until status is approved. A declined or expired session is over: open a new one.
  4. Claim. POST /card-sessions/{sessionId}/claim returns the stand-in card, the cardholder name and billing address, and the proxy login. It succeeds once; the credential can’t be fetched again.
  5. Check out. Fill in the merchant’s checkout with the stand-in card and send the payment request to an allowed host through the proxy, trusting the proxy’s root certificate at caBundleUrl.

​
Allowed hosts

allowedHosts is required and has no default. Entries are exact hostnames, such as api.stripe.com. Wildcards, ports and paths aren’t accepted. Only requests to these hosts get the real card, so name the payment processor’s API host that receives the card, not the merchant’s website. The user sees the hosts on the approval page.

​
Limits

  • A session covers one purchase. For another purchase, open a new session.
  • The user must approve, and the agent must claim, before claimExpiresAt.
  • The stand-in card and proxy login stop working at the claim’s expiresAt (ttlSeconds, 600 by default, up to 900).
  • Checkouts that encrypt the card in the browser before sending it can’t be completed this way.