Sandbox testing guide

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 → open the returned checkout, accept as the test buyer, and the transaction becomes 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 "Key2Pay-Version: 2026-10-12" \
  -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).