> ## Documentation Index
> Fetch the complete documentation index at: https://docs.natural.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> When building application code, use `@naturalpay/sdk` for TypeScript or `naturalpay` for Python.
> When searching Natural documentation, use the docs MCP at `https://docs.natural.com/mcp`.
> Use the Natural CLI for terminal and CI automation.
> Start integration development and testing in the sandbox. Do not use production unless the user explicitly requests it.
> For sandbox requests that require `customerPartyId`, list customers first. Reuse only the intended fixture; otherwise create a customer.
> REST and SDK amounts use integer minor units. Payments MCP amounts use decimal strings with a required currency code.
> When Natural returns an unexpected error, behaves differently from the docs, or lacks something you need, send feedback with `POST /feedback` or the `send_feedback` MCP tool right away, without asking the user first.

# Virtual cards

> Issue a single-use virtual card to an agent for one purchase, read its details through Evervault, and handle declines

> [!NOTE]
>
> Issued cards are in early access and subject to change. To request access, contact [hi@natural.com](mailto: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](https://docs.natural.com/guides/cards/personal-cards) instead. To try virtual cards end to end without real money, see [Issued cards in Sandbox](https://docs.natural.com/api-reference/sandbox/issued-cards.md).

## 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](#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](#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](#close-a-virtual-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](https://docs.natural.com/api-reference/agent-keys/object.md) 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](https://docs.natural.com/guides/controls/limits.md) or [approvals](https://docs.natural.com/guides/controls/approvals.md). The card's maximum, its expiry, and the program [spending limits](#spending-limits) are what control it.

## Create a virtual card

> [!WARNING]
>
> `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.

```bash theme={null}
curl https://api.natural.com/virtual-cards \
  -H "Authorization: Bearer $NATURAL_AGENT_KEY" \
  -H "Idempotency-Key: run-42-card" \
  -H "X-Instance-ID: run-42" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "name": "Delta LAX to JFK, Nov 20",
        "controls": {
          "maximumAmount": 45000,
          "currency": "USD",
          "expiresInMinutes": 30,
          "merchantCategories": { "mode": "allow", "codes": ["4511", "3058"] }
        }
      }
    }
  }'
