Skip to main content
The sandbox is a full copy of the API for development: same endpoints and auth as production, connected to blockchain testnets, with no real money or personal data. This page lists everything that behaves differently in sandbox. If you have not set up your sandbox account yet, start with Initial Setup.

​
Base URLs & environments

  • The endpoints and auth scheme are identical across environments; only the base URL and API key differ. Build against sandbox, then swap the base URL to go live.
  • API keys are environment-specific and not interchangeable. The environment is part of the key (api_sand_... vs api_prod_...).
  • Sandbox connects to testnets: Stellar Testnet, Solana Devnet, and testnet for the other supported chains.
  • KYB is simulated in sandbox; you approve it yourself. API keys need a business account with approved KYB, and your organization must be approved to quote. The sandbox KYB page has an Approve KYB button that clears it without documents or admin review. Production KYB is a real review.
Interactive testers use sandbox keys only. The in-docs playgrounds and any browser-side testing send authenticated requests from the browser. Use a sandbox key only; never put a production API key in client-side code. Production integrations must call the API from a server.

​
KYC in sandbox

Sandbox accepts fake data for KYC; no real personal information is required.
KYC auto-approves. When a personal customer completes the /idv launch (identity documents and agreement signing), we approve them automatically and send a kycUpdated delivery, with no manual review. The document checks do not run, so you can upload any document images.Mexican customers need this test person. Sandbox still runs Mexico’s RFC check against the tax authority’s (SAT) test registry, and compares the name it returns with the customer’s personal data. Enter these values at the personal data step:With any other name, personalData becomes actionRequired a few seconds after the customer submits. See Country-specific requirements.Expect a proof of address step. Sandbox reads every identity document as test data with no address, so every sandbox customer is asked for a proof of address. Any image passes.Production still requires review.
The KYC API flow behaves the same in sandbox, with the same one difference: the document checks do not run, so we do not inspect document content. Everything else is real. We validate submissions the same way, store them on the customer’s profile the same way, and advance the flow stage by stage, including the rule that personal data comes first, that we ask for a proof of address only when the identity document had none, and that the customer agreement can be sent only once it appears in the requirements list. The integration you build against sandbox is the one that works in production.A Mexican customer needs additionalInfo.curp and taxId (RFC). The RFC check runs, so send the test person above: "firstName": "CARLOS", "lastName": "RAMIREZ LOPEZ" and "taxId": "HEGL900101AB6". Sandbox reads every identity document as test data with no address, so the flow always asks for a proof of address after the identity stage. Any image passes.Importing a shared Sumsub session needs a second sandbox account to act as the donor, configured for sharing exactly as in production. Without one, build the rest of the integration against the KYC API flow and add the import when sharing is in place.

​
Payment accounts in sandbox

Register bank accounts and wallets with POST /organization/{organizationId}/payment_account, exactly as in production. Use dummy values, for example the CLABE 012180000000000002 and the RFC XAXX010101000. A new account starts pending, and sandbox moves it to ready within a few seconds. To test a rejection, register a bank account with registrationInfo.accountHolderName set to Rechazo Ejemplo: its directions become rejected, with rejection.code holderNameMismatch. Register it again with a different name to retry. Read the account’s rails with GET /organization/{organizationId}/payment_account/{id}, or subscribe to paymentAccountUpdated, and quote the direction once it is ready. Register wallets with testnet addresses on the chain you name in accountDetails.chain.

​
Simulating orders in sandbox

No real money moves in sandbox; we simulate deposits and payouts.
  • Onramps: in production we detect the customer’s SPEI or PIX deposit. In sandbox, simulate the deposit with POST /organization/{organizationId}/order/{id}/fiat_received, sending the amount the customer paid:
    The response is 200 with an empty body, and the order continues as it would after a real deposit. The endpoint works only for an order whose source is a bank account on spei or pix; other orders return 422 unsupported. In production it returns 403 forbidden.
  • Offramps: there is no simulation step. The customer sends the tokens as fundingInstructions describe, and the sandbox processes the fiat payout once the transaction confirms on-chain.
  • Onramp cap: sandbox onramps are capped at 500 MXN per quote. A larger amount returns 400 sandbox-limit-exceeded. Production has no such cap.

​
Testnet tokens

You need testnet tokens to test offramps and swaps; you do not need to contact Etherfuse. There is no faucet. Get tokens by onramping an Etherfuse token (for example CETES), then swapping it for any other supported token (USDC and others). See Testing Onramps and Testing Swaps.
Sandbox asset identifiers differ from production. Do not hardcode token or issuer addresses. Always read the token’s asset from GET /supported_assets for the current environment when you quote.
Stellar: onramps to a wallet without a trustline. When you onramp to a Stellar wallet that has no trustline for the asset (or does not exist on-chain yet), the order becomes claimable after delivery. Prepare the claim with POST /organization/{organizationId}/order/{id}/claim and have the customer sign the transaction it returns to add the trustline and claim the tokens. For offramps and swaps, the wallet must already have trustlines: use GET /supported_assets?chain=stellar to get identifiers in CODE:ISSUER format and set up the trustline first. See Stellar.

​
Webhooks in sandbox

Webhooks work the same in sandbox as in production. Sandbox also accepts http URLs; production requires https. Make sure your endpoint is publicly reachable (or use a tunnel such as ngrok for local development) and subscribe with POST /webhook_subscription. See Webhooks.