Skip to main content
Paying with an external card on Natural Natural stores a user’s existing debit or credit card, and your agent checks out with it at most merchants through a browser proxy that swaps in the real card. The user approves each purchase. Your agent never sees the card number, so it stays out of PCI scope. Most teams that use Natural as a card vault don’t want their users to verify their identity, so we built phone signup on top of it: the user enters one code we text them and adds their card. No email, no password, no identity check. If your agent also needs to hold or move money for the user, give them a full account instead. You need an API key to invite users and an agent key for card sessions, or the OAuth token of a partner app Natural has approved. Other apps connected through Natural OAuth, such as MCP clients, can’t use card sessions. Choosing between this and a Natural-issued card? See External and Natural-issued cards.
1

Connect the user

The user saves a card and connects your agent with savedCards.use, by phone or with a full account.
2

Open a card session for each purchase

Send the user the approval link. They check the purchase and approve it with the card’s security code or Face ID.
3

Claim and check out

Claim the session and pay through the proxy.

Pay with a saved card

These steps are the same however the user connected. To run them without reading these docs, give your agent the card vault skill.

Open a card session

Find the card with GET /external-cards?customerPartyId=pty_…, which returns the brand and last four digits, never the number (External cards). Then open a session with POST /card-sessions, using your agent’s key and an X-Instance-ID header.
cURL
The user approves merchantName, amount and description, but Natural doesn’t enforce them: it doesn’t cap the charge or lock the card to the merchant. It does enforce allowedHosts, the only hosts that get the real card. See what the user approves.
  • No purchase. To save the card on file at a merchant, or replace it on an account, set amount to 0 and say what your agent will do in description, such as Save this card on file at Amazon. The merchant keeps the real card number, and charges it makes later are outside Natural’s controls. See card actions with no purchase.
  • Encrypted checkouts. If you know the checkout encrypts the card in the browser, set requestAgentToken: true now. It can’t be added once the session is open. See Claim and check out.
  • returnUrl brings the user back once they approve or decline. It’s added to approvalUrl as returnTo, so send that link unchanged. Use an https page in your web app, which opens a moment after the user answers, or sms: and your number or short code (sms:+15551234567) to reopen your Messages thread, which shows a Back to button since Safari won’t open sms: without a tap. Anything else, including http and sms: links with a body, returns 400. Expired or already answered requests offer the same way back.
The response has an approvalUrl. Send it to the user. For a user who signed up by phone, add ?signin=phone first.

What the user sees

  1. Sign in, unless they saved their code with Face ID on this device. A user who signed up by phone gets a code by text and stays on the approval page.
  2. Check the purchase. “Your agent is asking to pay”, with the amount, merchant, your description, card and the hosts that receive it. With amount: 0, it reads “Your agent is asking to use your card” and leads with your description. With claimWindowSeconds above 600, it also says how long after approving your agent can use it.
  3. Approve with the card’s security code, or Decline. With a saved code, Approve with Face ID approves and fills in the code in one step; Use security code instead lets them type it. After approving with a typed code, a signed-in user without a saved code is offered to save it for next time. It’s optional, and the approval stands either way.

Deadlines

  • The user must approve within 24 hours of opening the session.
  • Your agent must claim before claimExpiresAt: 10 minutes after the user approves, or up to 24 hours with claimWindowSeconds (max 86400) to pay later.
  • The claimed card lasts ttlSeconds (600 by default, up to 900) and can’t be renewed under the same approval.
If any of these pass, open a new session and ask the user again. Approving needs Face ID with the user’s passkey or a Natural sign-in on their device, so open the session when the user is ready to approve, and claim right before your agent enters the card.

Claim and check out

Poll GET /card-sessions/{sessionId} until status is approved, then claim it for a stand-in card and a proxy login. Fill in the checkout with the stand-in and route the browser through the proxy, which swaps in the real card. See Browser tokens for the setup. If the checkout encrypts the card in the browser, the proxy can’t swap it. If you set requestAgentToken: true and the card supports it, pay with a tokenized card from the mandate the user approved (Agent tokens). Otherwise open a new session with requestAgentToken: true and ask the user to approve again. Most cards don’t support agent payments yet: if the card can’t, tell the user this checkout isn’t supported with this card.

Give your agent the skill

The card vault skill is one SKILL.md with these steps for your agent: the exact requests, responses and status values, plus what to do on each error, expiration and retry. It leaves out setup, so your agent needs its agent key and the user’s customerPartyId first. Install it with the skills CLI, which works with Claude Code, Codex, Cursor and other agents:
Or download it to wherever your agent loads skills from, such as Claude Code’s .claude/skills, or add it to your own agent’s system prompt. Install it again to pick up changes.

Sign users up by phone

Phone signup connects a user with one texted code and no identity check. After that, your agent pays with the same card sessions.

1. Invite the user by phone

