Sandbox testing

The sandbox runs the same API as production, with test data and no real money. Mock endpoints let you move any customer or order to any status, so you can test every branch of your code in minutes.

Sandbox vs production

	Sandbox	Production
Host	`https://sandbox.zapyd.com`	`https://api.zapyd.com`
Credentials	Sandbox key, secret and widget `app_id`	Production key, secret and widget `app_id`
KYC	Set it with a mock endpoint	Real checks
Payins	Any well-formed transfer reference, then a mock status	Real bank transfers
Payouts	Sepolia testnet stablecoins, then a mock status	Mainnet funds
Mock endpoints	Available	Not available

Every request is signed the same way in both environments. The Quickstart has a request helper that the examples below use.

Mock endpoints

Object	Endpoint	Values
Customer KYC	`PATCH /cms/api/v1/kyc/mock-kyc-status`	`VERIFIED`, `UNVERIFIED`, `DOCUMENT_VERIFICATION_FAILED`, `TAX_VERIFICATION_FAILED`, `ADDITIONAL_INFO_VERIFICATION_FAILED`
Bank account	`POST /cms/api/v1/bank/mock-bank-verification`	`VERIFIED`, `FAILED` (with a `failure_reason`), `MANUAL_REVIEW`
Payin	`PATCH /pis/api/v1/payin/mock-payin-status`	`SUCCESS`, `ON_HOLD`, `REFUNDED`, `FAILED`
Payout	`PATCH /pos/api/v1/payout/mock-payout-status`	`SUCCESS`, `FAILED`, `REFUNDED`
Payin EDD	`PATCH /ren/api/v1/payin/edd/mock-status`	`VERIFIED`, `FAILED`, `IN_REVIEW`, `DOCS_REQ`, `PROCESSING`
Payout EDD	`PATCH /ren/api/v1/payout/edd/mock-status`	`VERIFIED`, `FAILED`, `IN_REVIEW`, `DOCS_REQ`, `PROCESSING`

Each mock fires the same webhook production would send, except the bank account mock: read the account to see its new status.

await zapyd("PATCH", "/cms/api/v1/kyc/mock-kyc-status", { customer_id, kyc_status: "VERIFIED" });
await zapyd("PATCH", "/pis/api/v1/payin/mock-payin-status", { payin_id, payin_status: "ON_HOLD" });
await zapyd("PATCH", "/pos/api/v1/payout/mock-payout-status", { payout_id, payout_status: "REFUNDED" });

Test funds for payouts

Payout quotations on sepolia return a testnet wallet_address.

Get Sepolia ETH for gas and testnet stablecoins from a faucet.
Send the exact sending_amount to the quotation’s wallet_address.
Initiate with the Sepolia transaction hash, then set the result with the mock endpoint.

Sepolia works only in sandbox. Never send real funds to a sandbox address.

Webhooks on your laptop

Zapyd needs a public HTTPS URL. Expose your local server with a tunnel such as ngrok, then register it:

ngrok http 3000

await zapyd("POST", "/org/api/v1/organizations/api-webhooks", {
  webhook_url: "https://<your-subdomain>.ngrok-free.app/webhooks/zapyd",
});

Scenarios to cover

Customers and KYC

Customer create, then the same client_reference_id again (it returns the same customer)
KYC VERIFIED, then each failure value and its update endpoint
Bank account VERIFIED and FAILED

Payins

Quotation, then initiate before and after expiry_time
Every final status: SUCCESS, ON_HOLD, REFUNDED, FAILED
A reused transaction_reference_id is rejected
Crypto is credited only on SUCCESS

Payouts

Quotation with sending_amount, and with receiving_amount
A reused transaction_hash is rejected
Every final status: SUCCESS, FAILED, REFUNDED

Limits and EDD

A limit is exceeded, then EDD is submitted and mocked to VERIFIED and FAILED

Errors and webhooks

Wrong signature, expired timestamp and wrong module prefix
Duplicate webhook delivery is ignored
Your endpoint is down, and the order is recovered by polling

When everything passes, work through the Go-live checklist.

Get started

Onboard customers

Move money

Widget and no-code

Build and test

Markets

Coverage and help

Sandbox testing

Sandbox vs production

Mock endpoints

Test funds for payouts

Webhooks on your laptop

Scenarios to cover

​Sandbox vs production

​Mock endpoints

​Test funds for payouts

​Webhooks on your laptop

​Scenarios to cover

Sandbox vs production

Mock endpoints

Test funds for payouts

Webhooks on your laptop

Scenarios to cover