Skip to main content
Issued cards are in early access and subject to change. To request access, contact hi@natural.com.
A virtual card is a debit card that Natural issues for online purchases. An agent gets a single-use virtual card for one purchase. The agent asks for a card with a maximum amount and a lifetime. The card approves one purchase up to that maximum, before it expires, and then approves nothing else. Money comes from the funded balance of a wallet the agent can spend from. People on your account use personal cards instead. To try virtual cards end to end without real money, see Issued cards in Sandbox.

Check out with a virtual card

  1. Get the total. Go through the merchant’s checkout up to the payment step, so you know the total with shipping and tax.
  2. Create the card with maximumAmount at that total. See Create a virtual card.
  3. Read the card details. Call POST /virtual-cards/{cardId}/reveal, then send one GET from your shell, such as with curl, to the link within two minutes. See Read the card details.
  4. Pay. Enter the number, security code, and expiry, and use nameOnCard and billingAddress for the checkout’s name and billing fields. Submit the order once.
  5. Confirm. Call GET /card-transactions?cardId={cardId}. A purchase that’s authorized, partially_captured, or captured went through. If you’re not sure the order was submitted, check this before submitting again.
The card number only works for this one purchase, up to the card’s maximum, before the card expires. After that, it declines everything. You can show it in the agent’s chat, pass it between your tools, and type it into the checkout in a browser. Until that purchase, anyone with the number can spend up to the maximum, so don’t store it, and close the card if you abandon the checkout.

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.
A $0 card check that a merchant runs to verify the card doesn’t use up the card. Natural doesn’t approve part of a purchase: a purchase over the card’s maximum declines in full.

Before you start

  • A funded wallet. The card spends from the wallet’s balance.
  • The cards.read permission for the agent on that wallet. For your own agent, its agent key needs cards.read. An agent connected over OAuth needs the cards:agent scope. To act for a connected customer, the customer’s grant to your agent must include cards.read (“Use cards”). Without it, requests return 403 with card.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-keys with an API key returns 403. The dashboard shows each key once.
Virtual cards don’t use your agent limits or approvals. The card’s maximum, its expiry, and the program spending limits are what control it.

Create a virtual card

POST /agent-cards, the earlier agent cards API, is deprecated. It keeps working for integrations that already use it. Use POST /virtual-cards for new integrations. Cards from either route work with the /virtual-cards routes below.
Send POST /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 in codes. 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 but codes.
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:
To combine categories, send the codes of each one together, without repeats. A card transaction returns the code the merchant used in 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 be active. It takes one API call and one plain GET, with no keys or decryption on your side:
  1. Call POST /virtual-cards/{cardId}/reveal with the agent’s credential. The request needs no body. The response has a revealHandle and an expiresAt two minutes later. The handle is a one-time link to the card’s details.
  2. From your shell or your own code, send one GET /card-issuing/agent-card-reveal to your Natural relay host, with the handle in the X-Card-Reveal-Handle header. curl works. 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.
  3. Keep the response: the handle works once. Enter the details into the checkout.
The number works for one purchase, so you don’t need to hide it from the agent’s chat or browser. Don’t store it.
Then, from your own runtime:
The handle works once, until 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 in data.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. Send POST /virtual-cards/{cardId}/close. The request has no body and doesn’t need an Idempotency-Key, because repeating it is safe.
These callers can close a card:
  • The agent the card was issued to, while it has cards.read on the card’s wallet. To close a connected customer’s card, pass customerPartyId as a query parameter.
  • Any Owner or Admin on the account that owns the card’s wallet.
The response is 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 with card_blocked until the card is unfrozen. The agent can’t lift a freeze.
  • POST /virtual-cards/{cardId}/unfreeze: the card approves purchases again.
Both return 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_card takes the same fields as POST /agent-cards, except maximumAmount is a decimal amount in dollars, such as "25.00".
  • get_agent_card returns the card’s status.
  • get_agent_card_details returns a one-time reveal link: a URL on your relay host, the header name, the handle, when it expires, and a curl command 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_card closes a card, the same as POST /agent-cards/{cardId}/close. It returns closed or already_closed. On a retryable error, call it again.
  • list_card_transactions and get_card_transaction return the card’s purchases and refunds. Filter list_card_transactions by cardId to 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 active and 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.
An approved purchase holds the money in the wallet, and the card becomes 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’s decline 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
Other codes can appear. Natural keeps the code as it was recorded and returns the message “The card was declined.” A purchase with no recorded reason has the code 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’s data.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
The wallet owner gets an email when a purchase on an agent’s virtual card is approved or declined, and when a refund settles. These purchases and refunds also appear on the wallet’s monthly statement, with the agent’s name and the card’s last four digits in the memo.

Connected customers

A platform can follow a connected customer’s card activity with its party API key. Pass customerPartyId 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.