Insta Comecio: Pago a Cuotas

SETUP

01

Disponibilidad & Credenciales

Antes de iniciar, el frontend consulta qué sucursales (Locations) están activas y verifica la salud de los proveedores.

                        Health Check
                        READ-ONLY
                    
GET/api/bnpl/health
# Retorna estado de gateways
{
  "cashea": "UP",
  "lysto": "UP",
  "db": "CONNECTED"
}
                

INIT

02

Creación de Transacción

Punto de entrada único. El backend detecta el provider y aplica la estrategia de validación correspondiente.

✅ Valida monto mínimo/máximo
✅ Encripta datos sensibles
✅ Asigna UUID interno único

                        Payload Switcher
                        REQUIRED
                    
POST/api/bnpl/transactions
# Ejemplo Cashea
{
  "provider": "cashea",
  "amount": 100.50,
  "locationId": "uuid-de-la-caja",
  "invoiceId": "FAC-001",
  "identificationNumber": "V123456",
  "employeeId": null
}

# Respuesta Cashea
{
  "success": true,
  "transactionId": "b8e7de01-b303-4b04-afc9-bd4ae0d9b5c0", // Usar en todos los pasos siguientes (UUID en v2 | numérico en v1)"message": ""
}


# Ejemplo Lysto (Diferente Payload)
{
  "provider": "lysto",
  "description": "Nike Air Jordan",
  "amount": 250.00
}
                

LOGIC

03

Verificación y Cálculo

El sistema consulta el scoring del usuario en tiempo real (<200ms).

Lógica Backend: Calcula el Down Payment (Inicial) y los fees bancarios antes de confirmar.

                        Risk Engine
                        PROCESSING
                    
POST/transactions/:id/verify
# Body — Flujo QR (sin userCode) o Código de seguridad (con userCode)
{
  "provider": "cashea",
  "userCode": "123456"// Opcional — solo flujo offline
}

# Respuesta Cashea
{
  "success": true,
  "downPayment": 40.00, // Monto a cobrar en tienda"financedAmount": 60.00, // Monto financiado por Cashea"fees": 0,
  "downPaymentStatus": "PENDING", // PENDING = cobrar en tienda → llamar a confirm | PAID = ya pagó en la app → NO llamar a confirm"description": ""
}
                

COMMIT

04

Confirmación (Cierre)

Solo ejecutar si downPaymentStatus = PENDING.
Registra el cobro de la inicial en tienda y cierra la orden.
Si downPaymentStatus = PAID, el cliente ya pagó desde la App Cashea — no llamar a este endpoint.

                        Finalize
                        CRITICAL
                    
POST/transactions/:id/confirm
# Body para Lysto
{
  "invoiceNum": "FISCAL-999",
  "paymentHandle": "LY-TOKEN-XYZ",
  "branchId": "BR-001"
}

# 200 OK -> Venta Cerrada

AUDIT

05

Detalle de Orden (Cashea)

Consulta el estado real de una orden directamente desde Cashea. Útil para contingencias, auditoría o verificar el estado actual sin depender del registro local.

✅ Estado real en tiempo real
✅ Detalle de cuotas e inicial
✅ Preparado para múltiples proveedores

                        Order Details
                        PASS-THROUGH
                    
GET/bnpl/transactions/:id/details?provider=cashea
# Respuesta
{
  "uuid": "b8e7de01-...",
  "status": "IN_PROGRESS", // OPEN | IN_PROGRESS | CLOSED | PENDING | CANCELLED"amount": 100.50,
  "downPaymentAmount": 40.00,
  "financedAmount": 60.50,
  "invoiceId": "FAC-001",
  "paymentDetails": {
    "user": { "fullName": "Juan Doe", "identificationNumber": "V123456" },
    "installments": [...]
  }
}
                

LOG

📋

Historial de Cambios

v2.0.0 — 29/04/2026
- Migración a Cashea API v2
- transactionId devuelve UUID en v2 (numérico en v1) — el comercio siempre usa el mismo campo
- Nuevo campo downPaymentStatus (PENDING | PAID) en verify
- Nuevo endpoint: GET /bnpl/transactions/:id/details
- Soporte para pago de inicial desde la App Cashea
v1.1.0 — 19/09/2025
- Endpoint para simulación de escaneo de QR en ambiente de pruebas
v1.0.0 — 17/09/2025
- Documentación inicial