Cómo probar tus pagos en el sandbox de TAYPI

Probar una integración de pagos sin arriesgar un solo centavo es posible gracias al entorno de sandbox pagos QR pruebas. Si estás desarrollando o configurando tu e-commerce para aceptar pagos con QR interoperable en Perú, el sandbox te permite recorrer cada paso del proceso —desde la generación del código hasta la verificación de los webhooks— antes de conectarte a transacciones reales. En esta guía te explicamos cómo sacarle el máximo provecho, qué puedes simular y qué debes tener en cuenta para llegar a producción con la certeza de que todo funciona correctamente.

¿Qué es un sandbox de pagos y por qué es indispensable para tu integración?

Un sandbox de pagos es un entorno de pruebas aislado que replica el funcionamiento completo de una pasarela, pero sin mover dinero real ni afectar a clientes de verdad. Cuando hablamos de sandbox pagos QR pruebas nos referimos exactamente a eso: un laboratorio donde puedes enviar solicitudes a la API, generar códigos QR de prueba, recibir notificaciones simuladas y validar la seguridad de la comunicación, todo con credenciales especiales que no tienen efecto en el mundo real.

Para un desarrollador o un comercio que está dando sus primeros pasos en cobros digitales, el sandbox es la herramienta que separa una integración robusta de un lanzamiento con errores. Los beneficios principales incluyen:

• Validación temprana del flujo de cobro: puedes asegurarte de que el QR se genera correctamente, que el monto y la referencia son los esperados, y que el checkout_url dirige al pagador a la experiencia correcta.
• Pruebas de seguridad sin riesgo: verificar las firmas HMAC-SHA256 y el correcto manejo de claves en un entorno controlado evita exponer datos sensibles durante el desarrollo.
• Simulación de escenarios diversos: aunque no muevas dinero, puedes confirmar cómo se comporta tu sistema ante un pago exitoso, un error de red o un reintento por idempotencia.
• Reducción del tiempo de integración: al tener un sandbox bien diseñado, los equipos de desarrollo pueden iterar más rápido y detectar problemas antes de pasar a producción.

En el ecosistema de pagos en Perú, donde la interoperabilidad QR del BCRP conecta Yape, Plin y cualquier billetera interoperable, contar con un sandbox que refleje esa realidad es una ventaja enorme. Así no tienes que adivinar cómo se verá un cobro confirmado por la Cámara de Compensación Electrónica (CCE); el sandbox te permite verlo antes de salir a producción. Si quieres entender mejor ese marco, te recomendamos leer cómo funciona la interoperabilidad QR del BCRP.

El sandbox de TAYPI: claves, entorno y qué puedes simular

La pasarela TAYPI ofrece a los comercios un entorno de pruebas completamente funcional. Al registrarte en la plataforma, obtienes de inmediato un par de claves de sandbox (API Key y Secret) que te permiten empezar a integrar sin pasar por procesos de verificación KYB ni configurar una cuenta bancaria real. Este entorno está pensado para que developers y comercios prueben a fondo la integración de pagos con QR interoperable antes de activar las claves de producción.

Dentro del sandbox de TAYPI puedes simular, como mínimo, estos flujos:

• Creación de un cobro: realizas una petición a la API y obtienes un objeto de pago que contiene un qr_code (la representación del QR dinámico en texto) y un checkout_url, el enlace que puedes mostrar al cliente en una página web o enviar por cualquier medio. Cada QR generado es único, tiene un monto fijo y expira en 15 minutos, tal como ocurre en producción, lo que te permite probar también esa lógica de expiración.
• Confirmación de pago simulada: una vez creado el cobro, desde el panel de sandbox puedes marcarlo como pagado para que el sistema actúe exactamente igual que si una entidad financiera hubiera confirmado la transacción.
• Recepción y validación de webhooks: al simular la confirmación, el entorno de pruebas envía una notificación en tiempo real a la URL que hayas configurado. El webhook incluye la información del pago y una firma en el encabezado, que debes verificar usando el algoritmo HMAC-SHA256 con tu clave secreta de sandbox. Esta práctica es exactamente la misma que harás en producción, por lo que es fundamental dominarla. Si quieres profundizar en este mecanismo, consulta cómo verificar firmas HMAC-SHA256 en tu backend.
• Pruebas de idempotencia: al enviar una solicitud con un idempotency_key único, puedes comprobar que, si repites la misma petición con esa clave, el sistema devuelve la respuesta original y no crea un cobro duplicado. Esto es crítico para evitar cobrar dos veces al mismo cliente por un error en la red. Te sugerimos revisar nuestro artículo sobre la importancia de la idempotencia en APIs de pago.