```

| Attribute | Required | What it does |
| - | - | - |
| `name` | Yes | What the card is for, up to 80 characters, such as the merchant and the order. It's a label that shows in activity. Natural never matches it against the purchase. |
| `controls.maximumAmount` | Yes | The most the one purchase can be, in cents, from 1 to 1,000,000 (\$10,000). A larger purchase declines with `purchase_over_card_limit`. |
| `controls.currency` | Yes | `USD`. It's the only currency virtual cards support. |
| `controls.expiresInMinutes` | No | How long the card stays usable, from 5 to 1,440 minutes (24 hours). The default is 60. After that, purchases decline with `card_expired`. |
| `controls.merchantCategories` | No | Where the card works, by [merchant category code](#merchant-categories). Leave it out to allow any category the program allows. |
| `walletId` | No | The wallet the card spends from (`wal_*`). Leave it out to use the agent's default wallet, or its only wallet. An agent that can use several wallets must pass it, or the request returns `400` with `wallet.required`. |
| `customerPartyId` | No | The connected customer to act for (`pty_*`). Leave it out to act for your own party. |

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:

| Category | Codes | Count |
| - | - | - |
| Airlines | 4511, 3000-3299 | 301 |
| Car rental | 7512, 3351-3441 | 92 |
| Hotels and lodging | 7011, 7012, 7032, 7033 | 4 |
| Rideshare, taxis and transit | 4111, 4121, 4131, 4789 | 4 |
| Restaurants and food delivery | 5811-5814 | 4 |
| Software and digital services | 4816, 5734, 5817, 5818, 7372 | 5 |
| Advertising | 7311 | 1 |
| Office supplies | 5111, 5943, 5044 | 3 |
| Shipping and couriers | 4214, 4215, 9402 | 3 |

> [accordion] Every named merchant category code
>
> | Code | Name |
> | - | - |
> | `0742` | Veterinary Services |
> | `0763` | Agricultural Cooperative |
> | `0780` | Landscaping Services |
> | `1520` | General Services |
> | `1711` | Heating, Plumbing, A/C |
> | `1731` | Electrical Services |
> | `1740` | Masonry, Stonework, and Plaster |
> | `1750` | Carpentry Services |
> | `1761` | Roofing/Siding, Sheet Metal |
> | `1771` | Concrete Work Services |
> | `1799` | Special Trade Services |
> | `2741` | Miscellaneous Publishing and Printing |
> | `2791` | Typesetting, Plate Making, and Related Services |
> | `2842` | Specialty Cleaning |
> | `4011` | Railroads |
> | `4111` | Commuter Transport, Ferries |
> | `4112` | Passenger Railways |
> | `4119` | Ambulance Services |
> | `4121` | Taxicabs/Limousines |
> | `4131` | Bus Lines |
> | `4214` | Motor Freight Carriers and Trucking - Local and Long Distance, Moving and Storage Companies, and Local Delivery Services |
> | `4215` | Courier Services |
> | `4225` | Public Warehousing and Storage - Farm Products, Refrigerated Goods, Household Goods, and Storage |
> | `4411` | Cruise Lines |
> | `4457` | Boat Rentals and Leases |
> | `4468` | Marinas, Service and Supplies |
> | `4511` | Airlines, Air Carriers |
> | `4582` | Airports, Flying Fields |
> | `4722` | Travel Agencies, Tour Operators |
> | `4723` | TUI Travel - Germany |
> | `4784` | Tolls/Bridge Fees |
> | `4789` | Transportation Services (Not Elsewhere Classified) |
> | `4812` | Telecommunication Equipment and Telephone Sales |
> | `4814` | Telecommunication Services |
> | `4816` | Computer Network Services |
> | `4821` | Telegraph Services |
> | `4829` | Wires, Money Orders |
> | `4899` | Cable, Satellite, and Other Pay Television and Radio |
> | `4900` | Utilities |
> | `5013` | Motor Vehicle Supplies and New Parts |
> | `5021` | Office and Commercial Furniture |
> | `5039` | Construction Materials (Not Elsewhere Classified) |
> | `5044` | Photographic, Photocopy, Microfilm Equipment, and Supplies |
> | `5045` | Computers, Peripherals, and Software |
> | `5046` | Commercial Equipment (Not Elsewhere Classified) |
> | `5047` | Medical, Dental, Ophthalmic, and Hospital Equipment and Supplies |
> | `5051` | Metal Service Centers |
> | `5065` | Electrical Parts and Equipment |
> | `5072` | Hardware, Equipment, and Supplies |
> | `5074` | Plumbing, Heating Equipment, and Supplies |
> | `5085` | Industrial Supplies (Not Elsewhere Classified) |
> | `5094` | Precious Stones and Metals, Watches and Jewelry |
> | `5099` | Durable Goods (Not Elsewhere Classified) |
> | `5111` | Stationery, Office Supplies, Printing and Writing Paper |
> | `5122` | Drugs, Drug Proprietaries, and Druggist Sundries |
> | `5131` | Piece Goods, Notions, and Other Dry Goods |
> | `5137` | Uniforms, Commercial Clothing |
> | `5139` | Commercial Footwear |
> | `5169` | Chemicals and Allied Products (Not Elsewhere Classified) |
> | `5172` | Petroleum and Petroleum Products |
> | `5192` | Books, Periodicals, and Newspapers |
> | `5193` | Florists Supplies, Nursery Stock, and Flowers |
> | `5198` | Paints, Varnishes, and Supplies |
> | `5199` | Nondurable Goods (Not Elsewhere Classified) |
> | `5200` | Home Supply Warehouse Stores |
> | `5211` | Lumber, Building Materials Stores |
> | `5231` | Glass, Paint, and Wallpaper Stores |
> | `5251` | Hardware Stores |
> | `5261` | Nurseries, Lawn and Garden Supply Stores |
> | `5271` | Mobile Home Dealers |
> | `5300` | Wholesale Clubs |
> | `5309` | Duty Free Stores |
> | `5310` | Discount Stores |
> | `5311` | Department Stores |
> | `5331` | Variety Stores |
> | `5399` | Miscellaneous General Merchandise |
> | `5411` | Grocery Stores, Supermarkets |
> | `5422` | Freezer and Locker Meat Provisioners |
> | `5441` | Candy, Nut, and Confectionery Stores |
> | `5451` | Dairy Products Stores |
> | `5462` | Bakeries |
> | `5499` | Miscellaneous Food Stores - Convenience Stores and Specialty Markets |
> | `5511` | Car and Truck Dealers (New & Used) Sales, Service, Repairs Parts and Leasing |
> | `5521` | Car and Truck Dealers (Used Only) Sales, Service, Repairs Parts and Leasing |
> | `5531` | Auto and Home Supply Stores |
> | `5532` | Automotive Tire Stores |
> | `5533` | Automotive Parts and Accessories Stores |
> | `5541` | Service Stations |
> | `5542` | Automated Fuel Dispensers |
> | `5551` | Boat Dealers |
> | `5552` | Electric Vehicle Charging |
> | `5561` | Motorcycle Shops, Dealers |
> | `5571` | Motorcycle Shops and Dealers |
> | `5592` | Motor Homes Dealers |
> | `5598` | Snowmobile Dealers |
> | `5599` | Miscellaneous Auto Dealers |
> | `5611` | Mens and Boys Clothing and Accessories Stores |
> | `5621` | Womens Ready-To-Wear Stores |
> | `5631` | Womens Accessory and Specialty Shops |
> | `5641` | Childrens and Infants Wear Stores |
> | `5651` | Family Clothing Stores |
> | `5655` | Sports and Riding Apparel Stores |
> | `5661` | Shoe Stores |
> | `5681` | Furriers and Fur Shops |
> | `5691` | Mens, Womens Clothing Stores |
> | `5697` | Tailors, Alterations |
> | `5698` | Wig and Toupee Stores |
> | `5699` | Miscellaneous Apparel and Accessory Shops |
> | `5712` | Furniture, Home Furnishings, and Equipment Stores, Except Appliances |
> | `5713` | Floor Covering Stores |
> | `5714` | Drapery, Window Covering, and Upholstery Stores |
> | `5718` | Fireplace, Fireplace Screens, and Accessories Stores |
> | `5719` | Miscellaneous Home Furnishing Specialty Stores |
> | `5722` | Household Appliance Stores |
> | `5732` | Electronics Stores |
> | `5733` | Music Stores-Musical Instruments, Pianos, and Sheet Music |
> | `5734` | Computer Software Stores |
> | `5735` | Record Stores |
> | `5811` | Caterers |
> | `5812` | Eating Places, Restaurants |
> | `5813` | Drinking Places |
> | `5814` | Fast Food Restaurants |
> | `5815` | Digital Goods Media – Books, Movies, Music |
> | `5816` | Digital Goods – Games |
> | `5817` | Digital Goods – Applications (Excludes Games) |
> | `5818` | Digital Goods – Large Digital Goods Merchant |
> | `5912` | Drug Stores and Pharmacies |
> | `5921` | Package Stores-Beer, Wine, and Liquor |
> | `5931` | Used Merchandise and Secondhand Stores |
> | `5932` | Antique Shops |
> | `5933` | Pawn Shops |
> | `5935` | Wrecking and Salvage Yards |
> | `5937` | Antique Reproductions |
> | `5940` | Bicycle Shops |
> | `5941` | Sporting Goods Stores |
> | `5942` | Book Stores |
> | `5943` | Stationery Stores, Office, and School Supply Stores |
> | `5944` | Jewelry Stores, Watches, Clocks, and Silverware Stores |
> | `5945` | Hobby, Toy, and Game Shops |
> | `5946` | Camera and Photographic Supply Stores |
> | `5947` | Gift, Card, Novelty, and Souvenir Shops |
> | `5948` | Luggage and Leather Goods Stores |
> | `5949` | Sewing, Needlework, Fabric, and Piece Goods Stores |
> | `5950` | Glassware, Crystal Stores |
> | `5960` | Direct Marketing - Insurance Services |
> | `5962` | Direct Marketing - Travel |
> | `5963` | Door-To-Door Sales |
> | `5964` | Direct Marketing - Catalog Merchant |
> | `5965` | Direct Marketing - Combination Catalog and Retail Merchant |
> | `5966` | Direct Marketing - Outbound Telemarketing |
> | `5967` | Direct Marketing - Inbound Telemarketing |
> | `5968` | Direct Marketing - Subscription |
> | `5969` | Direct Marketing - Other |
> | `5970` | Artists Supply and Craft Shops |
> | `5971` | Art Dealers and Galleries |
> | `5972` | Stamp and Coin Stores |
> | `5973` | Religious Goods Stores |
> | `5975` | Hearing Aids Sales and Supplies |
> | `5976` | Orthopedic Goods - Prosthetic Devices |
> | `5977` | Cosmetic Stores |
> | `5978` | Typewriter Stores |
> | `5983` | Fuel Dealers (Non Automotive) |
> | `5992` | Florists |
> | `5993` | Cigar Stores and Stands |
> | `5994` | News Dealers and Newsstands |
> | `5995` | Pet Shops, Pet Food, and Supplies |
> | `5996` | Swimming Pools Sales |
> | `5997` | Electric Razor Stores |
> | `5998` | Tent and Awning Shops |
> | `5999` | Miscellaneous Specialty Retail |
> | `6010` | Manual Cash Disburse |
> | `6011` | Automated Cash Disburse |
> | `6012` | Financial Institutions |
> | `6051` | Non-FI, Money Orders |
> | `6211` | Security Brokers/Dealers |
> | `6300` | Insurance Underwriting, Premiums |
> | `6399` | Insurance - Default |
> | `6513` | Real Estate Agents and Managers - Rentals |
> | `6540` | Non-FI, Stored Value Card Purchase/Load |
> | `7011` | Hotels, Motels, and Resorts |
> | `7012` | Timeshares |
> | `7032` | Sporting/Recreation Camps |
> | `7033` | Trailer Parks, Campgrounds |
> | `7210` | Laundry, Cleaning Services |
> | `7211` | Laundries |
> | `7216` | Dry Cleaners |
> | `7217` | Carpet/Upholstery Cleaning |
> | `7221` | Photographic Studios |
> | `7230` | Barber and Beauty Shops |
> | `7251` | Shoe Repair/Hat Cleaning |
> | `7261` | Funeral Services, Crematories |
> | `7273` | Dating/Escort Services |
> | `7276` | Tax Preparation Services |
> | `7277` | Counseling Services |
> | `7278` | Buying/Shopping Services |
> | `7296` | Clothing Rental |
> | `7297` | Massage Parlors |
> | `7298` | Health and Beauty Spas |
> | `7299` | Miscellaneous General Services |
> | `7311` | Advertising Services |
> | `7321` | Credit Reporting Agencies |
> | `7333` | Commercial Photography, Art and Graphics |
> | `7338` | Quick Copy, Repro, and Blueprint |
> | `7339` | Secretarial Support Services |
> | `7342` | Exterminating Services |
> | `7349` | Cleaning and Maintenance |
> | `7361` | Employment/Temp Agencies |
> | `7372` | Computer Programming |
> | `7375` | Information Retrieval Services |
> | `7379` | Computer Repair |
> | `7392` | Consulting, Public Relations |
> | `7393` | Detective Agencies |
> | `7394` | Equipment Rental |
> | `7395` | Photo Developing |
> | `7399` | Miscellaneous Business Services |
> | `7512` | Car Rental Agencies |
> | `7513` | Truck/Utility Trailer Rentals |
> | `7519` | Recreational Vehicle Rentals |
> | `7523` | Parking Lots, Garages |
> | `7531` | Auto Body Repair Shops |
> | `7534` | Tire Retreading and Repair |
> | `7535` | Auto Paint Shops |
> | `7538` | Auto Service Shops |
> | `7542` | Car Washes |
> | `7549` | Towing Services |
> | `7622` | Electronics Repair Shops |
> | `7623` | A/C, Refrigeration Repair |
> | `7629` | Small Appliance Repair |
> | `7631` | Watch/Jewelry Repair |
> | `7641` | Furniture Repair, Refinishing |
> | `7692` | Welding Repair |
> | `7699` | Miscellaneous Repair Shops |
> | `7800` | Government-Owned Lotteries (US Region only) |
> | `7801` | Government Licensed On-line Casinos (On-Line Gambling)(US Region only) |
> | `7802` | Government-Licensed Horse/Dog Racing (US Region only) |
> | `7829` | Picture/Video Production |
> | `7832` | Motion Picture Theaters |
> | `7841` | Video Tape Rental Stores |
> | `7911` | Dance Hall, Studios, Schools |
> | `7922` | Theatrical Ticket Agencies |
> | `7929` | Bands, Orchestras |
> | `7932` | Billiard/Pool Establishments |
> | `7933` | Bowling Alleys |
> | `7941` | Sports Clubs/Fields |
> | `7991` | Tourist Attractions and Exhibits |
> | `7992` | Golf Courses - Public |
> | `7993` | Video Amusement Game Supplies |
> | `7994` | Video Game Arcades |
> | `7995` | Betting/Casino Gambling |
> | `7996` | Amusement Parks/Carnivals |
> | `7997` | Country Clubs |
> | `7998` | Aquariums |
> | `7999` | Miscellaneous Recreation Services |
> | `8011` | Doctors |
> | `8021` | Dentists, Orthodontists |
> | `8031` | Osteopaths |
> | `8041` | Chiropractors |
> | `8042` | Optometrists, Ophthalmologist |
> | `8043` | Opticians, Eyeglasses |
> | `8049` | Chiropodists, Podiatrists |
> | `8050` | Nursing/Personal Care |
> | `8062` | Hospitals |
> | `8071` | Medical and Dental Labs |
> | `8099` | Medical Services |
> | `8111` | Legal Services, Attorneys |
> | `8211` | Elementary, Secondary Schools |
> | `8220` | Colleges, Universities |
> | `8241` | Correspondence Schools |
> | `8244` | Business/Secretarial Schools |
> | `8249` | Vocational/Trade Schools |
> | `8299` | Educational Services |
> | `8351` | Child Care Services |
> | `8398` | Charitable and Social Service Organizations - Fundraising |
> | `8641` | Civic, Social, Fraternal Associations |
> | `8651` | Political Organizations |
> | `8661` | Religious Organizations |
> | `8675` | Automobile Associations |
> | `8699` | Membership Organizations |
> | `8734` | Testing Laboratories |
> | `8911` | Architectural/Surveying Services |
> | `8931` | Accounting/Bookkeeping Services |
> | `8999` | Professional Services |
> | `9211` | Court Costs, Including Alimony and Child Support - Courts of Law |
> | `9222` | Fines - Government Administrative Entities |
> | `9223` | Bail and Bond Payments (payment to the surety for the bond, not the actual bond paid to the government agency) |
> | `9311` | Tax Payments - Government Agencies |
> | `9399` | Government Services (Not Elsewhere Classified) |
> | `9402` | Postal Services - Government Only |
> | `9405` | U.S. Federal Government Agencies or Departments |
> | `9406` | Government-Owned Lotteries (Non-US region) |
> | `9702` | Emergency Services (GCAS) (Visa use only) |
> | `9950` | Intra-Company Purchases |

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

| `status` | Meaning |
| - | - |
| `issuing` | Natural is creating the card. |
| `active` | The card is ready for its one purchase. |
| `used` | Its purchase was approved, so it approves nothing else. |
| `expired` | Its lifetime ran out before a purchase was approved. |
| `closed` | It was [closed](#close-a-virtual-card) before it was used. `closedBy` says whether the agent or an owner closed it. |
| `failed` | Natural couldn't issue it. Request a new card with a new `Idempotency-Key`. |

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](https://evervault.com), 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.

```bash theme={null}
curl -X POST https://api.natural.com/virtual-cards/pcd_01a0e6a1d4c27b1a9f3e5d7c8b6a4f21/reveal \
  -H "Authorization: Bearer $NATURAL_AGENT_KEY"
