Issued cards are in early access and subject to change. To request access, contact hi@natural.com.
Check out with a virtual card
- Get the total. Go through the merchant’s checkout up to the payment step, so you know the total with shipping and tax.
- Create the card with
maximumAmountat that total. See Create a virtual card. - Read the card details. Call
POST /virtual-cards/{cardId}/reveal, then send oneGETfrom your shell, such as withcurl, to the link within two minutes. See Read the card details. - Pay. Enter the number, security code, and expiry, and use
nameOnCardandbillingAddressfor the checkout’s name and billing fields. Submit the order once. - Confirm. Call
GET /card-transactions?cardId={cardId}. A purchase that’sauthorized,partially_captured, orcapturedwent through. If you’re not sure the order was submitted, check this before submitting again.
What single-use cards are for
A single-use card is for one purchase that the agent completes now, such as a single online checkout. It’s not for subscriptions, recurring payments, or any charge the merchant makes again later. Once the first purchase is approved, the card declines every later charge, so:- A subscription, free trial, or membership that bills again on a schedule declines on its next charge.
- A merchant that adds to an approved amount later, such as a hotel or car rental that raises its hold, declines on the added charge.
- Storing the card with a merchant for future orders doesn’t work. Issue a new card for each purchase.
Before you start
- A funded wallet. The card spends from the wallet’s balance.
- The
cards.readpermission for the agent on that wallet. For your own agent, its agent key needscards.read. An agent connected over OAuth needs thecards:agentscope. To act for a connected customer, the customer’s grant to your agent must includecards.read(“Use cards”). Without it, requests return403withcard.readRequired. - An agent credential. Use an agent key or an agent-scoped OAuth grant. A party API key acts as the party, not as an agent, and can’t create virtual cards. Only a person signed in to the dashboard can create an agent key:
POST /agent-keyswith an API key returns403. The dashboard shows each key once.
Create a virtual card
SendPOST /virtual-cards with the agent’s credential. The request needs an Idempotency-Key and an X-Instance-ID header for the agent run. Retrying with the same Idempotency-Key returns the same card.
Every virtual card an agent creates is single-use: it approves one purchase, then it’s
used. Agents can read only single-use cards.
The response is 201 with the card (pcd_*). The card is usually active in the response. It can briefly be issuing. In that case, read it with GET /virtual-cards/{cardId} until it’s active. Only the agent the card was issued to can read it.
Set the maximum a little above the checkout total you expect, including tax and shipping, and keep the lifetime short.
Merchant categories
merchantCategories limits the card to a set of four-digit merchant category codes (MCCs), which the card network assigns to every merchant:
"mode": "allow": the card buys only at merchants incodes. For example,["4511", "3058"]limits it to merchants coded as airlines in general (4511) and to Delta, which has its own code (3058)."mode": "block": the card buys anywhere butcodes.
codes takes 1 to 500 codes. A purchase outside the rule declines with merchant_category_not_allowed_by_card. The categories blocked on every Natural card, such as gambling, stay blocked even if you allow them.
The API takes codes, not category names. To limit a card to a kind of merchant, send every code for that kind. Large airlines and car rental companies have their own codes, so a card for any airline needs 4511 and 3000-3299, not 4511 alone. These are the categories the dashboard’s Create card form offers, and the codes each one sends:
Every named merchant category code
Every named merchant category code
merchant.categoryCode, so you can check it after a purchase or a decline.
Card status
The card also returns its
name and controls, lastFour, expirationMonth, and expirationYear once it’s issued, plus closedBy and closedAt. closedAt is set when the card is used, expires, or is closed. The card never includes the full number or security code.
Read the card details
The agent needs the card number, security code, and expiry to check out. Natural hands these over through Evervault, so the number stays encrypted while it passes through Natural, and Natural doesn’t store or log it. The card must beactive.
It takes one API call and one plain GET, with no keys or decryption on your side:
- Call
POST /virtual-cards/{cardId}/revealwith the agent’s credential. The request needs no body. The response has arevealHandleand anexpiresAttwo minutes later. The handle is a one-time link to the card’s details. - From your shell or your own code, send one
GET /card-issuing/agent-card-revealto your Natural relay host, with the handle in theX-Card-Reveal-Handleheader.curlworks. Browser automation tools often can’t reach the relay host, so don’t use one for this step. The relay decrypts the number and security code on the way to you. - Keep the response: the handle works once. Enter the details into the checkout.
expiresAt. If it expired or was already used, the relay returns 404. Create a new reveal and try again. The card is still good, so you don’t need a new card. Send only GET: a HEAD returns 405, and a request without the header returns 400. A card that isn’t active returns 409. To act for a connected customer, pass customerPartyId in the query string, as on the other card routes.
The response from the relay has the same shape as GET /virtual-cards/{cardId}/details: number, cvv, expirationMonth, expirationYear, nameOnCard, and billingAddress. nameOnCard and billingAddress are for the checkout’s name and billing fields: the account owner’s, or for a business, its primary beneficial owner’s, as the bank holds them. You can also call GET /virtual-cards/{cardId}/details at the relay host directly. If you call it at the API host instead, number and cvv come back as Evervault ciphertext that starts with ev:.
In Sandbox, the relay host is the Sandbox API host, api.sandbox.natural.com, and every card returns the same test card, 4242 4242 4242 4242 with security code 123. For your production relay host, contact hi@natural.com.
The /agent-cards/{cardId}, /details, and /reveal routes keep working for integrations that already use them.
Read the card with your own key
If your runtime can generate keys and decrypt, it can instead read the card straight from Column, Natural’s card issuing bank, encrypted to a key only it holds. Generate a one-time P-256 key pair and send its RFC 7638 thumbprint indata.attributes.revealKeyThumbprint on the same POST /virtual-cards/{cardId}/reveal. The response is then Column’s single-use request: revealUrl, headers, revealKeyHeader, expiresAt, and encryption, plus nameOnCard and billingAddress. Send GET to revealUrl with headers as they are and your public key as JSON in the revealKeyHeader header. The reply is { "jwe": "..." }, a compact JWE encrypted to your key with ECDH-ES and A256GCM. Decrypt it with your private key to get pan, cvv2, and expiration_date. The request works once, for about a minute, and only with the key it was bound to. In Sandbox, revealUrl points at the Sandbox API host, which answers the same way with the test card.
Close a virtual card
Close a card you no longer need, for example when a customer cancels the order the card was for. SendPOST /virtual-cards/{cardId}/close. 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, passcustomerPartyIdas a query parameter. - Any Owner or Admin on the account that owns the card’s wallet.
200 with the card. A closed card is closed, with closedBy set to agent or owner and closedAt set. A card on another account’s wallet returns 404 with agentCard.notFound, and anyone else gets 403 with party.ownerOrAdminRequired.
A card that was already used, expired, or failed to issue comes back as it is, and nothing changes. A used card stays open with the card network until its lifetime ends, so the merchant can still settle its purchase. The card already declines any new purchase.
If the card network doesn’t confirm the close, the response is 503 with agentCard.closeUnconfirmed and retryable: true. The card is closed in Natural’s records by then, so new purchases on it already decline, and Natural keeps retrying the card network in the background. Send the same close again to get the confirmation.
If Natural couldn’t process the close at all, the response is 503 with agentCard.closeUnavailable or virtualCard.changeUnavailable, and retryable: true. The card may still be active, so send the close again until it returns 200.
POST /agent-cards/{cardId}/close keeps working for integrations that already use it, including a party API key or a person with payments.create on the card’s wallet.
Freeze a virtual card
Any Owner or Admin on the account can stop an agent’s card from approving purchases without closing it, and lift that later:POST /virtual-cards/{cardId}/freeze: purchases decline withcard_blockeduntil the card is unfrozen. The agent can’t lift a freeze.POST /virtual-cards/{cardId}/unfreeze: the card approves purchases again.
200 with the card. Freezing a frozen card, unfreezing one that isn’t frozen, or changing a closed card returns 409 with virtualCard.stateConflict. The agent and party API keys get 403 with party.ownerOrAdminRequired.
Over MCP
The Natural MCP server has the same card tools for accounts with virtual cards:create_agent_cardtakes the same fields asPOST /agent-cards, exceptmaximumAmountis a decimal amount in dollars, such as"25.00".get_agent_cardreturns the card’s status.get_agent_card_detailsreturns a one-time reveal link: a URL on your relay host, the header name, the handle, when it expires, and acurlcommand for it. Run the command once from your shell. The response has the number, security code, expiry, and billing name and address, and you can use them directly in the checkout.close_agent_cardcloses a card, the same asPOST /agent-cards/{cardId}/close. It returnsclosedoralready_closed. On a retryable error, call it again.list_card_transactionsandget_card_transactionreturn the card’s purchases and refunds. Filterlist_card_transactionsbycardIdto check whether a checkout went through.
Purchases
When the merchant authorizes a purchase, Natural approves it if all of these are true:- The card is
activeand hasn’t expired. - The amount is at or under the card’s maximum.
- The purchase is within the spending limits.
- The purchase is online, not in person.
- The purchase is in US dollars.
- The merchant isn’t in a blocked category, and the purchase isn’t cash or a cash-like transaction. See Declines.
- The wallet is active and has the funds.
used. When the merchant settles the purchase, the held money is taken. If the merchant settles for less, or cancels, the rest of the hold is released. A refund from the merchant goes back to the wallet when it settles.
Natural closes a card when its lifetime ends, or when you close it first. A used card stays open with the card network until its lifetime ends, so the merchant can settle the purchase.
Spending limits
Single-use cards follow the same program spending limits as every Natural virtual card. They depend on who owns the wallet:
The daily limit covers every card purchase on the wallet, from personal cards and single-use cards together. A day runs from 00:00 to 24:00 UTC, so the daily total resets at 00:00 UTC. Approved and settled purchases count toward it. A released hold, a declined purchase, and a refund don’t. A purchase that brings a total to exactly the limit is approved.
These limits can change. Natural gives notice before it changes them.
A single-use card’s maximum applies within these limits. For example, on a wallet a person owns, a card with a $5,000 maximum still declines a $4,000 purchase, because it’s over the $3,000 per-purchase limit.
Virtual cards are for online purchases. In-person use isn’t available yet, so an in-person purchase declines with
card_present_without_wallet_token.
Declines
A declined purchase moves no money. The merchant sees a generic decline, except for insufficient funds. You see the reason in the card transaction’sdecline object, as a code and a message.
These merchant category codes (MCCs) are blocked on every Natural virtual card:
- Gambling: 7800, 7801, 7802, 7995
- Cash, ATM, quasi-cash, and money transfer: 4829, 6010, 6011, 6050, 6051, 6540
card_declined.
What to do next depends on the reason. For an expired or used card, issue a new card. For an amount over the maximum, issue a new card with a higher maximum. For insufficient funds, fund the wallet first. For a purchase over the daily limit, wait until the total resets at 00:00 UTC. A purchase over the per-purchase limit declines again at the same amount on any card on that wallet. A blocked category, a cash purchase, or a non-USD purchase declines again on any Natural virtual card.
Track activity
Each purchase or refund is a card transaction (cit_*). GET /card-transactions lists them newest first, and an agent sees only transactions on its own cards. Filter by walletId, cardId, agentId, status, createdAfter, and createdBefore. Each card transaction has its merchant, its amounts at each stage, its decline reason, who used the card, and a timeline of events. It links to the matching wallet transaction in GET /transactions.
Card transaction webhooks
Natural sends a webhook event when a card transaction changes. Each event’sdata.object is the card transaction exactly as GET /card-transactions/{cardTransactionId} returns it at that moment. Card numbers are never in an event. Events are signed like every other Natural webhook. See Receive events to register a webhook and verify signatures.
Each fact is sent once. A purchase sends
authorized, declined, or reversed at most once. It sends captured each time the settled total grows, so a purchase the merchant settles in two parts sends two captured events, and amounts.captured in each one is the running total. A refund sends refunded each time its settled total grows. A refund the merchant approved but hasn’t settled sends nothing until it settles.
Some changes don’t send an event. A merchant can raise a hold after it’s approved, or release part of a hold. Those change amounts, and you see them in the next event or in GET /card-transactions/{cardTransactionId}. A refund doesn’t send an event on its purchase. Its own refunded event links the purchase.
Natural records each change once, even when the card network reports it more than once. Events can arrive out of order, and an event you already handled can be delivered again, so key your handling on the event id. When events reach Natural out of order, a stage can be skipped. For example, you can get captured without authorized. Read the card transaction for its latest state.
The events go to the webhooks of the party that owns the card’s wallet. The dashboard’s event picker doesn’t list them while virtual cards are in early access. To subscribe, create or update a webhook with the event names in enabledEvents, or use "*".
cardTransaction.captured
Connected customers
A platform can follow a connected customer’s card activity with its party API key. PasscustomerPartyId to GET /card-transactions. The customer’s grant to your platform must include payments.read on the card’s wallet, and you see every card transaction on the wallets it covers. Without it, requests return 403 with payment.readRequired. When Natural sends card transaction webhooks, webhooks whose sources include "connected" receive the customer’s cardTransaction.* events under the same rule.
An agent acting for a connected customer still sees only transactions on its own cards.
Errors
A maximum over $10,000 or a lifetime outside 5 to 1,440 minutes returns
422, with one error for each invalid field. See Virtual cards errors for the full list.