What is different
Everything else — endpoints, request shapes, response shapes, webhook events, error envelopes — is the same code. That is the point: what you build against sandbox is what runs in production.
Get a sandbox key
Sandbox keys are created from the dashboard, in sandbox mode, under Developers → API Keys. They start withsandbox_secret_ so you can tell at a glance that a key is not a production credential.
A sandbox key works only against api.sandbox.spherepay.co, and a production key works only against api.spherepay.co. There is no routing between them: present the wrong key and the request is rejected exactly as any unrecognized key would be.
Choose a network
Pass the same network slugs you use in production. Sandbox resolves them to test networks:sol reaches Solana Devnet.
A sandbox request naming a network with no test configuration is rejected rather than falling through to a mainnet network. You cannot reach mainnet from a sandbox key.
Mint test tokens
SPHEREUSDC is the sandbox test stablecoin. Mint it to any address on either test network with the faucet:202 Accepted with a mint id. Minting is asynchronous, so poll for the transaction hash:
amount defaults to 1000 and accepts at most 1000 per call. A mint that would take the wallet above 10000 SPHEREUSDC, counting pending mints, is refused. Send an Idempotency-Key header so a retry returns the same mint rather than minting twice. Reusing a key with different parameters returns 409.
The faucet mints tokens, not gas. Fund the wallet’s native balance from a public Sepolia or Solana Devnet faucet before sending a transaction from it.
Advance a transfer
In production a transfer moves through its lifecycle as deposits arrive and rails settle. In sandbox you drive it yourself:transfer/invalid-transition rather than forcing the transfer into an inconsistent state.
These routes exist only on the sandbox deployment. On
api.spherepay.co they return 404, so there is no way to advance a real transfer by hand.Simulation endpoints
These endpoints exist only onhttps://api.sandbox.spherepay.co:
- Advance a sandbox customer:
POST /v2/sandbox/customer/{id}/advance - Advance a sandbox transfer:
POST /v2/sandbox/transfer/{id}/advance - Mint test tokens:
POST /v2/sandbox/faucet - Retrieve a test token mint:
GET /v2/sandbox/faucet/{id}
Rate limits
The sandbox-only routes are limited per application, not per IP, so a shared CI runner does not throttle itself:
Every other endpoint follows the limits on Rate Limits.
What sandbox does not do
- It holds no real funds, so nothing you do in sandbox can move money.
- It does not run real identity verification. Customers you create are not screened by Sumsub.
- It is not a staging environment for SpherePay. It deploys from the same branch as production, at the same time.