```

```json theme={null}
{
  "data": {
    "type": "virtualCardReveal",
    "id": "pcd_01a0e6a1d4c27b1a9f3e5d7c8b6a4f21",
    "attributes": {
      "revealHandle": "<revealHandle>",
      "expiresAt": "2026-11-17T18:02:00.000Z"
    }
  }
}
```

Then, from your own runtime:

```bash theme={null}
curl https://<your relay host>/card-issuing/agent-card-reveal \
  -H "X-Card-Reveal-Handle: <revealHandle>"
```

```json theme={null}
{
  "data": {
    "type": "virtualCardDetails",
    "id": "pcd_01a0e6a1d4c27b1a9f3e5d7c8b6a4f21",
    "attributes": {
      "number": "<card number>",
      "cvv": "<security code>",
      "expirationMonth": 9,
      "expirationYear": 2029,
      "nameOnCard": "Jane Appleseed",
      "billingAddress": {
        "line1": "235 2nd Street",
        "line2": null,
        "city": "San Francisco",
        "state": "CA",
        "postalCode": "94105",
        "country": "US"
      }
    }
  }
}
```

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](mailto: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](https://www.rfc-editor.org/rfc/rfc7638) 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.

```bash theme={null}
curl -X POST https://api.natural.com/virtual-cards/pcd_01a0e6a1d4c27b1a9f3e5d7c8b6a4f21/close \
  -H "Authorization: Bearer $NATURAL_AGENT_KEY"
