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 required in sandbox too, but 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 identity checks do not run, so you can upload any document images.The one exception is Mexico: if the customer selects Mexico they must upload a Constancia de Situación Fiscal at the tax-document step, or the flow does not pass. Any constancia works as long as it looks valid. Use this example, or see Country-specific requirements.Mexican customers must use the name LETICIA HERNANDEZ GONZALEZ. Sandbox still runs the RFC registry check. The sandbox registry returns this one test person for every RFC and compares the name to the customer’s personal data. Enter first name LETICIA and last name HERNANDEZ GONZALEZ at the personal data step. Any other name is rejected.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.We still read a Mexican customer’s constancia: its RFC comes from the document itself, so a sample belonging to somebody else records the wrong identity. The RFC registry check also runs, so send "firstName": "LETICIA" and "lastName": "HERNANDEZ GONZALEZ" as a Mexican customer’s personal data.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. 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.