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", // Obligatorio. Si aún no hay factura, enviar un relleno y actualizar luego (paso 06)"identificationNumber": "12345678", // String solo numérico: sin V/E, guiones ni puntos"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": "12345678" },
    "installments": [...]
  }
}
                

FISCAL

06

Actualizar Factura (Cashea)

Cashea exige invoiceId al crear la orden. Si la factura fiscal aún no existe, se crea con un valor de relleno (ej. "00000000") y se reemplaza aquí por el número fiscal real una vez emitida.

✅ No cambia el estado de la transacción
⚠️ Por normativa, el valor final debe ser el número fiscal real
⚠️ El :id debe ser de la misma versión de Cashea con la que se creó la orden

                        Update Invoice
                        PASS-THROUGH
                    
PATCH/bnpl/transactions/:id/invoice
# Body
{
  "provider": "cashea",
  "invoiceId": "F-2025-000123"// Número fiscal real
}

# Respuesta
{
  "success": true,
  "invoiceId": "F-2025-000123",
  "message": ""
}
                

LOG

📋

Historial de Cambios

v2.1.0 — 30/09/2026
- Nuevo endpoint: PATCH /bnpl/transactions/:id/invoice para actualizar el número de factura en Cashea
- Se aclara que identificationNumber en Cashea es un string solo numérico (ej. "12345678")
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