Sandbox de API para cripto: probar pagos con seguridad

Un sandbox de API cripto es una copia aislada de una API de pagos o de wallets en la que puede crear wallets, enviar transacciones y recibir notificaciones sin mover dinero real. Pasa a producción cambiando las credenciales y la configuración de red. Los proveedores usan el término de forma distinta: algunos simulan saldos y otros le remiten a una testnet pública de blockchain.

Esta guía explica la diferencia, recorre un plan de pruebas desde la primera clave hasta el primer webhook, y enumera lo que conviene verificar antes del lanzamiento.

TL;DR

• Un sandbox es una copia aislada de una API, gestionada por el proveedor. Una testnet es una blockchain pública separada con monedas sin valor. Muchos equipos usan ambas.
• Pruebe el ciclo completo: crear una wallet, financiarla, enviar una transacción, confirmarla, recibir el webhook y gestionar un fallo.
• Los webhooks son donde se esconden la mayoría de los errores de pago. Pruebe las comprobaciones de firma, los reintentos, los duplicados y los eventos fuera de orden.
• Nunca reutilice claves de producción ni secretos de wallets en código de prueba, y nunca deje que direcciones de prueba se filtren a la configuración de producción.
• Antes del lanzamiento, compare redes soportadas, activos, comportamiento de comisiones y tiempos de confirmación entre prueba y producción.

¿Qué es un sandbox de API cripto?

El término se usa con poca precisión, así que empiece con una definición de trabajo. En el diseño de APIs, un mock devuelve respuestas predefinidas. Un sandbox completo es distinto: Redocly lo describe como un entorno aislado y con estado que persiste registros, ejecuta la lógica de negocio y le permite probar acciones destructivas sin arriesgar datos de producción. Esa distinción importa en cripto. Si crea una wallet y luego pide su saldo, un mock le devuelve lo que se le haya programado decir. Un sandbox recuerda la wallet que creó.

Un sandbox cripto suele hacer tres cosas:

1. Emite claves de API de prueba separadas que no pueden tocar fondos reales.
2. Le permite crear cuentas o wallets y asignarles saldos de prueba.
3. Simula, o retransmite a una testnet, las transacciones y notificaciones que vería en producción.

Sandbox frente a testnet frente a devnet

Una testnet de blockchain no es lo mismo que un sandbox de API. Una testnet es una red pública separada que imita la red principal para que los desarrolladores experimenten sin lo que supone el dinero real. La documentación de Ethereum describe las testnets como el equivalente de un servidor de preproducción. Indica Sepolia como testnet predeterminada recomendada para desarrollar aplicaciones, y señala que la mayoría de las personas obtiene ETH de testnet gratis desde faucets.

Las monedas de testnet no deberían tener valor real. Trate como una señal de alarma a cualquiera que le pida dinero a cambio de ellas.

La conclusión práctica: un sandbox prueba su integración con la API, mientras que una testnet prueba cómo se comporta su código en una cadena real, aunque sin valor. Cada cadena documenta sus propias redes de prueba: Tron tiene Shasta y Nile, y la guía para desarrolladores de Bitcoin explica los modos testnet y regtest.

¿Cómo se prueba un pago cripto, paso a paso?

Los proveedores difieren en los detalles, pero la secuencia de abajo se sostiene casi siempre.

1. Obtenga credenciales de prueba

Cree una cuenta y busque un modo de prueba o sandbox separado, o una URL base distinta. Los buenos proveedores emiten claves diferentes por entorno, de modo que una clave de prueba simplemente falla contra producción. Guarde la clave en una variable de entorno o en un gestor de secretos desde la primera línea de código, no en el repositorio.

Si el proveedor usa peticiones firmadas, como hacen las APIs basadas en HMAC, implemente la función de firma una vez y escriba una prueba unitaria con una entrada y una salida conocidas. Un salto de línea mal colocado en la cadena que firma produce errores que parecen fallos de autenticación durante horas.

