Saltar al contenido principal

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​

CapacidadComportamiento
TokenPOST /oauth/token con credenciales locales.
BancosGET /api/banks?country=COL&rail_id=PSE: catálogo de prueba (incluye el banco 1007 que el motor puede forzar).
IntenciónPOST /v1/payments/intents → 202 con payment_id, rail.payment_link y transaction. Con Idempotency-Key: misma respuesta para el mismo cuerpo, 409 si cambia.
ConsultasGET /v1/payments/{id} y GET /v1/transactions/{id}.
ComerciosPOST/PUT/GET /v1/merchants (y alta automática en la primera intención).
Banco simuladoPágina con el aviso "SIMULACIÓN — SIN DINERO REAL" y las decisiones de abajo.
WebhooksRegistro (/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étodoEntrada simuladaCómo se resuelve
PSEPOST /v1/payments/intentsBanco simulado en /bank/{token}; webhook firmado akua-wh-*.
TarjetaPOST /v1/links → url a /card/{token}Tarjetas de prueba (abajo); mismos webhooks payment.purchase.*.
Bre-BPOST /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 CrezcamosGET /payments-savings/v1/savings/accounts/{n}/existTermina en 0000 → no existe (código 26); en 9999 → false; otra → true.
TransferenciasPOST /payments-transfers/v1/transfers/accountsIdempotente 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úmeroResultado
4242 4242 4242 4242Aprobada
4000 0000 0000 0002Rechazada (USER_DECLINED)
4000 0000 0000 9995Fondos insuficientes (INSUFFICIENT_FUNDS)
4000 0000 0000 0119Error 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)
001Aprobado (QR: PAGADO)
005Rechazado, fondos insuficientes (QR: CANCELADO)
051Rechazado (QR: CANCELADO)
097Expirado
098Fallido, proveedor no disponible (QR: EXPIRADO)
099Se queda pendiente
otroInteractivo; 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):

RutaUso
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}/replayReenví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ónResultadoEventostatus_detail
AprobarAprobadopayment.purchase.succeededSUCCESS
RechazarRechazadopayment.purchase.rejectedUSER_DECLINED
Fondos insuficientesRechazadopayment.purchase.rejectedINSUFFICIENT_FUNDS (valor local)
Proveedor no disponibleFallidopayment.purchase.failedPROVIDER_UNAVAILABLE
Volver sin resolverSigue pendiente—PENDING_CUSTOMER
(sin acción)Vence a los 30 minpayment.purchase.rejectedEXPIRED (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 consultando GET /v1/transactions/{id}.
  • INSUFFICIENT_FUNDS y EXPIRED son 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.