Skip to main content
In Sandbox, your agent issues single-use cards the same way as in production. You then simulate the merchant side: authorize a purchase on the card, then capture, reverse, expire, or refund it. Natural approves or declines each authorization based on the card and the wallet. To test cards your customers use to pay you, see card fixtures. Issued-card simulations are available through the REST API and the Sandbox MCP server. The SDKs and CLI don’t support them yet.

​
Before you start

You need:
  • Issued cards enabled for your organization. To request access, contact hi@natural.com. Without it, card requests return 403 with issued_cards_not_enabled.
  • A funded wallet. Link a test bank account and deposit into the wallet. Sandbox deposits complete immediately.
  • An agent with cards.read on the wallet.
    • An agent connected over OAuth needs the cards:agent scope. If the agent connected before issued cards were enabled, reconnect it.
    • To act for a connected customer, the customer’s grant to your agent must include cards.read. Pass the customer’s party ID as customerPartyId.
Send every request below to https://api.sandbox.natural.com with a sandbox key.

​
Issue a test card

Issue a card with the agent’s key. maximumAmount is in cents and caps the card’s one purchase.
The response is the card (pcd_...). Use it once its status is active. A card expires after 60 minutes unless you set expiresInMinutes (5 to 1440).

​
Read the test card

GET /agent-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.

​
Simulate a purchase

Authorize a purchase on the card:
The response is a card transaction (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 409 with card_purchase_simulation_not_allowed.
Read the result with GET /card-transactions/{cardTransactionId}.

​
Who can simulate

  • The agent the card was issued to, while it has cards.read on the wallet.
  • The wallet owner’s dashboard user or party API key with payments.create on the wallet.
To simulate for a connected customer, use the connected agent and pass customerPartyId in the request attributes.

​
Declines

A declined authorization returns 200 with status declined and a decline object. No money moves.

​
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 503 with retryable: true means the simulation was accepted but its result wasn’t ready yet. Retry with the same key.