Skip to main content

​
Overview

Contro provides a full sandbox environment for testing your integration. Sandbox mode is determined by the API key prefix:
  • sk_test_* — Sandbox mode. All operations use a separate ledger and simulated card provider.
  • sk_live_* — Production mode. Operations use real card providers and your live balance.
Sandbox and production data are fully isolated. Cardholders, cards, transactions, webhook events, and usage records created in sandbox mode are tagged with sandbox: true and never appear in live queries.

​
Test Data

When issuing cards in sandbox mode, the simulated card provider returns:
FieldValue
Card Number (PAN)4000 0000 0000 0000
CVV123
Expiry12/2030
BrandVisa
TypeVirtual

​
KYC Auto-Approval

When you call POST /partner/cardholders/{id}/kyc with a sandbox API key, KYC is approved instantly. No external verification provider is contacted. The response returns { "status": "approved" } and a cardholder.kyc.updated webhook is fired with sandbox: true in the payload.

​
Sandbox-Only Endpoints

These endpoints are only available when using a sk_test_ API key. They return 403 Forbidden with a live key.

​
Simulate Transaction

POST /partner/sandbox/simulate-transaction
Creates a real transaction record against a sandbox card, deducts transaction fees from the sandbox ledger, and fires a transaction.created webhook. 
{
  "cardId": "card_abc123",
  "amount": 2500,
  "currency": "USD",
  "merchantName": "Test Coffee Shop"
}

​
Reset Balance

POST /partner/sandbox/reset-balance
Resets your sandbox ledger balance to a specified amount or the default configured during partner creation. 
{
  "amount": 1000000
}

​
Simulate KYC Approval

POST /partner/sandbox/simulate-kyc-approval
Instantly approves a cardholder’s KYC status and fires the corresponding webhook. 
{
  "cardholderId": "ch_abc456"
}

​
Data Isolation

All sandbox resources are scoped separately from live resources:
  • Cardholders: sandbox: true flag — same externalUserId can exist in both modes
  • Cards: Issued with provider sandbox — no real card network involved
  • Transactions: Tagged with provider sandbox, only appear in sandbox queries
  • Webhooks: Events fired with sandbox: true in payload and stored with sandbox flag
  • Usage Records: Tracked separately so sandbox testing doesn’t inflate billing
  • Balance: Uses sandboxLedgerId instead of ledgerId — completely separate ledger

​
Go-Live Checklist

Before switching to production, complete the readiness checklist:
  1. KYB Approved — Your organization has been verified
  2. Sandbox Card Issued — At least one card issued with sk_test_ key
  3. Webhook Verified — At least one webhook successfully delivered
  4. Live Balance Funded — Your live account has a positive balance
Check your status via GET /partner/go-live-checklist or the dashboard Go-Live page.