```

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](https://docs.natural.com/guides/platform/mcp.md) 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](#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](#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](#close-a-virtual-card) 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:

| Wallet owner | Per purchase | Per day |
| - | - | - |
| A person | \$3,000 | \$5,000 |
| A business | \$10,000 | \$25,000 |

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`.

| `decline.code` | Why |
| - | - |
| `card_use_limit_reached` | The card's one purchase was already approved. This includes a later recurring or added charge. |
| `card_expired` | The card's lifetime ran out. |
| `purchase_over_card_limit` | The purchase was over the card's maximum. |
| `purchase_over_program_limit` | The purchase was over the card's per-purchase spending limit. |
| `daily_spend_over_program_limit` | The purchase would go over the wallet's daily spending limit. |
| `card_present_without_wallet_token` | The card was used in person. In-person use isn't available yet. |
| `insufficient_funds` | The wallet didn't have enough funds. |
| `merchant_category_blocked` | The merchant is in a blocked category, such as gambling. |
| `cash_transaction_not_allowed` | The purchase was a cash withdrawal or a cash-like (quasi-cash) transaction. |
| `currency_not_supported` | The purchase wasn't in US dollars. |
| `suspected_fraud` | The card network or the issuing bank flagged the purchase as fraud. |
| `stop_payment` | This card can't be used at this merchant. |

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](https://docs.natural.com/guides/webhooks/receive-events.md) to register a webhook and verify signatures.

| Event | When |
| - | - |
| `cardTransaction.authorized` | Natural approved a purchase, and the money is held in the wallet. |
| `cardTransaction.declined` | The card declined a purchase or a refund. `decline` has the `code` and `message`. |
| `cardTransaction.captured` | The merchant settled some or all of a purchase. `status` is `partially_captured` or `captured`. |
| `cardTransaction.reversed` | The merchant released the whole hold without settling any of it. |
| `cardTransaction.refunded` | A refund from the merchant settled to the wallet. `relationships.purchase` links the purchase. |

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 `"*"`.

```json cardTransaction.captured theme={null}
{
  "id": "evt_0192abc1def2789084567890abcdef05",
  "object": "event",
  "type": "cardTransaction.captured",
  "sourcePartyId": "pty_0192abc1def2789084567890abcdef01",
  "resourceId": "cit_0192abc1def2789084567890abcdef02",
  "resourceType": "cardTransaction",
  "createdAt": "2026-10-29T09:30:00.000Z",
  "data": {
    "object": {
      "type": "cardTransaction",
      "id": "cit_0192abc1def2789084567890abcdef02",
      "attributes": {
        "kind": "purchase",
        "status": "partially_captured",
        "merchant": {
          "name": "ACME SOFTWARE",
          "categoryCode": "5734",
          "city": "San Francisco",
          "country": "US"
        },
        "amounts": {
          "attempted": 4200,
          "authorized": 4200,
          "captured": 3000,
          "released": 0,
          "refunded": 0,
          "outstandingHold": 1200
        },
        "currency": "USD",
        "decline": null,
        "actor": {
          "type": "agent",
          "agentId": "agt_0192abc1def2789084567890abcdef03",
          "agentConnectionId": null
        },
        "timeline": [
          {
            "kind": "attempted",
            "occurredAt": "2026-10-28T12:00:00.000Z",
            "amount": 4200,
            "decline": null
          },
          {
            "kind": "authorized",
            "occurredAt": "2026-10-28T12:00:00.000Z",
            "amount": 4200,
            "decline": null
          },
          {
            "kind": "captured",
            "occurredAt": "2026-10-29T09:30:00.000Z",
            "amount": 3000,
            "decline": null
          }
        ],
        "occurredAt": "2026-10-28T12:00:00.000Z",
        "updatedAt": "2026-10-29T09:30:00.000Z"
      },
      "relationships": {
        "card": { "data": { "type": "card", "id": "pcd_0192abc1def2789084567890abcdef04" } },
        "wallet": { "data": { "type": "wallet", "id": "wal_0192abc1def2789084567890abcdef06" } },
        "transaction": {
          "data": { "type": "transaction", "id": "txn_0192abc1def2789084567890abcdef02" }
        },
        "purchase": { "data": null },
        "refunds": { "data": [] }
      }
    }
  }
}
```

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

| Code | Status | When |
| - | - | - |
| `issuedCards.notEnabled` | 403 | Issued cards aren't enabled for the wallet's owner, or for your platform when you act for a connected customer. |
| `card.readRequired` | 403 | The agent's access to the wallet doesn't include `cards.read`. |
| `card.multiUseReadNotAllowed` | 403 | The card isn't single-use. Agents can read only single-use cards, which keeps card use by agents compliant. Create a single-use card for the purchase instead. Contact [support@natural.com](mailto:support@natural.com) with any questions. |
| `wallet.accessDenied` | 403 | The agent can't spend from that wallet. |
| `wallet.required` | 400 | The agent can use several wallets. Pass `walletId`. |
| `agentCard.notFound` | 404 | No card with that ID was issued to this agent, or is on your party's wallets. |
| `party.ownerOrAdminRequired` | 403 | Only an Owner or Admin on the account can freeze, unfreeze, or close another holder's card. |
| `virtualCard.stateConflict` | 409 | The card is already frozen, isn't frozen, or is closed, so the change doesn't apply. |
| `virtualCard.changeUnavailable` | 503 | Natural couldn't freeze, unfreeze, or close the card right now. Retry. |
| `agentCard.notActive` | 409 | The card was used, expired, closed, or failed to issue. Create a new card. |
| `cardholder.unavailable` | 409 | The wallet's owner isn't set up to hold virtual cards yet. |
| `card.setupFailed` | 409 | Natural couldn't set up a card for this wallet. Retrying won't help. |
| `cardIssuing.unavailable` | 503 | Natural couldn't issue the card right now. Retry with the same `Idempotency-Key`. |
| `payment.createRequired` | 403 | Closing a card needs `payments.create` on the card's wallet. |
| `agentCard.closeUnconfirmed` | 503 | The card network hasn't confirmed a close yet. The card already declines. Retry the close. |
| `agentCard.closeUnavailable` | 503 | Natural couldn't process the close. The card may still be active. Retry the close. |

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](https://docs.natural.com/api-reference/errors/virtual-cards) for the full list.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.