Sandbox

A sandbox shop lets you test payment handling without sending real crypto. Each merchant can have one sandbox shop.

Create a separate shop with "sandbox": true. An existing live shop cannot be switched into sandbox mode.

Test an invoice

1. Create an invoice in the sandbox shop using the quickstart.
2. Save its id as your issuance_id.
3. Simulate a confirmed incoming payment:

curl -X POST 'https://platform.invoise.me/api/v1/shops/{shop_id}/sandbox/simulate' \
  -H 'Authorization: Bearer ivk_...' \
  -H 'Idempotency-Key: <saved-unique-key>' \
  -H 'Content-Type: application/json' \
  -d '{"issuance_id":"<issuance-id>","kind":"transfer.confirmed","amount":"10000000"}'

Use the invoice’s actual amount in base units. An empty {} body does not identify a payment and will fail.

In sandbox, one invoice or simulated transfer can be at most 10,000 tokens; a larger amount returns 400 sandbox_amount_limit. Sandbox invoices and deposit addresses are counted separately from production. See Limits.

Read the status endpoint again. A fully funded invoice reaches funded; webhook subscribers can receive transfer.confirmed. The simulation inserts the requested event, not an entire real blockchain payment.

To simulate invoice closure after funding, send a new idempotency key with:

{"issuance_id":"<issuance-id>","kind":"invoice.closed","amount":"0"}

That tests the settled state. To test corrections, simulate transfer.reverted with reference_event_id set to the earlier event ID. Use a different saved key for each new simulated event.

Start a clean test

POST /api/v1/shops/{shop_id}/sandbox/reset deletes sandbox payment history. It requires an owner session, fresh MFA if enabled, and an Idempotency-Key.

Old idempotency keys keep their original results after reset. Use new keys for new test payments.

Before accepting real payments

Sandbox checks your API and event handling. It does not prove real network confirmations, gas costs or receipt at an exchange. Test a small real payment separately before relying on that route.