2. Cree una wallet

Llame al endpoint de creación de wallets y anote lo que devuelve: la dirección, un identificador y si el proveedor conserva la clave privada o se la entrega a usted. Ese último punto determina su modelo de seguridad, así que escríbalo. Cree varias wallets en cada red que piense soportar, porque los formatos de dirección difieren entre cadenas y son una fuente habitual de errores de validación.

3. Financie con activos de prueba

Aquí es donde más divergen los sandboxes. Algunos le permiten acreditar un saldo mediante una llamada a la API o un botón del panel. Otros esperan que pida monedas a un faucet público de la testnet correspondiente y las envíe a su nueva dirección. Los faucets pueden tener límites de peticiones o quedarse vacíos, así que pida fondos temprano en el día, no diez minutos antes de una demostración. Mantenga una wallet de prueba bien financiada como su «banco» y recargue desde ella las wallets más pequeñas.

4. Envíe una transacción

Empiece por el caso más sencillo: una transferencia de moneda nativa entre dos de sus wallets. Después pase a las transferencias de tokens (tokens al estilo ERC-20, BEP-20 o TRC-20), porque los tokens añaden llamadas a contratos, una mecánica de comisiones distinta y, en algunas cadenas, una moneda de comisión separada. Anote el ID de transacción que devuelve la API y compárelo con lo que muestra un explorador de bloques de esa red de prueba.

5. Verifique el resultado

Una transacción tiene varios estados, y su aplicación debe modelarlos en lugar de usar una sola marca de «pagado»:

• Enviada: aceptada por la API, aún no en la cadena.
• Pendiente: vista en el mempool o en un bloque con muy pocas confirmaciones.
• Confirmada: suficientes confirmaciones para su tolerancia al riesgo.
• Fallida o descartada: rechazada, sin gas, reemplazada o nunca minada.

Para los informes de ingresos, cuente los pagos liquidados, no los intentos. Lo mismo vale para las confirmaciones en una cadena: una transacción pendiente todavía no es ingreso.

¿Cómo se prueban los webhooks y las rutas de fallo?

Los webhooks convierten una API de pagos de algo que se consulta en algo que le avisa cuando llega el dinero. También son donde las integraciones se rompen con más frecuencia, porque el remitente controla el momento.

Reciba una notificación de extremo a extremo

Necesita una URL HTTPS pública que llegue a su máquina de desarrollo. Sirve una herramienta de túnel o un servidor de preproducción. Registre la URL, envíe una transacción de prueba a una dirección vigilada y confirme que su manejador recibe el evento con los campos que espera. Nuestro artículo sobre cómo usar webhooks para procesar depósitos automáticamente explica la estructura habitual.

Lista de comprobación de webhooks

• Verifique la firma. Rechace cualquier petición cuya firma no coincida, y pruébelo alterando el valor firmado. Con Chaingateway, el valor firmado es el txid, así que compruebe también el importe y el destinatario frente a lo esperado. El artículo sobre secretos personales lo explica.
• Pruebe la idempotencia. Entregue dos veces el mismo evento. Su sistema debe abonar al usuario una sola vez, así que guarde un ID de evento o de transacción y compruébelo antes de actuar.
• Pruebe la entrega fuera de orden. Un evento «confirmado» puede llegar antes que el de «pendiente». No deje que un estado antiguo sobrescriba uno más reciente.
• Pruebe un receptor lento o con fallos. Devuelva un error o deje la petición colgada durante 30 segundos, y observe qué hace el proveedor. Chaingateway no reintenta automáticamente: las notificaciones fallidas se enumeran, y usted solicita el reenvío de cada una.
• Responda rápido. Conteste pronto con un código de éxito y haga el trabajo pesado en una cola. Los manejadores largos provocan tiempos de espera y entregas duplicadas.
• Repita tras una caída. Apague su receptor, envíe transacciones y vuelva a encenderlo. Sepa cómo recuperará los eventos perdidos, por ejemplo desde la lista de notificaciones fallidas o desde el historial de transacciones.

