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	INVALID_INPUT (insufficient balance check)
003	INVALID_INPUT (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	Declined, cardDeclinedReason: INSUFFICIENT_FUNDS, as production declines an authorization the funding source cannot cover
003	Declined, cardDeclinedReason: CARD_NOT_ACTIVE. Use against a FROZEN card to verify it refuses authorizations
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, moves to VOIDED, and sends CARD_TRANSACTION.VOIDED.

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.STATUS_CHANGE webhooks plus transaction webhooks for the simulated authorization, clearing, and return — wire those into your local webhook handler to validate end-to-end.