Sandbox & test cards

Sandbox vs production

Environment selection is driven by the API key prefix — there is no separate sandbox host:

Both prefixes hit the same base URL (https://api.settleflow.io). Always make sure the right key reaches the right environment in your deployment pipeline.

Test cards

SettleFlow's sandbox recognises these card numbers. Use any valid future expiry date (e.g. 12 / 2028) and any 3-digit CVV unless noted.

More test cards for specific edge cases (declines, insufficient funds, soft declines) can be requested from your SettleFlow account manager.

What the sandbox simulates

• Luhn validation (same as production).
• 3DS challenge redirect flow — the 3DSecureUrl points at a simulated ACS page.
• Webhook delivery with signed payloads (same HMAC scheme as production, using your sandbox webhook secret).
• Refund and status endpoints against sandbox transactions.

What the sandbox does not simulate:

• Real card network authorization latency (responses are faster than production).
• Dynamic chargeback / dispute flows — these must be staged by SettleFlow support.
• Bank-level decline reasons that depend on the issuing bank.

Typical testing checklist

Before switching to production, confirm the following all succeed in sandbox:

1. Auth + capture without 3DS — POST /v1/payment/direct with 4111111111111111 returns Status: captured and Code: 0.
2. 3DS challenge — POST /v1/payment/direct with 4000000000003220 and 3DS: "yes" returns 3DSecureUrl; after redirect, /v1/status/direct reports captured.
3. Webhook signature — a webhook hits your CallbackUrl, signature verifies successfully with your whsec_... sandbox secret (see Webhooks).
4. Refund — /v1/refund/direct on the captured transaction returns Status: captured, OperationType: refund.
5. Status lookup by Tid — /v1/status/direct with your own Tid returns the same transaction as when queried by Reference.
6. Error handling — a malformed request produces the expected numeric Code (e.g. 206 for an invalid card number). See Error codes.

Going live

Once the checklist passes, the cutover is simple:

1. Replace the sk_test_ key with your sk_live_ key in environment configuration.
2. Replace the sandbox whsec_ secret with the production one.
3. Point CallbackUrl and ReturnUrl at production URLs (HTTPS required).
4. Run a single low-value transaction on a real card and reconcile it in the SettleFlow merchant dashboard.
5. Monitor the first production webhook deliveries to confirm signatures verify with the live secret.