Fallos que conviene provocar

Rompa cosas a propósito en el sandbox, que para eso existe:

• Envíe más de lo que tiene la wallet.
• Envíe a una dirección malformada o a una dirección de otra red.
• Envíe un token a una wallet que no tiene moneda nativa para pagar comisiones.
• Fije una comisión demasiado baja y observe cómo se atasca la transacción.
• Envíe un importe diminuto por debajo de su umbral mínimo de pago.
• Pague un poco menos o un poco más de lo que espera la factura. Los pagos insuficientes y los excesivos son rutinarios en el checkout cripto, así que decida su política y pruébela.

¿En qué difiere el sandbox de producción?

Un sandbox es un modelo, y los modelos dejan cosas fuera. Antes de cambiar a claves reales, revise estas áreas de forma explícita.

Después ejecute un pago canario en producción: una transferencia real pequeña que recorra todo el flujo, desde la creación de la wallet hasta el webhook y el asiento en el libro contable. Cuesta unos céntimos o unos dólares, y detecta errores de configuración que ningún sandbox puede detectar.

¿Cómo se protegen las claves durante las pruebas?

Los entornos de prueba son donde empiezan los malos hábitos, y los hábitos pasan a producción.

• Use claves separadas por entorno. Nómbrelas con claridad y dé prefijos distintos en su gestor de secretos, para que una confusión sea visible.
• Mantenga los secretos fuera del repositorio. Use variables de entorno, una bóveda o el almacén de secretos de su CI. Revise el historial de commits si alguna vez se cuela una clave, y rótela.
• No importe nunca una wallet real a una configuración de prueba. Si una frase semilla o una clave privada controla fondos reales, no debe estar en un script de prueba, en una captura de pantalla ni en un mensaje de chat.
• Restrinja quién puede ver las claves. Los contratistas y las agencias que trabajan en su integración deben recibir solo claves de prueba.
• Fije las URL base en la configuración, no en el código. Añada una comprobación al arrancar que se niegue a funcionar si una clave de prueba se empareja con la URL real, o al revés.
• Rote las claves después de las demostraciones. Las claves que se mostraron en pantalla o en una grabación deben tratarse como expuestas.

¿Qué limitaciones conviene revisar desde el principio?

Antes de comprometerse con el sandbox de un proveedor, haga algunas preguntas directas:

1. ¿Qué redes cubre en modo prueba? Si su producto necesita Ethereum, Tron y Bitcoin, confirme las tres, no solo una.
2. ¿Qué estándares de token y qué activos? Las monedas nativas son fáciles. Las stablecoins y los NFT es donde aparecen los huecos.
3. ¿Cómo se obtienen los fondos de prueba, y hay límites? Los límites de los faucets y los máximos diarios determinan la rapidez con la que puede iterar su equipo.
4. ¿Persiste el estado? Un sandbox con estado permite construir escenarios de varios pasos. Un mock sin estado no.
5. ¿Están disponibles los webhooks en modo prueba, y puede dispararlos a voluntad?
6. ¿Cuán estable es? Las testnets se reinician o se dejan de mantener, lo que puede borrar sus wallets de prueba. Mantenga la configuración en scripts para poder reconstruirla en minutos.

Si además necesita entender qué tipos de proveedor encajan con cada trabajo, nuestra comparativa de APIs de blockchain y cuándo usar cada tipo es un buen complemento.

¿Cómo se prueba con Chaingateway?

Chaingateway no ofrece un sandbox simulado independiente con saldos ficticios. Su documentación de API describe las pruebas en testnets públicas: añada la cabecera X-Network: testnet a una petición, o déjela fuera para mainnet. Los mismos endpoints, claves y formas de respuesta se aplican a ambas. Cada cadena tiene su propia testnet, enumerada en la página de redes compatibles:

