Testing

Every account starts in test mode. A test store uses test networks, test API keys and tokens that have no value, so you can build and break your integration without touching real funds.

Test mode and live mode

Each store has an environment, test or live, and everything follows from it:

A key only ever acts on its own store, so a test key cannot create a live invoice. Live stores need live approval first; see Going live.

Test networks and tokens

Test mode uses BNB Smart Chain testnet (bsc-testnet, 15 confirmations) and Ethereum Sepolia (eth-sepolia, 12 confirmations). Other test networks exist but stay disabled until the platform operator enables them. GET /v1/assets?environment=test lists what is currently offered.

The same symbol can have different decimals on different networks; USDT and USDC have 18 decimals on BNB Smart Chain and 6 on Ethereum. Always use the decimals of the asset row, never a value assumed from the symbol.

Test tokens are contracts configured by the platform operator and have no value. To pay a test invoice for real you need those test tokens plus test native coin (tBNB or Sepolia ETH) for gas. Ask your platform operator which test tokens are configured.

Simulate a payment

You do not need any tokens to test your webhook handling. Open a pending or partial invoice of a test store under Payments in the dashboard and press Simulate payment (or Simulate remaining payment). The dashboard calls POST /dashboard/invoices/{id}/simulate, which runs the same crediting path as a real payment:

• the invoice becomes paid (or partial, if you simulate less than the remaining amount);
• invoice.paid is emitted and delivered to your endpoints exactly as for a real payment;
• the invoice and the payment are marked simulated: true, and the action is recorded in the audit log.

Nothing moves on chain and nothing settles: a simulated invoice is excluded from settlement, and a refund request on it is refused (invoice_simulated) because no funds exist. Simulation is refused on live stores (403 simulate_live_forbidden) and needs a role that can create invoices (owner, admin, developer or finance).

Send a test event

To check that your endpoint is reachable and your signature check works, press Send test next to the endpoint under Webhooks & API, or call POST /v1/webhook-endpoints/{id}/ping. It sends a ping event with {"message": "Zenq Pay webhook test"}, signed like every other event and sent even if the endpoint is filtered to other event types. The delivery and its attempts appear in the delivery list.

A suggested test plan

1. Create an invoice with a test key and open its checkout_url.
2. Send a test event; confirm your receiver answers 2xx and rejects a tampered body with 400.
3. Simulate a payment; confirm the order is fulfilled once.
4. Replay that delivery from the dashboard; confirm the order is not fulfilled a second time (deduplication on the event id).
5. Let an invoice expire; confirm invoice.expired does not fulfil anything.
6. Pay one invoice with real test tokens on a test network and watch it go confirming → paid.