Probar tu integración en Sandbox

Sandbox es el entorno de pruebas de PAGOS360. Funciona igual que producción, pero sin mover dinero real, y te permite simular pagos exitosos, rechazados y pendientes. En esta guía vas a ver qué host usar para cada API, qué datos de prueba tenés disponibles, cómo simular un pago con QR, cómo depurar webhooks y qué revisar antes de salir a producción.

Entornos y hosts

PAGOS360 tiene tres APIs, y cada una usa su propio host en cada entorno:

Más información en Entornos y URLs, Autorización, QR Interoperable y Alias de pago.

Datos de prueba

En Sandbox podés simular distintos resultados según los datos que uses en el Checkout.

Tarjetas

Tenés tarjetas de prueba de crédito y débito (VISA y MASTERCARD) y para Tarjeta Agro, con resultado exitoso, rechazado o pendiente. Por ejemplo:

En todas: CVV 123 y vencimiento 11/ + un año mayor al actual. Nombre, DNI, email y teléfono no se validan.

Tenés la lista completa en Tarjetas.

Cuentas bancarias

Para probar DEBIN (débito inmediato: el pagador aprueba el cobro desde su banco) y adhesiones a débito en cuenta, tenés alias y CBU de prueba (la CBU es la Clave Bancaria Uniforme, que identifica una cuenta bancaria en Argentina). Cada uno da un resultado exitoso, expirado o con error. Los encontrás en Cuentas.

Qué escenarios probar

Como mínimo, recorré estos casos y verificá que tu sistema quede en el estado correcto:

• Pago exitoso: la solicitud pasa a paid y recibís el webhook payment_request / paid.

• Pago rechazado: recibís el webhook payment_request / rejected. La solicitud sigue en pending, porque el pagador puede reintentar con otro medio de pago.

• Pago pendiente: el pagador vuelve por back_url_pending (si la enviaste) y el pago todavía no está confirmado. Entregá el producto recién cuando recibas paid.

• Pagador que abandona el Checkout: cerrá la pestaña sin pagar. Tu sistema tiene que enterarse del resultado sin depender de la redirección.

Simular un pago con QR

En Sandbox no hay una billetera real que escanee tus códigos QR. Para probar el flujo completo, usá el servicio de prueba que marca un QR como pagado. Está disponible solo en Sandbox:

qr_id es el ID único del QR que generaste: el ID de tu cuenta, un guion y tu identificador (hasta 25 caracteres en total). Ver cómo se arma en QR dinámico.

Respuesta exitosa:

Si el pago no se puede simular (por ejemplo, porque el QR no existe o ya fue pagado), recibís:

Después de simular el pago, verificá que tu integración reciba la notificación y que el estado del QR cambie a pagado. Más información en Pagar QR (Solo para homologación).

Depurar webhooks

Para recibir webhooks, PAGOS360 necesita llegar a tu URL desde internet. Mientras desarrollás, tenés dos opciones:

• webhook.site: te da una URL pública donde ves cada POST que llega, con sus headers y su body. Te sirve para ver qué envía PAGOS360 antes de escribir código.

• ngrok: crea un túnel público hacia tu máquina, así el webhook llega directo a tu endpoint local. Por ejemplo, si tu aplicación escucha en el puerto 3000:

Configurá como URL del webhook la URL https:// que te muestra ngrok, más la ruta de tu endpoint (por ejemplo https://<subdominio>.ngrok-free.app/webhooks/pagos360).

Cada webhook llega como un POST con un body JSON como este:

Al depurar, tené en cuenta:

• Solo se consideran exitosas las respuestas 200, 201, 202, 203, 204 y 208. Cualquier otra, incluidas las 3xx, cuenta como error y el evento se reintenta.

• Si tu endpoint tarda demasiado en responder, el envío se corta por tiempo de espera y se reintenta. Respondé primero y procesá después.

• Si al configurar el webhook agregaste headers (Authorization, Proxy-Authorization o X-*), llegan en cada envío. Usalos para verificar que la notificación viene de PAGOS360.

• Si ves el mismo evento más de una vez, es esperable: los reintentos pueden duplicar envíos.

Más información en Configuración y Depuración de webhooks.

Checklist antes de salir a producción

Entorno y credenciales

• Cambiaste el host de Sandbox por el de producción en cada API que usás (API PAGOS360, QR Interoperable y Alias de pago).

• Generaste una API Key de producción desde Integraciones en tu cuenta de producción y la cargaste en la configuración.

• La API Key está solo en tu servidor: no está en el frontend, en una app móvil ni en un repositorio.

• Quitaste del código cualquier llamada a servicios de prueba, como POST /pay-qr/{qr_id}.

Webhooks

• Configuraste los webhooks en tu cuenta de producción, con los eventos que necesitás. La configuración de Sandbox no se copia.

• La URL del webhook es https://, es pública y no redirige: los webhooks no siguen redirecciones.

• Tu endpoint responde un 2xx enseguida y procesa el evento después (por ejemplo, con una cola).

• El procesamiento es idempotente: si llega dos veces el mismo evento (misma combinación de entity_name, type, entity_id y payload.request_result_id), la segunda vez no hace nada.

• Antes de marcar un pedido como pagado, consultás la solicitud con GET /payment-request/{id} y verificás state e importe.

• Si agregaste un header de autenticación al webhook, tu endpoint lo valida.

Datos y seguimiento

• Guardás el id de cada solicitud de pago junto a tu pedido.

• Enviás un external_reference propio (número de pedido o de factura) para poder conciliar.

• Tu sistema no depende de las URLs de retorno (back_url_*) para confirmar pagos: el pagador puede cerrar la pestaña antes de volver.

• Manejás los estados expired, reverted y refunded, no solo paid.

• Registrás en tus logs las respuestas de error de la API (400, 401, 409) para poder diagnosticarlas.