Sandbox Testing

Drive deterministic card outcomes with the simulate endpoints

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

merchant.descriptor must be 1–25 characters — the width of the card network’s acceptor-name field. A longer one is rejected with 400 INVALID_INPUT.

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",
    "fundingSources": ["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.