Es importante destacar que el sandbox no procesa tarjetas de crédito o débito, porque TAYPI se enfoca exclusivamente en el ecosistema de billeteras y QR interoperable peruano (Yape, Plin y cualquier billetera conectada a la CCE). Por lo tanto, tus pruebas siempre estarán alineadas con la experiencia real que tendrán tus clientes.

Cómo obtener tus claves de sandbox y configurar tu entorno de pruebas

El primer paso para empezar con el sandbox pagos QR pruebas es conseguir las credenciales. El proceso es sencillo y completamente gratuito:

1. Regístrate en la plataforma: accede a la documentación para developers o directamente al panel de registro. Solo necesitas un correo electrónico y algunos datos básicos de tu negocio. No se te pedirá información bancaria para el entorno sandbox.
2. Accede al panel de control: una vez dentro, dirígete a la sección de “Integraciones” o “Desarrolladores”. Ahí encontrarás las claves de sandbox etiquetadas claramente (por ejemplo, sandbox_api_key y sandbox_secret). Asegúrate de estar en el entorno de pruebas y no en el de producción.
3. Configura tu URL de webhook: en la misma sección podrás indicar una URL pública (por ejemplo, un endpoint de tu servidor local expuesto con un túnel como ngrok) a la que TAYPI enviará las notificaciones simuladas. Recomendamos usar HTTPS incluso en pruebas para asemejar las condiciones reales de seguridad, dado que TAYPI utiliza TLS 1.3 en todas las comunicaciones.
4. Elige tu ruta de integración: puedes usar directamente la API REST, alguno de los SDKs oficiales —disponibles en PHP, JavaScript/TypeScript y .NET— o los plugins para WooCommerce o WHMCS. El sandbox funciona con cualquiera de estos métodos, así que elige el que más se ajuste a tu stack tecnológico.

Una buena práctica es definir desde el inicio una estructura de proyecto que separe las credenciales de sandbox de las de producción mediante variables de entorno. Así evitarás el error clásico de desplegar en producción con claves de prueba.

Simulando un flujo de cobro completo con QR desde la API

Vayamos a lo práctico. Supongamos que ya tienes tus credenciales de sandbox y un endpoint preparado para recibir webhooks. Ahora quieres simular el recorrido completo de un cobro. Te describimos el proceso a alto nivel (los detalles de cada endpoint están en la documentación oficial; aquí nos centramos en la lógica para que entiendas qué probar):

Creación del pago y obtención del QR

Realizas una solicitud POST al endpoint de creación de pagos incluyendo el monto, la moneda (PEN), una referencia única que identifique la orden en tu sistema y, opcionalmente, datos adicionales del cliente. En la cabecera debes incluir la autenticación con firma HMAC-SHA256 generada a partir de tu sandbox_secret, así como un idempotency_key para evitar duplicados no deseados.

La respuesta te devolverá un objeto JSON con la propiedad qr_code y la propiedad checkout_url. El qr_code contiene la representación del código QR dinámico que puedes renderizar en tu frontend (por ejemplo, usando una librería QR en JavaScript) para que el cliente escanee con Yape, Plin o cualquier billetera interoperable. El checkout_url es un enlace que puedes mostrar si prefieres una redirección a una página que también muestra el QR e instrucciones de pago.

