Issued cards are in early access and subject to change. To request access, contact hi@natural.com.
Before you start
You need:- Issued cards turned on for your account in Sandbox. Natural turns virtual cards on for each account. To request it, contact hi@natural.com. Turning them on in Sandbox doesn’t turn them on in production. Without it, card requests return
403withissuedCards.notEnabled. - A funded wallet. Link a test bank account and deposit into the wallet. Sandbox deposits complete immediately.
- An agent and its agent key. Only an agent can create virtual cards. A party API key acts as your account, not as an agent, so
POST /virtual-cardswith it returns403. cards.readfor the agent on the wallet. Without it, card requests return403withcard.readRequired.
Get an agent key
A person signed in to the dashboard creates agent keys. An API key can’t create one:POST /agent-keys with an API key returns 403. This keeps a leaked API key from minting new agent credentials.
- In the dashboard, switch to Sandbox and open Agents.
- Choose Add agent. The dashboard creates the agent and its key, and shows the key (
ak_ntl_sandbox_...) once. Save it then. - Repeat for each agent. If your code creates agents with
POST /agents, a person still creates each agent’s key from the dashboard.
POST /agents gets your default wallet unless you pass walletId. For your own agent, cards.read comes from the agent’s permissions on each of those wallets. If you remove cards.read from an agent on a wallet, Natural closes the agent’s open cards on that wallet. If the agent had cards.read on every wallet and you narrow it to some wallets, Natural closes all of the agent’s open cards, and the agent can request new ones on the wallets it kept.
Issue cards for a connected customer
A Connect platform can issue and track virtual cards for a connected customer, such as one customer per health plan.- Act through your connected agent. Pass the customer’s party ID as
customerPartyId. Your agent can then issue a card on the customer’s wallet, read its details, close it, and simulate purchases on it. The customer’s grant to your agent must includecards.read. An agent connected over OAuth needs thecards:agentscope. If it connected before virtual cards were turned on, reconnect it. - Issued cards follow your account. When your platform acts for a connected customer, Natural accepts your account’s issued-cards setting, so the customer’s account doesn’t need it turned on. The customer’s own agents and keys still follow the customer’s account. A test customer from Invite a test customer always follows your account.
- Read card transactions with
payments.read. Your party API key reads the customer’s card transactions withGET /card-transactions?customerPartyId=.... The customer’s grant to your platform must includepayments.readon the card’s wallet, and you see every card transaction on the wallets it covers. Without it, requests return403withpayment.readRequired. Your agent sees only the transactions on its own cards. The same rule decides which card transaction webhooks you receive. - Close, but no unfreeze. Your connected agent can close a card it issued for the customer. Unfreezing a card isn’t available when you act for a customer.
https://api.sandbox.natural.com with a sandbox key.
Issue a test card
Issue a card with the agent’s key.controls.maximumAmount is in cents and caps the card’s one purchase.
pcd_...). Use it once its status is active. A card expires after 60 minutes unless you set controls.expiresInMinutes (5 to 1440).
If the card can’t be issued, these errors come back:
See Virtual cards errors for the full list.
Read the test card
GET /virtual-cards/{cardId}/details returns the card’s details. Every Sandbox card returns the same test card, unencrypted:
Simulations use the card ID, not the number.
Close a test card
Close a card you no longer need withPOST /virtual-cards/{cardId}/close. It works the same in Sandbox as in production. The request has no body and doesn’t need an Idempotency-Key, because repeating it is safe.
- The agent the card was issued to, while it has
cards.readon the card’s wallet. To close a connected customer’s card, use the connected agent and passcustomerPartyIdas a query parameter. - Any Owner or Admin on the account that owns the card’s wallet. Anyone else gets
403withparty.ownerOrAdminRequired.
404 with agentCard.notFound.
The response is 200 with the card. A card closed before it was used is closed, with closedBy (agent or owner) and closedAt set, and it declines every purchase. A card that was already used, expired, or failed to issue comes back unchanged.
A 503 with agentCard.closeUnconfirmed, agentCard.closeUnavailable, or virtualCard.changeUnavailable has retryable: true. Send the same close again until it returns 200. An authorization you simulate on a closed card declines.
Owners and Admins can also freeze a card with POST /virtual-cards/{cardId}/freeze and lift it with POST /virtual-cards/{cardId}/unfreeze. An authorization you simulate on a frozen card declines with card_blocked.
Card status
Card controls
A single-use virtual card has these controls, and they work the same in Sandbox as in production:- Single use. The card approves one purchase. After that, it’s
usedand declines withcard_use_limit_reached. - Maximum amount.
controls.maximumAmountis set when you issue the card, from 1 cent to $10,000 (1000000). A purchase over it declines withpurchase_over_card_limit. - Lifetime.
controls.expiresInMinutesis 5 to 1440 (24 hours), and 60 if you leave it out. AfterexpiresAt, the card declines withcard_expired. - Merchant categories.
controls.merchantCategorieslimits the card to merchant category codes ("mode": "allow") or keeps it out of them ("mode": "block"). A purchase outside the rule declines withmerchant_category_not_allowed_by_card. Merchant categories lists the codes for each category, such as airlines or hotels. - Close and freeze. You can close a card before it’s used, and an Owner or Admin can freeze it.
purchase_over_program_limit even when it’s under the card’s maximum. A purchase that goes over the daily total declines with daily_spend_over_program_limit.
The card’s name is returned with the card but isn’t matched against the purchase. To limit where it works, set controls.merchantCategories. Country rules aren’t available.
Simulate a purchase
Authorize a purchase on the card:cit_...) with status authorized or declined. Amounts are in cents.
Then act on it with POST /simulations/card-transactions/{cardTransactionId}/{action}:
For
reverse and expire, send {"data": {"attributes": {}}}.
Rules:
- A purchase can be captured, reversed, or expired once. A capture can be up to the authorized amount.
- A refund needs a capture first. You can refund more than once, up to the captured amount.
- An action the purchase’s state doesn’t allow returns
409withcardPurchase.simulationNotAllowed.
GET /card-transactions/{cardTransactionId}.
Who can simulate
- The agent the card was issued to, while it has
cards.readon the wallet. - The wallet owner’s dashboard user or party API key with
payments.createon the wallet. This includes purchases on a person’s own card (see Personal cards).
customerPartyId in the request attributes.
Personal cards
A person on the wallet can also get their own card in Sandbox. In the dashboard, switch to Sandbox, open the wallet, and choose Create card.- Hovering the card number or CVV shows the Sandbox test card:
4242424242424242, CVV123, and the card’s own expiration. - Freezing and unfreezing the card work as in production.
- To simulate a purchase, choose Copy ID from the card’s menu to copy the card ID (
pcd_...). Then callPOST /simulations/agent-cards/{cardId}/authorizewith the wallet owner’s party API key, which needspayments.createon the wallet. The capture, reverse, expire, and refund actions above work the same way. - An agent can’t simulate purchases on a person’s card.
insufficient_funds, and a frozen card declines.
Declines
A declined authorization returns200 with status declined and a decline object. No money moves.
Card transaction webhooks
Natural sends a webhook event when a card transaction changes. Each event’sdata.object is the card transaction as GET /card-transactions/{cardTransactionId} returns it at that moment. Events go to the webhooks of the party that owns the card’s wallet. For a connected customer’s card, your webhook needs connected in sources, and the customer’s grant to your platform must include payments.read on the card’s wallet.
The dashboard’s event picker doesn’t list these events yet. To subscribe, create or update a webhook with the event names in enabledEvents, or use "*". See Receive events to register a webhook and verify signatures.
Simulations send the same events as real purchases, because they go through the same records:
A purchase sends each event once, and a refund doesn’t send an event on its purchase. Events can arrive out of order or more than once, so key your handling on the event
id and read the card transaction for its latest state.
To confirm an event was sent, list your events with GET /events and eventType, for example cardTransaction.captured. To see each delivery attempt to your URL, open the webhook in the dashboard under Developers.
Retries
- Every simulation needs an
Idempotency-Key. Retrying with the same key and body returns the first result without running the simulation again. See Idempotency. - Agents also send
X-Instance-ID. - A
503withretryable: truemeans the simulation was accepted but its result wasn’t ready yet. Retry with the same key.