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.