Simulación de la confirmación del pago

En un entorno real, cuando el cliente escanea y paga, la entidad financiera confirma la transacción a través de la CCE (Cámara de Compensación Electrónica) y TAYPI notifica a tu backend mediante un webhook. Dentro del sandbox, puedes provocar esa confirmación desde el panel de control: ubicas el pago que acabas de crear y seleccionas la opción “Marcar como pagado” o similar.

Al hacerlo, el sistema envía una solicitud POST a tu URL de webhook con un cuerpo que contiene los detalles del pago (ID, monto, estado, referencia, etc.) y una cabecera con la firma HMAC. En ese momento, tu backend debe:

1. Extraer la firma del encabezado.
2. Calcular la firma esperada utilizando tu sandbox_secret y el cuerpo de la solicitud.
3. Comparar ambas firmas. Si coinciden, la notificación es auténtica y puedes actualizar el estado de la orden en tu base de datos.

Todo este mecanismo te permite probar la integridad de los datos y la autenticidad del mensaje, algo que será obligatorio en producción. Si quieres conocer más sobre las notificaciones en tiempo real, te sugerimos leer nuestra guía completa de webhooks de pagos en tiempo real.

Casos de prueba recomendados

Para sacar el máximo provecho del sandbox, te recomendamos cubrir al menos los siguientes escenarios:

Escenario de prueba	¿Qué validas?	¿Cómo simularlo?
Pago exitoso	La generación del QR, el webhook de confirmación y la actualización de la orden.	Crear pago con monto válido y marcarlo como pagado desde el panel.
Error de firma en webhook	Que tu sistema rechace notificaciones con firma inválida y no procese pagos fraudulentos.	Modificar manualmente el cuerpo o la firma antes de que llegue a tu backend, o enviar una solicitud sin firma.
Idempotencia	Que enviar la misma solicitud dos veces no cree dos pagos.	Crear un pago con idempotency_key X, luego repetir la misma petición con la misma clave; la respuesta debe ser idéntica y no se debe generar un nuevo QR.
QR expirado	Que tu sistema maneje correctamente la imposibilidad de pagar un QR después de 15 minutos.	Crear un pago, esperar más de 15 minutos (o usar una herramienta para adelantar la hora del sistema si el sandbox lo permite) y luego intentar confirmar el pago.
Monto mínimo (S/ 1.00) y monto con decimales	Que la API acepte correctamente montos pequeños y el redondeo a dos decimales.	Crear pagos por exactamente S/ 1.00 y por montos como S/ 15.99, verificando el monto devuelto.

Esta tabla te da una pauta para estructurar tus casos de prueba más allá del “happy path”. La idea es que cuando llegues a producción ya hayas enfrentado —y solucionado— los posibles puntos de fricción.

Pruebas avanzadas: idempotencia, manejo de errores y la verificación HMAC-SHA256

Una vez que domines el flujo básico, es hora de profundizar en aspectos que marcan la diferencia entre una integración sólida y una propensa a fallos en el mundo real.

Idempotencia: por qué es crítica y cómo probarla

En un sistema de pagos, los fallos de red pueden hacer que una solicitud llegue al servidor de TAYPI pero que la respuesta nunca regrese a tu backend. Si tu sistema reintenta automáticamente sin un mecanismo de idempotencia, podrías terminar generando dos cobros por una misma intención. La clave de idempotencia es un identificador único que envías en cada petición de creación de pago. Si envías una segunda petición con la misma clave, TAYPI reconoce que ya procesó esa solicitud y te devuelve el resultado original, sin crear un nuevo QR.

En el sandbox puedes probar esto fácilmente: genera un UUID o un identificador único por intento de pago, incorpóralo en el encabezado Idempotency-Key y crea un pago. Luego, vuelve a enviar una solicitud idéntica (mismo monto, misma referencia) con la misma clave. Deberías recibir exactamente la misma respuesta que la primera vez, incluyendo el mismo identificador de pago. Si en lugar de eso obtienes un nuevo QR, algo no está funcionando y debes revisar la implementación.

