Why Sandbox Matters

  • Mirrors production ledger semantics.
  • Produces the same webhook payload shapes and retry behavior.
  • Lets you rehearse cutover runbooks without live funds.

Setup

  1. Load sandbox credentials.
  2. Register reachable webhook endpoints.
  3. Prefund master accounts used for issuance/topups.
  4. Ensure logs/metrics capture API responses and webhook attempts.

Core Helper Endpoints

Endpoint Description
POST /sandbox/transactions Simulate authorization, settle, cancel, refund, decline.
POST /sandbox/cards/fund Optional direct test funding for card shadow balances.
POST /v1/webhooks/resend Replay failed deliveries after receiver recovery.
GET /v2/accounts Confirm master-account balance changes after scenarios.

Transaction Recipes

Authorization -> Settlement -> Refund

# Authorization
curl -X POST "$PAYCA_BASE_URL/sandbox/transactions" \
  -H "Content-Type: application/json" \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET" \
  -d '{
    "cardId": "<card-id>",
    "currency": "USD",
    "type": "authorization",
    "amount": "60.00"
  }'

# Settlement
curl -X POST "$PAYCA_BASE_URL/sandbox/transactions" \
  -H "Content-Type: application/json" \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET" \
  -d '{
    "cardId": "<card-id>",
    "currency": "USD",
    "type": "settle",
    "amount": "60.00",
    "linkedId": "<linked-id-from-auth>"
  }'

# Refund
curl -X POST "$PAYCA_BASE_URL/sandbox/transactions" \
  -H "Content-Type: application/json" \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET" \
  -d '{
    "cardId": "<card-id>",
    "currency": "USD",
    "type": "refund",
    "amount": "60.00",
    "linkedId": "<linked-id-from-auth>"
  }'

Expect corresponding card_transaction and account_transaction payloads with shared referenceId.

Hold Release

{
  "cardId": "<card-id>",
  "currency": "USD",
  "type": "cancel",
  "amount": "10.00",
  "linkedId": "<linked-id-from-auth>"
}

Hard Decline

{
  "cardId": "<card-id>",
  "currency": "USD",
  "type": "decline",
  "amount": "20.00"
}

Webhook Chaos Test

  1. Return 500 from webhook receiver.
  2. Trigger a sandbox transaction.
  3. Verify retries and backoff.
  4. Restore 204 and confirm backlog drains.

Data Reset Strategy

  • Sandbox data is persistent; mark test runs with consistent metadata in your own tracking.
  • Request support-side purge when large data cleanup is needed.

Production Differences

Area Sandbox Behavior
Settlement timing Immediate (no batch delay).
Provider fees Optional simulation.
Limits Higher for testing, still finite.
Card numbers Non-PCI test PANs mapped to test BINs.

Exit Criteria

  • All webhook paths validated (auth, settle, cancel, refund, decline).
  • Replay tested with /v1/webhooks/resend.
  • Monitoring and alerts configured.
  • Reconciliation scripts verified against sandbox runs.

Continue with Go-Live Runbook for production cutover preparation.