Call POST /customers/invitations with a phone recipient and only the savedCards.use permission, which lets your agent list the user’s saved cards, open card sessions and check their status. The read-only party.read, payments.read and wallets.read are also allowed. Any other permission, or {"type":"ALL"}, needs a full account: the user can’t accept it with a phone code.
  • One agent per invitation. Each agent gets its own invitation (adi_*), and the link connects only that one.
  • redirectUrl (optional) sends the user back to you after they save the card: an https URL, an app deep link, or an sms: link back to a chat.
  • Expiry. Invitations last 30 days unless you set expiresAt (up to 90). The user must sign up before then.
Natural doesn’t send phone invitations. Send the user a link to /connect-card on the host of the invitation’s url, wherever you talk to them:
All are optional. Older links with ?signup=card on the invitation’s url still open this page. The invitation’s url alone starts a full signup with email and an identity check.

What the user sees

  1. Add their card. “Add a card for Acme”, with your app’s name. They enter the name on the card, number, expiry, billing address and a nickname, and tap Save card. Natural stores the number encrypted, and never the security code unless they lock it with Face ID (below).
  2. Enter the code. Save card texts a code to phone, and they enter it on the same page without entering the card again. A new account is named after the name on the card.
  3. Done. “Your card is saved”, then your redirectUrl if you set one.
If the number already has a Natural account, the code signs them in and the card is saved there. They can also choose Sign in another way to use Google or email, then come back and enter the card number again. The connection is live once the card is saved. You get the agentConnectionInvitation.accepted and connection.activated webhooks, and the user appears in GET /customers. Their id (pty_*) is the customerPartyId you pass from now on.

Let the user approve with a passkey

Add passkeyApprovals=true to the link so the user approves purchases with Face ID instead of typing the security code. When their device can use a passkey, the form also asks for the security code (otherwise it doesn’t, so a code is never collected without a way to save it) and says it’ll be saved with Face ID (Touch ID on a Mac, “a passkey” elsewhere). Save card opens the Face ID prompt, which creates a passkey for this card and locks the code with it. Natural stores only the locked code: only that passkey, on the user’s devices, can open it. If the user cancels, or their device or browser can’t do this, the card is still saved without the code and they type it when they approve. Some browsers need one more tap: an optional Finish saving card button after the card is saved. Natural checks the passkey for each purchase, so the user approves with Face ID alone, without signing in. It doesn’t sign them in to anything else. Add ?signin=phone to every approvalUrl you send a user who signed up by phone:
Always add ?signin=phone for a user who signed up by phone. Without it, a signed-out user is sent to a sign-in page that asks for email or Google, which a phone-only user doesn’t have.

What a phone-only user can do

A phone code sign-in lets the user manage saved cards, approve card purchases, and accept or remove card-only agent connections. Anything else, such as moving money or changing account details, asks them to sign in with email or Google, which they don’t have yet. They can’t use agent tokens: requestAgentToken has no effect, so pay through the proxy.

Saved security codes

  • The user can remove a saved code with Forget saved security code on the card in their Natural account. Removing the card removes it too.
  • A saved code stops working when the card expires. It’s also dropped when a payment through Natural’s card proxy is refused because the code is wrong (for example, a reissued card) and the processor says so, today only Adyen. The next approval asks for it again. Otherwise the user can forget it and type the new code.
  • It works only on devices with the user’s passkey. Passkeys synced through iCloud Keychain or Google Password Manager work on their other devices; anywhere else, they type the code.

Test in Sandbox

Run the whole flow with your Sandbox keys. Sandbox has no real people and texts no one:
  1. Invite any phone number. It creates a test customer for that number, yours alone: another developer’s invitation to the same number is a different customer. Inviting it again invites the same test customer.
  2. Add env=sandbox to the card link. Save card asks for the code without texting it: enter 000000. Use test card 4111 1111 1111 1111 with any future expiry.
  3. Approve purchases. Sandbox approval links already carry env=sandbox. A signed-out user enters the invited phone and 000000.
The link signs in as the test customer, not as you, even where you’re signed in to your dashboard. The test customer’s session lasts an hour, in that browser tab only.

Limits

  • No email recipients in Sandbox. Invite a phone, or create a test customer with POST /simulations/invite-customer.
  • No VoIP numbers. Use E.164 format, such as +14155550123. Natural blocks VoIP numbers, such as Google Voice, at signup; creating the invitation doesn’t check.
  • Card only. A phone-only user can’t accept an invitation that asks for more than savedCards.use and the read-only permissions above. If your agent later needs to move money, the user needs a full account.

Users with a full account

A user who signs up through a normal invitation gives their email, verifies their identity, and saves cards on the dashboard. Offer your agent savedCards.use in the invitation; they see it as Use saved cards when they approve the connection. Besides approving each purchase, they can approve a budget once with agent tokens and let your agent spend within it.