Sandbox testing guide

Sandbox is a fully isolated environment that never touches real money or real providers. It ships with built-in test payment methods and a simulate endpoint so you can create a payment and drive it through every outcome — completed, failed, expired, refunded, chargeback — asserting your webhook handler at each step. No provider credentials, no waiting.

How it works

1. List methods → sandbox always returns the built-in test rails below (even before you configure anything).
2. Create a payment with a test paymentMethodId → it lands as pending.
3. Call the simulate endpoint to move it to the status your test needs.
4. We fire the matching signed webhook(s) to your registered URL; assert + repeat.

Test payment methods

GET https://sandbox.key2pay.ai/api/v1/payment-methods returns these in sandbox. They mirror real LATAM rails so your request shape (e.g. PIX/SPEI requiring a buyer documentId) matches production. Any country/method also works — the sandbox cascade always accepts.

Simulate endpoint

Drives a sandbox payment to a terminal status on demand and fires the matching webhook(s). Bearer-authenticated, sandbox-only (refused with 400 in production). Body: { "action": "paid" | "failed" | "expired" | "refunded" | "chargeback" }.

# 1) Create a sandbox payment (lands as "pending"):
curl https://sandbox.key2pay.ai/api/v1/payments \
  -H "Authorization: Bearer sk_test_51N8mP...exampleK3Y" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 50, "paymentMethodId": "sbx_pix", "country": "BRA",
        "documentId": "12345678909", "userEmail": "test@test.com" }'
# → { "transactionId": "TXN-…", "status": "pending", … }

# 2) Mark it paid (fires payment.completed to your webhook):
curl https://sandbox.key2pay.ai/api/v1/payments/TXN-XXXX/simulate \
  -H "Authorization: Bearer sk_test_51N8mP...exampleK3Y" \
  -H "Content-Type: application/json" \
  -d '{ "action": "paid" }'
# → { "id":"TXN-XXXX","status":"completed","eventsFired":["payment.completed","payment.captured"] }

# Test a refund (needs a completed tx first):
curl https://sandbox.key2pay.ai/api/v1/payments/TXN-XXXX/simulate \
  -H "Authorization: Bearer sk_test_51N8mP...exampleK3Y" \
  -d '{ "action": "refunded" }'

# Test a chargeback (mark paid first, then chargeback):
curl https://sandbox.key2pay.ai/api/v1/payments/TXN-XXXX/simulate -d '{ "action": "paid" }' -H "Authorization: Bearer sk_test_51N8mP...exampleK3Y"
curl https://sandbox.key2pay.ai/api/v1/payments/TXN-XXXX/simulate -d '{ "action": "chargeback" }' -H "Authorization: Bearer sk_test_51N8mP...exampleK3Y"

Statuses you can simulate

End-to-end walkthrough

1. Get an sk_test_… key from the dashboard (API keys) for your sandbox shop.
2. Register a webhook URL for the events you want to test (or use a tunnel like ngrok).
3. GET /payment-methods → pick a test rail (e.g. sbx_pix).
4. POST /payments with that paymentMethodId → get the transactionId (pending).
5. POST /payments/{id}/simulate with {"action":"paid"} → assert you received payment.completed.
6. Repeat with failed / expired on fresh payments, and refunded / chargeback on a completed one.
7. When green, flip to production: swap the base URL + sk_live_… key and drop the simulate calls (production status comes from real providers + signed webhooks).