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 is the single reference for everything that behaves differently in sandbox. If you haven’t 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 baked into 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. 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 embed a production API key in client-side code. Production integrations must call the API server-side.

​
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 + agreement signing) they auto-approve and a kyc_updated webhook fires, with no manual review. The document checks don’t 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, personal data is rejected 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 identically in sandbox, with the same one difference: the document checks don’t actually run, so document content isn’t scrutinised. Everything else is real. Submissions are validated the same way, land on the customer’s profile the same way, and the flow advances stage by stage, including the rule that personal data comes first, that a proof of address is only requested when the identity document carried 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.

​
Bank accounts in sandbox

Use a placeholder RFC to auto-approve a bank account. When registering a bank account via API in sandbox, use one of these placeholder RFCs so Etherfuse provisions it without involving the real SPEI provider:These skip SPEI provider registration and mark the account active immediately, so you can go straight to creating orders. Any other RFC in sandbox is sent to the SPEI provider’s sandbox and treated as a real registration; it will not auto-approve. Both placeholders are rejected in production.
Optional: test with a real bank account. To verify a real Mexican bank account wires up correctly with our SPEI provider, link it in sandbox using its real RFC. No real funds are moved; all sandbox transactions are simulated even with a real bank account. This is optional; the placeholder RFCs above cover standard testing.

​
Simulating orders in sandbox

No real money moves in sandbox; deposits and payouts are simulated.
  • Onramps: production detects the customer’s MXN deposit automatically via SPEI. In sandbox, simulate the deposit with the sandbox-only Simulate Fiat Received endpoint (POST /ramp/order/fiat_received) using the order’s orderId.
  • Offramps: no simulation step; the sandbox processes the fiat payout automatically once the burn transaction confirms on-chain.
  • Onramp cap: sandbox onramps are capped at 500 MXN per quote (larger amounts are rejected). Production has no such cap.
  • Every order response includes a statusPage URL (https://sandbox.etherfuse.com/ramp/order/<order_uuid>) you can open in a browser to track progress, sign transactions, and debug without polling. You must sign in to Etherfuse with an account in the order’s organization or its parent organization to open it.

​
Testnet tokens

You’ll need testnet tokens to test offramps and swaps; no need to contact Etherfuse. There is no faucet. Get tokens by onramping an Etherfuse token (e.g. CETES), then swapping it for any other supported token (USDC, etc.). See Testing Onramps and Testing Swaps.
Sandbox asset identifiers differ from production. Don’t hardcode mint/issuer addresses; always resolve the identifier from GET /ramp/assets for the current environment when quoting or building orders.
Stellar: trust lines for onramps are handled automatically. When onramping to a Stellar wallet without a trustline (or that doesn’t exist on-chain yet), pass walletAddress in the quote; the quote fee includes a one-time onboarding cost, and after the order completes you sign the stellarClaimTransaction from the order response to add the trustline and claim your tokens. For offramps and swaps, the wallet must already have trust lines: use GET /ramp/assets?blockchain=stellar to get identifiers in CODE:ISSUER format and establish the trustline first.

​
Webhooks in sandbox

Webhooks work the same in sandbox as in production. Make sure your endpoint is publicly reachable (or use a tunnel like ngrok for local development) and register it via POST /ramp/webhook.