Verificación de firma HMAC-SHA256: tu seguro contra manipulaciones

Cada webhook que envía TAYPI, tanto en sandbox como en producción, incluye un encabezado con una firma generada usando tu clave secreta y el cuerpo del mensaje. Tu backend debe recalcular esa firma y compararla para asegurarse de que el mensaje no fue alterado en tránsito y que realmente proviene de TAYPI.

La fórmula general es: HMAC-SHA256(cuerpo_del_webhook, clave_secreta) y luego una codificación en hexadecimal. En el sandbox puedes hacer pruebas variando ligeramente el cuerpo o la firma para asegurarte de que tu sistema rechaza correctamente las notificaciones que no cuadran. Este control es obligatorio si quieres cumplir con buenas prácticas de seguridad, y se alinea con las exigencias de PLAFT y las normativas locales supervisadas por la SBS y la UIF-Perú. Para ahondar en este mecanismo, te recomendamos nuestro artículo HMAC-SHA256 explicado: cómo proteger tus transacciones.

Manejo de errores y tiempo de expiración del QR

Durante las pruebas en el sandbox, no solo te preocupes por los escenarios felices. Simula también qué sucede si el endpoint de pagos no responde a tiempo (timeout), o si tu sistema recibe una notificación de un estado desconocido. Aunque en el sandbox no puedas provocar todos los errores del mundo real, sí puedes desconectar tu túnel de pruebas para ver cómo reacciona tu lógica de reintentos y cómo registras los fallos.

Además, recuerda que el QR dinámico expira en 15 minutos. En el sandbox, comprueba que pasado ese lapso el pago ya no pueda confirmarse (el webhook no debería llegar, o tu sistema debería marcar la orden como expirada). Esto es especialmente relevante en comercios con alta demanda, donde un cliente podría intentar pagar con un QR caduco y frustrarse si no manejas bien el caso.

Del sandbox a producción: checklist antes de lanzar

Cuando todas tus pruebas en el sandbox son exitosas, es tentador pasar de inmediato a producción. Sin embargo, te recomendamos seguir una checklist para minimizar sorpresas:

1. Revisa que uses exclusivamente las claves de producción: cambia las variables de entorno de sandbox_api_key a live_api_key. Un error aquí puede hacer que los cobros queden en un limbo.
2. Actualiza la URL del webhook: si en sandbox usaste un dominio de pruebas (como un túnel ngrok), asegúrate de configurar la URL de producción con HTTPS y un certificado válido. La seguridad de los datos de tus clientes depende de ello.
3. Verifica la lógica de idempotencia: en producción, cualquier reintento accidental podría generar problemas. Asegúrate de que cada petición nueva lleve un idempotency_key único y de que tu sistema se comporte correctamente ante respuestas repetidas.
4. Comprueba la gestión de inventario o stock: una vez que el webhook confirma el pago, tu backend debe descontar el producto o registrar la orden como pagada. Simula en sandbox una confirmación y verifica que todo el flujo interno se complete.
5. Prueba con montos reales pequeños: aunque ya estés en producción, puedes hacer una primera transacción real por un monto simbólico (por ejemplo, S/ 1.00, que es el monto mínimo por transacción) para verificar que la liquidación T+1 funcione y que los fondos lleguen a tu cuenta bancaria CCI. Así confirmas de extremo a extremo toda la cadena, incluida la conciliación.
6. Revisa los costos: en producción cada cobro confirmado tiene una comisión del 2.50% + S/ 0.20 + IGV. Asegúrate de que tu modelo de negocio ya tiene esto internalizado y que no te llevas una sorpresa con la liquidación. Puedes conocer más sobre los precios de TAYPI.

