Guía de integración: Recepción de pagos en tienda (Cash-In)

Esta guía está dirigida a comercios que desean integrar el registro de pagos en tienda física con la API de Atrato.

Requisitos previos

Cuenta de partner en Atrato con acceso al dashboard
Funcionalidad Recepción de pagos en sucursal habilitada para tu comercio
Tipo de cuenta: Administrador, Gerente o Desarrollador

Flujo de integración

sequenceDiagram
    participant Comercio
    participant API
    Comercio->>API: POST /login (username, password)
    API-->>Comercio: token
    Comercio->>API: GET /search?reference=XXX (x-auth-token)
    API-->>Comercio: userName, userId, credits[]
    Comercio->>API: GET /available-stores (x-auth-token)
    API-->>Comercio: stores[]
    Comercio->>API: POST /register-payment (userId, payments) (x-auth-token)
    API-->>Comercio: globalPaymentId, status, totalAmount

Paso 1: Autenticación

Obtén un token con tus credenciales del dashboard partner:

POST /api/v4/integration/login
Content-Type: application/json

{
  "username": "tu_usuario",
  "password": "tu_contraseña"
}

Respuesta: { "token": "..." }

Guarda el token y envíalo en el header x-auth-token en todas las peticiones siguientes. El token expira en 5 minutos.

Paso 2: Buscar al cliente

Antes de registrar un pago, identifica al cliente por su referencia CIE (inicia con la letra U) o por el ID de solicitud (applicationId). Se requiere al menos uno de los dos parámetros.

GET /api/v4/integration/cash-in/search?reference=U123456789
x-auth-token: <tu_token>

O por applicationId:

GET /api/v4/integration/cash-in/search?applicationId=12345
x-auth-token: <tu_token>

Respuesta: userName, userId y lista de credits con: creditId, debtToDate, settleAmount, merchantName, installmentAmount. Usa userId y creditId/amount en el registro de pago.

Paso 3: Obtener sucursales

Obtén las sucursales autorizadas para tu cuenta. Necesitarás el storeId para registrar el pago.

GET /api/v4/integration/cash-in/available-stores
x-auth-token: <tu_token>

Respuesta: stores: [{ storeId, name }]. Usa el storeId de la sucursal donde se recibe el pago.

Paso 4: Registrar el pago

Con el userId (paso 2), storeId (paso 3) y los creditId/amount (paso 2):

POST /api/v4/integration/cash-in/register-payment
x-auth-token: <tu_token>
Content-Type: application/json

{
  "userId": 12345,
  "storeId": 1,
  "payments": [
    { "creditId": 100, "amount": 500.00 },
    { "creditId": 101, "amount": 300.00 }
  ]
}

Respuesta 201: globalPaymentId, status, totalAmount, appliedPayments, message.

Validaciones importantes al registrar

Monto máximo: El amount de cada crédito no puede ser mayor al settleAmount (monto a liquidar) devuelto en /search. Si excede, recibirás: "El monto a pagar no puede ser mayor al monto a liquidar".
Créditos válidos: Los creditId deben pertenecer al usuario y estar activos.
Sucursal: El storeId es requerido y debe ser una de las sucursales autorizadas (obtener de /available-stores).
Horario: Algunas sucursales tienen horario de registro configurado; fuera de ese horario el pago será rechazado.

Consultar pagos

Listar pagos con filtros

Parámetros opcionales: paymentId, minDate, maxDate, minAmount, maxAmount, stores (IDs separados por coma), status, page, limit, orderBy (paymentDate|paymentAmount|paymentId), orderDirection (ASC|DESC).

GET /api/v4/integration/cash-in/payments?minDate=2025-01-01&maxDate=2025-01-31&status=success&page=0&limit=10
x-auth-token: <tu_token>

Respuesta: totalPayments, totalAmount, data: [{ globalPaymentId, status, totalAmount, paymentDate, storeName }].

Detalle de un pago

GET /api/v4/integration/cash-in/payment-details/999
x-auth-token: <tu_token>

Respuesta: globalPaymentId, status, totalAmount, paymentDate, appliedPayments, storeName, storeId, receiptUrl (si aplica).

Estados del pago

Estado	Descripción
`success`	Pago conciliado correctamente
`pending_conciliation`	Pago registrado, pendiente de conciliación
`cancelled`	Pago cancelado

Códigos de error

400 - Datos incorrectos

Causa	Mensaje / Detalle
userId faltante o inválido	`details: "userId es requerido"`
payments faltante o vacío	`details: "Debe incluir al menos un pago"`
Monto o creditId inválido	`details: "payments[].amount debe ser un monto mayor a cero"`
Sucursal no autorizada	`message: "La sucursal X no está autorizada o no existe."`
Monto mayor al permitido	`message: "El monto a pagar no puede ser mayor al monto a liquidar"`
Usuario sin créditos activos	`message: "No se encontraron créditos activos para este usuario"`
Créditos no pertenecen al usuario	`message: "No puede pagar créditos que no correspondan al usuario"`

401 - No autorizado

Credenciales inválidas, token expirado o sin permiso para usar la integración.

404 - No encontrado

Usuario sin créditos: "No se encontraron créditos activos para este usuario"
Resumen de créditos: "No se encontró el resumen de los créditos para este usuario"

500 - Error de servidor

Error general: "Error al registrar el pago."
Fuera de horario: "El horario de registro de pagos de la sucursal es de 09:00 a 18:00 Hora de México"