Sandbox integration

Test without USDC or credits

Open API → Sandbox. Create a test key, create a test invoice and simulate pending, failed, paid, expired or cancelled states. There is no blockchain transaction. Test records and keys are isolated from live payments, receipts, events and credits.

POST /sandbox/keys                        # live billing:write key; secret shown once
POST /sandbox/invoices                    # test bearer key + Idempotency-Key
{"amount":"1"}
POST /sandbox/invoices/{id}/simulate      # test key
{"status":"paid"}
GET /sandbox/invoices/{id}                # test key

Test keys start with test_, expire in 30 days, and cannot call live payment endpoints. Live keys cannot replace test keys in sandbox invoice endpoints. Keep at most 5 active keys and 1000 test invoices; invoice retention and idempotency last 7 days. Lists return up to 50 records. Terminal paid, expired and cancelled states cannot be changed.

Test webhook signatures and duplicate delivery

PUT /sandbox/webhook                     # live billing:write key
{"url":"https://store.example/test-hook"}
POST /sandbox/invoices/{id}/webhook       # test key, after simulated payment

Save the separate test signing secret. Deliveries use HTTPS, public-address validation and no redirects. Explicit replay is limited to once per minute; the event ID and body remain the same, with a fresh signature timestamp. There is no automatic retry. Changing the endpoint requires rotate:true and a new secret.

Test events use sandbox.payment_intent.succeeded, test:true, livemode:false and a test_evt_ ID. Verify the HMAC as described in Webhooks, with the test secret. Never fulfill a real order from a test event. Sandbox tests API integration, not wallet or chain behavior.