Cumplir con esta checklist te dará la tranquilidad de que tu integración está realmente lista para recibir pagos de clientes reales con Yape, Plin o cualquier billetera interoperable, sin contratiempos.

Preguntas frecuentes sobre el sandbox de pagos QR

¿El sandbox permite probar el pago en un clic con Yape On File?

Sí, en el entorno de pruebas puedes simular la afiliación de un cliente y los cobros posteriores. Sin embargo, como el pago en un clic con Yape ya es una función operativa en producción, te recomendamos coordinar la activación con el equipo de TAYPI una vez que hayas validado los flujos básicos en sandbox. Recuerda que en el entorno real el cliente autoriza la afiliación en su propia app Yape bajo estrictos mecanismos de seguridad, por lo que la simulación se enfoca en la lógica de cobro y no en la verificación biométrica.

¿Necesito una cuenta de banco real para usar el sandbox?

No. El sandbox está diseñado para que puedas probar la integración sin haber completado aún la verificación KYB ni haber registrado una cuenta bancaria. Las claves de pruebas se generan al momento del registro y te permiten simular todo el flujo. Cuando estés listo para producción, sí necesitarás completar el Nivel 2 (KYB verificado) y proporcionar tu CCI para recibir las liquidaciones.

¿Puedo probar los plugins de WooCommerce o WHMCS en el sandbox?

Sí. Los plugins y módulos oficiales de TAYPI incluyen opciones de configuración para entorno sandbox. Solo debes ingresar las credenciales de pruebas en lugar de las de producción. De esta manera puedes verificar que la pasarela se integra correctamente con tu tienda sin afectar las órdenes reales. Además, los SDKs de PHP, JavaScript/TypeScript y .NET también soportan sandbox.

¿El sandbox simula fallos de pago como saldo insuficiente?

El entorno de sandbox te permite controlar el estado final del pago (generalmente “exitoso” desde el panel). Para probar escenarios de fallo, puedes simular errores de red o manipular las respuestas a los webhooks, lo que te da un buen panorama sobre cómo se comporta tu sistema ante eventos inesperados. Si en el futuro necesitas probar los reintentos parciales del cobro inteligente de Yape On File, el sandbox te permite reproducir la lógica, aunque la causa exacta del fallo real (como saldo insuficiente) solo se produce con pagos vivos.

¿Cuánto tiempo puedo usar el sandbox?

No hay un límite de tiempo. Puedes usar el entorno de pruebas todo el tiempo que necesites durante el desarrollo y la puesta a punto. Eso sí, recuerda que las credenciales de sandbox son independientes de las de producción, por lo que una vez que migres, deberás cambiar las claves en tu aplicación.

Conclusión

El sandbox pagos QR pruebas es mucho más que un simple entorno de desarrollo: es tu laboratorio personal para construir una integración de pagos sólida, segura y lista para el exigente ecosistema del e-commerce peruano. Al simular cada paso —desde la generación del QR interoperable hasta la validación de la firma HMAC-SHA256 y el control de idempotencia— reduces drásticamente la posibilidad de errores en producción y mejoras la experiencia de tus clientes.

Ya sea que estés implementando una tienda en línea, un sistema de suscripciones o un marketplace, dedicar tiempo a probar en el sandbox de TAYPI te ahorrará dolores de cabeza y te permitirá lanzar con confianza. Aprovecha las herramientas disponibles: explora la documentación para developers, profundiza en la seguridad de TAYPI y no olvides revisar los artículos de nuestro blog, como cómo integrar pagos QR en tu tienda online y por qué los pagos QR están reemplazando al POS tradicional. Con el sandbox, tienes todo lo necesario para dominar los pagos con QR antes de procesar tu primer sol real.

---

¿Listo para empezar? Crea tu cuenta gratis en TAYPI y activa tu sandbox en minutos. Sin costo de instalación, sin mensualidades, y con la seguridad de estar operando sobre la infraestructura de pagos interoperables del BCRP.