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 withGET /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
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
amountto0and say what your agent will do indescription, such asSave 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: truenow. It can’t be added once the session is open. See Claim and check out. returnUrlbrings the user back once they approve or decline. It’s added toapprovalUrlasreturnTo, so send that link unchanged. Use anhttpspage in your web app, which opens a moment after the user answers, orsms:and your number or short code (sms:+15551234567) to reopen your Messages thread, which shows a Back to button since Safari won’t opensms:without a tap. Anything else, includinghttpandsms:links with a body, returns400. Expired or already answered requests offer the same way back.
approvalUrl. Send it to the user. For a user who signed up by phone, add
?signin=phone first.
What the user sees
- 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.
- Check the purchase. “Your agent is asking to pay”, with the amount, merchant, your
description, card and the hosts that receive it. Withamount: 0, it reads “Your agent is asking to use your card” and leads with yourdescription. WithclaimWindowSecondsabove 600, it also says how long after approving your agent can use it. - 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 withclaimWindowSeconds(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.
Claim and check out
PollGET /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 oneSKILL.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:
.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
CallPOST /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: anhttpsURL, an app deep link, or ansms:link back to a chat.- Expiry. Invitations last 30 days unless you set
expiresAt(up to 90). The user must sign up before then.
2. Send the user the card link
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
- 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).
- 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. - Done. “Your card is saved”, then your
redirectUrlif you set one.
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
AddpasskeyApprovals=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.
Approval links for phone users
Add?signin=phone to every approvalUrl you send a user who signed up by phone:
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:- 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.
-
Add
env=sandboxto the card link. Save card asks for the code without texting it: enter000000. Use test card4111 1111 1111 1111with any future expiry. -
Approve purchases. Sandbox approval links already carry
env=sandbox. A signed-out user enters the invited phone and000000.
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.useand 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 agentsavedCards.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.