Una primera prueba necesita cuatro peticiones. Cree una dirección, financiela desde el faucet de la cadena, registre un webhook y envíe una transferencia:

# 1. Create an address on Sepolia
curl -X POST https://app.chaingateway.io/api/v2/ethereum/addresses \
  -H "Authorization: Bearer $CHAINGATEWAY_TOKEN" \
  -H "X-Network: testnet" \
  -H "Content-Type: application/json" \
  -d '{"password": "use-a-strong-test-password"}'

# 2. Fund the address from a Sepolia faucet, then register a webhook for it
curl -X POST https://app.chaingateway.io/api/v2/ethereum/webhooks \
  -H "Authorization: Bearer $CHAINGATEWAY_TOKEN" \
  -H "X-Network: testnet" \
  -H "Content-Type: application/json" \
  -d '{"to": "0xYourNewAddress", "url": "https://your-tunnel.example/hooks", "type": "ETH", "reference": "test-1"}'

La respuesta de la primera llamada contiene la nueva dirección. En el caso del webhook, type indica el tipo de activo. En Ethereum los valores son ETH, ERC20 y ERC721, y otras cadenas usan sus propios nombres, como TRC20 en Tron. La referencia de la API los enumera. Los webhooks existen en todas las cadenas soportadas salvo Solana, así que para Solana pruebe consultando transacciones mediante sondeo.

Chaingateway firma los webhooks con una cabecera X-Signature una vez que define un secreto personal, y no reintenta por sí mismo las notificaciones fallidas. Ambas cosas merecen una prueba en testnet. Los planes empiezan en 49 € al mes con Plus, Pro cuesta 99 €, Premium 249 € y Enterprise 499 € al mes. La facturación anual es de 490 €, 990 €, 2.490 € y 4.990 € respectivamente. Todos los planes empiezan con una prueba gratuita de 7 días sin tarjeta ni KYC. Consulte la página de precios, y las páginas de la API Blockchain y de los webhooks de Chaingateway para más detalles.

Para ideas sobre qué construir cuando sus pruebas pasen, nuestro repaso de los casos de uso de una API de blockchain es una buena lectura siguiente.

¿Cómo es un plan de pruebas práctico?

Use esto como lista de comprobación de una sola página para una publicación.

1. Configuración: claves de prueba guardadas en un gestor de secretos, URL base en la configuración, función de firma con pruebas unitarias.
2. Wallets: cree al menos dos por red soportada, y anote los formatos de dirección.
3. Financiación: financie una wallet maestra de prueba, y programe la recarga de las demás.
4. Camino feliz: transferencia nativa, después transferencia de token, cada una verificada en un explorador de bloques.
5. Webhooks: comprobación de firma, entrega duplicada, eventos fuera de orden, caída del receptor.
6. Fallos: saldo insuficiente, dirección de otra red, falta de moneda de comisión, comisión baja, pago insuficiente, pago excesivo.
7. Modelo de estados: su base de datos gestiona enviada, pendiente, confirmada y fallida sin ambigüedad.
8. Carga: ráfaga de transacciones dentro de los límites de peticiones de su plan.
9. Revisión de seguridad: ningún secreto de producción en código de prueba, logs depurados de claves y semillas.
10. Canario: un pago real pequeño por todo el flujo antes de anunciar el lanzamiento.

Fuentes

• Networks, documentación para desarrolladores de Ethereum (testnets y faucets)
• Networks, documentación para desarrolladores de Tron (Shasta y Nile)
• Testing applications, guía para desarrolladores de Bitcoin
• What you really need to build an API sandbox, Redocly

Recomendado

• API Blockchain: una API REST para Bitcoin, Ethereum y otras 5 cadenas
• Cómo crear una wallet cripto con una API: guía de 2026
• Desarrolladores: lance pagos cripto recurrentes en 90 días, EIP y 2026
• Recibir pagos cripto en Laravel: guía práctica