Sandbox de pagos
sandbox imita los proveedores de pago (Akua: PSE y tarjeta; Crezcamos: Bre-B, cuentas y transferencias) porque no ofrecen un ambiente de pruebas que llegue hasta un banco simulado. No mueve dinero, no llama a Akua ni a bancos reales y no es un sandbox oficial.
Qué simula
| Capacidad | Comportamiento |
|---|---|
| Token | POST /oauth/token con credenciales locales. |
| Bancos | GET /api/banks?country=COL&rail_id=PSE: catálogo de prueba (incluye el banco 1007 que el motor puede forzar). |
| Intención | POST /v1/payments/intents → 202 con payment_id, rail.payment_link y transaction. Con Idempotency-Key: misma respuesta para el mismo cuerpo, 409 si cambia. |
| Consultas | GET /v1/payments/{id} y GET /v1/transactions/{id}. |
| Comercios | POST/PUT/GET /v1/merchants (y alta automática en la primera intención). |
| Banco simulado | Página con el aviso "SIMULACIÓN — SIN DINERO REAL" y las decisiones de abajo. |
| Webhooks | Registro (/v1/webhooks) y entrega firmada (akua-wh-*, HMAC-SHA256) con reintentos persistentes. |
Métodos de pago simulados
El sandbox imita a Akua (PSE y tarjeta) y a Crezcamos (Bre-B, cuentas, transferencias) con las mismas rutas y formas que usa el engine. Para usarlo basta cambiar la configuración: AKUA__BASEURL / AKUA__AUDIENCE y CREZCAMOSAPI__BASEURL.
| Método | Entrada simulada | Cómo se resuelve |
|---|---|---|
| PSE | POST /v1/payments/intents | Banco simulado en /bank/{token}; webhook firmado akua-wh-*. |
| Tarjeta | POST /v1/links → url a /card/{token} | Tarjetas de prueba (abajo); mismos webhooks payment.purchase.*. |
| Bre-B | POST /payments-links/v1/qr/generate (también GET {id} y update) | qrCode es la URL /qr/{id} (escaneable); el engine consulta qrStatus (HABILITADO, PAGADO, CANCELADO, EXPIRADO). No hay webhook: el engine consulta. |
| Cuentas Crezcamos | GET /payments-savings/v1/savings/accounts/{n}/exist | Termina en 0000 → no existe (código 26); en 9999 → false; otra → true. |
| Transferencias | POST /payments-transfers/v1/transfers/accounts | Idempotente por transactionId; devuelve reference. |
El login de Crezcamos (/payments-authentication/v1/login) acepta cualquier usuario y contraseña; no valida x-hash ni descifra el password. Los contratos de Crezcamos y del link de tarjeta se deducen del cliente del engine, no de documentación del proveedor.
Tarjetas de prueba
| Número | Resultado |
|---|---|
4242 4242 4242 4242 | Aprobada |
4000 0000 0000 0002 | Rechazada (USER_DECLINED) |
4000 0000 0000 9995 | Fondos insuficientes (INSUFFICIENT_FUNDS) |
4000 0000 0000 0119 | Error técnico (PROVIDER_UNAVAILABLE) |
Cualquier otro número se rechaza en la página; no se guardan datos de tarjeta.
Controlar el resultado
Orden de precedencia: regla explícita → monto → modo. Es una convención local del sandbox, no del proveedor.
| Los últimos 3 dígitos del monto (COP) | Resultado automático (a los SANDBOX_AUTO_RESOLVE_SECONDS, 3 por defecto) |
|---|---|
001 | Aprobado (QR: PAGADO) |
005 | Rechazado, fondos insuficientes (QR: CANCELADO) |
051 | Rechazado (QR: CANCELADO) |
097 | Expirado |
098 | Fallido, proveedor no disponible (QR: EXPIRADO) |
099 | Se queda pendiente |
| otro | Interactivo; con SANDBOX_MODE=auto se aprueba solo |
En transferencias, un monto que termine en 300, 303, 307, 309, 310, 313, 314, 315, 329 o 332 responde con ese código de error (p. ej. 20315 → fondos insuficientes).
Con SANDBOX_ADMIN_KEY definida se habilita /__sandbox/* (header X-Admin-Key):
| Ruta | Uso |
|---|---|
POST /__sandbox/rules | {merchant_id, order_ref, scenario, uses}. PSE: order_ref = id del pedido; tarjeta: id del link; QR: merchant_id = crezcamos-qr y order_ref = monto (25000). Dos reglas vivas para la misma referencia → 409. |
GET /__sandbox/rules, DELETE /__sandbox/rules/{id} | Listar y borrar. |
GET /__sandbox/payments?merchant_id=&method= | Pagos PSE y tarjeta con estado y escenario. |
POST /__sandbox/payments/{id}/resolve | {scenario}: resuelve un pago pendiente sin navegador. |
POST /__sandbox/deliveries/{messageId}/replay | Reenvía un webhook con el mismo akua-wh-id. |
DELETE /__sandbox/reset?merchant_id= | Borra pagos, sesiones, entregas y reglas de ese comercio. |
Escenarios: Approve, Reject, InsufficientFunds, ProviderUnavailable, Expired, Pending, Interactive.
Decisiones del banco simulado (PSE)
| Botón | Resultado | Evento | status_detail |
|---|---|---|---|
| Aprobar | Aprobado | payment.purchase.succeeded | SUCCESS |
| Rechazar | Rechazado | payment.purchase.rejected | USER_DECLINED |
| Fondos insuficientes | Rechazado | payment.purchase.rejected | INSUFFICIENT_FUNDS (valor local) |
| Proveedor no disponible | Fallido | payment.purchase.failed | PROVIDER_UNAVAILABLE |
| Volver sin resolver | Sigue pendiente | — | PENDING_CUSTOMER |
| (sin acción) | Vence a los 30 min | payment.purchase.rejected | EXPIRED (valor local) |
Un pago nace con un evento payment.purchase.pending. La sesión del banco dura 15 min: pasada esa hora el enlace responde 410 con una página explicativa y el pago no se cancela. El vencimiento del pago (por defecto 30 min, configurable; 0 lo desactiva) lo cierra como rechazado con motivo EXPIRED.
Diferencias con Akua
- El token, los clientes, los comercios y el catálogo son locales.
- El payload del webhook es el mínimo de la guía de Akua (
type,data.payment_id,data.transaction_id); el motivo de un rechazo se obtiene consultandoGET /v1/transactions/{id}. INSUFFICIENT_FUNDSyEXPIREDson valores del simulador, no documentados por Akua para PSE.- La proyección del estado agregado del pago es provisional.
- No implementa tarjetas (
/v1/links).
El detalle contractual (qué está documentado, qué es decisión local y qué falta confirmar) vive en sandbox/docs/contract-matrix.md y known-differences.md del repositorio.