Saltar a contenido

Cómo usar el entorno Sandbox de 4Geeks Payments para pruebas

🤖 Explicar con IA

Desplegar la lógica de pagos directamente en un entorno de producción conlleva riesgos significativos, como cargos accidentales a tarjetas de crédito reales y reportes financieros desordenados. El Sandbox de 4Geeks Payments proporciona una réplica segura y aislada de su entorno de producción. Permite a los desarrolladores y gerentes de finanzas simular transacciones, probar integraciones de API y validar flujos de trabajo de facturación complejos utilizando 4Geeks Payments sin mover dinero real.

Este artículo lo guía a través del acceso al sandbox, la obtención de credenciales de prueba y la realización de transacciones simuladas para asegurar que su sistema esté listo para el lanzamiento.

Requisitos previos

Antes de comenzar las pruebas, asegúrese de tener lo siguiente:

  • Acceso a la 4Geeks Console: Debe tener una cuenta activa con acceso a la 4Geeks Console.
  • Permisos: Necesita permisos de nivel “Desarrollador” o “Administrador” para ver las claves de API y cambiar los modos de entorno.
  • Integración de pagos: Idealmente, debería tener una comprensión básica de cómo se conecta su aplicación a 4Geeks Payments, o estar listo para probar transacciones manuales a través del panel.

Instrucciones paso a paso

Siga estos pasos para configurar y utilizar el entorno sandbox de manera efectiva.

Paso 1: Cambiar al modo de prueba

La plataforma 4Geeks separa los datos “Reales” (Live) de los datos de “Prueba” (Test) para evitar accidentes.

  1. Inicie sesión en la 4Geeks Console.
  2. Navegue al módulo Payments en la barra lateral izquierda.
  3. Localice el Interruptor de Entorno en la barra de navegación superior (que generalmente muestra “Live”).
  4. Haga clic en el interruptor para cambiarlo a “Test” o “Sandbox”.
  5. El banner del panel debería cambiar de color (típicamente a naranja o azul) para indicar que ahora está trabajando con datos ficticios.

Paso 2: Obtener credenciales de API de prueba

Sus claves de API reales no funcionarán en el sandbox. Debe generar credenciales específicas para las pruebas.

  1. Mientras esté en el Modo de Prueba, vaya a Settings > API & Webhooks.
  2. Localice las secciones Public Key y Secret Key.
  3. Haga clic en Reveal Keys para ver sus credenciales de prueba. Estas claves suelen empezar con un prefijo como pk_test_ o sk_test_.
  4. Copie estas claves y actualice su entorno de desarrollo local o la configuración del servidor de pruebas.

Nota: Nunca use sus claves reales (pk_live_...) en su código de prueba, ya que esto resultará en una autenticación fallida o transacciones reales no intencionadas.

Paso 3: Simular una transacción

Puede verificar su integración procesando un pago con números de tarjeta de prueba.

  1. Inicie un flujo de pago a través de su aplicación (por ejemplo, una página de pago o un enlace de pago de factura).
  2. Cuando se le soliciten los detalles del pago, use uno de los Números de Tarjeta de Prueba de 4Geeks. (Consulte la documentación de 4Geeks Payments para obtener una lista completa).
    • Visa (Exitosa): 4242 4242 4242 4242
    • Mastercard (Rechazada): 5100 0000 0000 0051
    • Fecha de vencimiento: Cualquier fecha futura.
    • CVC: Cualquier número de 3 dígitos (por ejemplo, 123).
  3. Complete el proceso de pago.

Paso 4: Verificar los resultados

  1. Regrese a la 4Geeks Console (asegúrese de seguir en el Modo de Prueba).
  2. Haga clic en la pestaña Transactions.
  3. Debería ver su pago simulado más reciente en la lista.
  4. Haga clic en el ID de la transacción para ver los detalles, incluyendo el estado (Exitoso/Fallido), los registros de respuesta de la API y los metadatos asociados.

Casos de uso comunes

Escenario 1: Probar el Dunning automático para suscripciones

Si usa 4Geeks Payments para gestionar la facturación recurrente, puede simular un pago fallido para probar su lógica de dunning (reintentos).

  • Acción: Cree una suscripción en el sandbox usando un número de tarjeta de prueba específico de “Rechazo”.
  • Validación: Verifique que el sistema intente reintentar el pago de acuerdo con su programa y que se active la notificación por correo electrónico correcta de “Pago Fallido” al correo electrónico del cliente ficticio.

Escenario 2: Validar desembolsos de nómina

Para las empresas que utilizan 4Geeks Payroll, el sandbox es esencial para probar los pagos a contratistas.

  • Acción: Configure un perfil de contratista de prueba e inicie un pago masivo utilizando fondos de prueba en su billetera virtual.
  • Validación: Verifique que el estado de la transacción se actualice a “Pagado” en la consola y que se active el webhook correspondiente a su sistema de backend, confirmando que la integración gestiona los pagos correctamente.

Solución de problemas

Problema 1: Error “Clave de API inválida”

  • Causa: Es probable que esté usando sus claves de API reales mientras su aplicación apunta al endpoint de Sandbox, o viceversa.
  • Solución: Verifique su archivo .env o la configuración. Asegúrese de que sus claves coincidan con el entorno (claves de Test para Sandbox, claves de Live para Producción).

Problema 2: Las transacciones no aparecen en el Panel

  • Causa: La vista de la consola podría estar configurada en el modo incorrecto.
  • Solución: Mire el interruptor en el encabezado de la 4Geeks Console. Si procesó una transaccion de prueba, asegúrese de que el interruptor esté en Test. Las transacciones reales nunca aparecerán en la vista de prueba.

Problema 3: Los webhooks no se activan

  • Causa: Los endpoints de los webhooks deben configurarse por separado para los entornos Live y Test.
  • Solución: Vaya a Settings > API & Webhooks mientras esté en el Modo de Prueba. Asegúrese de que la URL de su servidor de pruebas esté agregada como un endpoint de webhook y que los eventos “subscription_created” o “payment_succeeded” estén habilitados.

Conclusión

Utilizar el Sandbox de 4Geeks Payments es un paso crítico en el ciclo de vida del desarrollo. Asegura que su lógica de facturación, desde la facturación de pacientes en 4Geeks Health hasta la gestión de suscripciones en 4Geeks Assets, funcione impecablemente antes de interactuar con clientes reales. Al aislar las pruebas en este entorno, protege sus flujos de ingresos y mantiene los datos limpios para informes precisos.

Para escenarios de prueba más avanzados, como la simulación de 3D Secure o la gestión de disputas, consulte los Recursos adicionales a continuación.

Recursos adicionales