Sandbox Testing

The card network can’t reach into Sandbox to send real authorizations, so Sandbox exposes three simulate helpers that drive the same internal authorize and reconcile paths the issuer would call in production. Production returns 404 on these paths.

POST /sandbox/cards/{id}/simulate/authorization
POST /sandbox/cards/{id}/simulate/clearing
POST /sandbox/cards/{id}/simulate/return

Authorization outcomes are deterministic and driven by magic-value suffixes on merchant.descriptor. Other Sandbox helpers use the identifier suffixes described in their sections, including /sandbox/internal-accounts/{id}/fund.

Funding-source suffixes (accountId)

Binding a funding source resolves based on the last three characters of accountId:

Suffix	Behavior
`002`	`FUNDING_SOURCE_INELIGIBLE` (insufficient balance check)
`003`	`FUNDING_SOURCE_INELIGIBLE` (account closed)
any other	Success

Authorization simulate

curl -X POST "$GRID_BASE_URL/sandbox/cards/Card:019542f5-b3e7-1d02-0000-000000000010/simulate/authorization" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1250,
    "currency": { "code": "USD" },
    "merchant": {
      "descriptor": "BLUE BOTTLE COFFEE SF",
      "mcc": "5814",
      "country": "US"
    }
  }'

Outcomes are controlled by the last three characters of merchant.descriptor:

Suffix	Outcome
`002`	Decline — `INSUFFICIENT_FUNDS` (the pull on the funding source fails)
`003`	Decline — `CARD_PAUSED` (use against a `FROZEN` card to verify)
`005`	Delayed pull (~30s) — exercises the `PENDING → CONFIRMED` path
`006`	Pull succeeds but the confirmation event reports `FAILED` — exercises the high-urgency `EXCEPTION` alert
any other	Approved

The response is the resulting CardTransaction.

Clearing simulate

curl -X POST "$GRID_BASE_URL/sandbox/cards/Card:019542f5-b3e7-1d02-0000-000000000010/simulate/clearing" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "cardTransactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000100",
    "amount": 1500
  }'

amount > authorizedAmount exercises the over-auth post-hoc pull path (restaurant tip / tip-on-top).
amount = 0 exercises AUTHORIZATION_EXPIRY — the auth expires with no clearing posted.

Suffix-driven outcomes on the parent transaction’s id govern whether the post-hoc pull succeeds — use them with the merchant descriptor suffixes above to construct deterministic exception scenarios.

Return simulate

curl -X POST "$GRID_BASE_URL/sandbox/cards/Card:019542f5-b3e7-1d02-0000-000000000010/simulate/return" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "cardTransactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000100",
    "amount": 1500
  }'

A refund posts as its own dated CREDIT CardTransaction linked to the purchase via originalTransactionId; the purchase keeps its SETTLED status, whether the refund is full or partial.

End-to-end happy path

A simple Sandbox loop that exercises issue → activate → auth → clear → refund:

# 1. Issue a virtual card
curl -X POST "$GRID_BASE_URL/cards" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "Customer:...",
    "form": "VIRTUAL",
    "fundingSource": "InternalAccount:..."
  }'

# 2. Simulate auth — any non-magic descriptor approves
curl -X POST "$GRID_BASE_URL/sandbox/cards/Card:.../simulate/authorization" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 1250, "currency": {"code":"USD"}, "merchant": {"descriptor":"BLUE BOTTLE COFFEE SF"} }'

# 3. Clear the auth
curl -X POST "$GRID_BASE_URL/sandbox/cards/Card:.../simulate/clearing" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "cardTransactionId": "Transaction:...", "amount": 1500 }'

# 4. Refund the cleared transaction
curl -X POST "$GRID_BASE_URL/sandbox/cards/Card:.../simulate/return" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "cardTransactionId": "Transaction:...", "amount": 1500 }'

At each step you’ll see CARD.STATE_CHANGE webhooks plus transaction webhooks for the simulated authorization, clearing, and return — wire those into your local webhook handler to validate end-to-end.

Overview

Onboarding

Card management

Transactions

Card design

Platform tools

Funding-source suffixes (accountId)

Authorization simulate

Clearing simulate

Return simulate

End-to-end happy path

​Funding-source suffixes (accountId)

​Authorization simulate

​Clearing simulate

​Return simulate

​End-to-end happy path

Funding-source suffixes (accountId)

Authorization simulate

Clearing simulate

Return simulate

End-to-end happy path