Saltar al contenido principal
Sandbox es un despliegue de SpherePay separado que se comporta como producción y no mueve nada de valor. Lo usas para construir tu integración, ejercitar el ciclo de vida de una transferencia y ejecutar tu suite de pruebas sin clientes reales, fondos reales ni documentos de identidad reales. Los cuerpos de tus solicitudes son idénticos en ambos lugares. Cambia tanto la URL base como la clave: cada host acepta solo las claves de su propio entorno.

Qué es diferente

Todo lo demás — endpoints, formas de solicitud, formas de respuesta, eventos de webhook, sobres de error — es el mismo código. Ese es el punto: lo que construyes contra sandbox es lo que se ejecuta en producción.

Obtén una clave de sandbox

Las claves de sandbox se crean desde el dashboard, en modo sandbox, en Developers → API Keys. Comienzan con sandbox_secret_ para que reconozcas de un vistazo que una clave no es una credencial de producción. Una clave de sandbox funciona solo contra api.sandbox.spherepay.co, y una clave de producción funciona solo contra api.spherepay.co. No hay enrutamiento entre ambos: si presentas la clave equivocada, la solicitud se rechaza exactamente como se rechazaría cualquier clave desconocida.
Mantén las claves de sandbox y de producción en configuraciones separadas. Apuntar una suite de pruebas a producción porque una clave se pegó en la variable de entorno equivocada mueve dinero real.

Elige una red

Pasa los mismos identificadores de red que usas en producción. Sandbox los resuelve a redes de prueba:
En sandbox eso llega a Sepolia. sol llega a Solana Devnet. Una solicitud de sandbox que nombra una red sin configuración de prueba se rechaza en lugar de caer a una red mainnet. No puedes alcanzar mainnet con una clave de sandbox.

Emite tokens de prueba

SPHEREUSDC es la stablecoin de prueba de sandbox. Emítela a cualquier dirección en cualquiera de las dos redes de prueba con el faucet:
Genera la clave de idempotencia una vez por emisión y reutilízala si reintentas, para que una respuesta perdida no emita dos veces. La respuesta es 202 Accepted con un id de emisión. La emisión es asíncrona, así que consulta para obtener el hash de la transacción:
amount toma 1000 por defecto y acepta como máximo 1000 por llamada. Se rechaza una emisión que lleve la billetera por encima de 10000 SPHEREUSDC, contando las emisiones pendientes. Envía un encabezado Idempotency-Key para que un reintento devuelva la misma emisión en lugar de emitir dos veces. Reutilizar una clave con parámetros distintos devuelve 409.
El faucet emite tokens, no gas. Financia el saldo nativo de la billetera desde un faucet público de Sepolia o Solana Devnet antes de enviar una transacción desde ella.

Avanza una transferencia

En producción una transferencia avanza por su ciclo de vida a medida que llegan los depósitos y los rieles liquidan. En sandbox la avanzas tú:
Cada avance ejecuta la misma máquina de estados y el mismo pipeline de webhooks que producción, así que tus manejadores de webhooks reciben los eventos que recibirán en producción, en las mismas formas. El endpoint es idempotente por estado. Avanzar al estado en el que la transferencia ya está devuelve el resultado original y no emite nada, por lo que una llamada repetida o concurrente es segura. Solo algunas transiciones son legales desde un estado dado. Una ilegal devuelve transfer/invalid-transition en lugar de forzar la transferencia a un estado inconsistente.
Estas rutas existen solo en el despliegue de sandbox. En api.spherepay.co devuelven 404, así que no hay forma de avanzar una transferencia real a mano.

Endpoints de simulación

Estos endpoints existen solo en https://api.sandbox.spherepay.co: La simulación de depósitos para offloader wallets y cuentas virtuales llegará pronto.

Límites de tasa

Las rutas exclusivas de sandbox se limitan por aplicación, no por IP, para que un runner de CI compartido no se limite a sí mismo: Todos los demás endpoints siguen los límites de Límites de Tasa.

Qué no hace sandbox

  • No contiene fondos reales, así que nada de lo que hagas en sandbox puede mover dinero.
  • No ejecuta verificación de identidad real. Los clientes que crees no son analizados por Sumsub.
  • No es un entorno de staging para SpherePay. Se despliega desde la misma rama que producción, al mismo tiempo.
Última modificación el 16 de noviembre de 2026