Visión general
Esta página explica, sin tecnicismos, cómo encaja Créditos Core y te lleva por el flujo completo —de crear un usuario a cobrarle— con un ejemplo real en cada paso.
Cómo encaja
Hay tres actores: tu aplicación, Migo y la entidad financiera. Tú solo hablas con Migo; Migo habla con el banco por ti.
Tu aplicación
│ creas usuario, afilias, creas y autorizas la transacción
▼
Migo Créditos Core ───────────► Entidad financiera (BAM, GE, ...)
▲ │ envía el OTP al usuario final
│ te avisa por webhook │
└────────────── ◄──────────────────┘
- Tú envías peticiones a la API de Migo (crear usuario, afiliar, transaccionar).
- El banco envía OTP al teléfono del usuario y, cuando algo se confirma de su lado, Migo te avisa por webhook (por ejemplo, cuando la afiliación queda aprobada).
El flujo completo de un vistazo
1. Crear usuario POST v2/credits/users ──► userUID
│
▼
2. Afiliar a un banco POST v2/credits/users/{uid}/banks/{slug}/affiliations (el banco envía OTP)
│
▼
3. Validar OTP de afiliación POST .../affiliations/otp (el banco confirma por webhook)
│
▼ [usuario ACTIVE]
4. Crear transacción POST v2/credits/transactions ──► trxUID + URL de pago
│
▼
5. Autorizar (preautorizar) POST v2/credits/transactions/{trxUID}/authorize (reserva el monto)
│
▼
6. Capturar (cobrar) POST v2/credits/transactions/{trxUID}/capture ──► APPROVED
Ejemplo de extremo a extremo
Sigamos a Ana García desde cero hasta el cobro. Todas las peticiones llevan el header Authorization: <token> (ver Autenticación).
1. Creas el usuario. Le das a Migo sus datos básicos; recibes un userUID para identificarlo de aquí en adelante.
{
"firstName": "Ana",
"lastName": "García",
"document": { "type": "DPI", "number": "9988776655443" },
"dateOfBirth": "1992-03-15",
"gender": "female",
"userAddress": { "address": "Zona 1", "department": "Guatemala", "city": "Guatemala" }
}
→ { "success": true, "data": { "userId": "a1b2c3d4-...", "status": "CREATED" } }
2. La afilias a un banco. Indicas el banco en la URL (bam). El banco le envía un OTP al teléfono de Ana.
{ "merchant": "miComercio", "clientCode": "CLIENT-001", "phone": "50212345678" }
→ { "success": true, "data": { "status": "Affiliation requested" } }
3. Validas el OTP que Ana recibió. Poco después, el banco confirma la afiliación con un webhook y el usuario queda ACTIVE y con cuenta de crédito.
{ "merchant": "miComercio", "clientCode": "CLIENT-001", "code": "123456" }
4. Creas la transacción por el monto a financiar. Recibes un trxUID y una URL: el link de pago donde Ana elige su cuenta y confirma con OTP.
{ "merchant": "miComercio", "clientCode": "CLIENT-001", "amount": 250.00, "currency": "GTQ" }
→ { "success": true, "data": { "uid": "txn-abc123", "URL": "https://webview.migopayments.com/?orderId=txn-abc123" } }
5. Autorizas la transacción: el banco reserva el monto (todavía no cobra).
{ "account": "ACC-123456", "processor": "bam", "code": "123456" }
→ { "success": true, "data": { "status": "AUTHORIZED" } }
6. Capturas para ejecutar el cobro. Si no envías monto, se cobra el total autorizado.
{}
→ { "success": true, "data": { "status": "APPROVED", "total": 250.0 } }
Con esto, Ana compró a crédito y el cobro quedó confirmado.
Puedes ejecutar este mismo flujo desde la referencia interactiva (botón "Test Request") o importando la especificación OpenAPI en Postman.
Reglas que aplican siempre
- Toda petición lleva tu token en el header
Authorization. Las únicas excepciones son los webhooks que el banco te envía a ti. Ver Autenticación. - El contrato no cambia al sumar bancos: el banco siempre viaja en la URL (
bankSlug), nunca cambias tu código por una entidad nueva. - Todas las respuestas tienen la misma forma:
{ success: true, data }cuando todo salió bien, o{ success: false, error }cuando algo falló. - Algunos pasos son asíncronos (la afiliación, el reverso y la cancelación por tiempo): la confirmación final llega por webhook, así que no asumas el resultado al instante.
Estados
A medida que avanzas, el usuario y la transacción cambian de estado:
Usuario
CREATED → ACTIVE (cuando el banco confirma la afiliación)
ACTIVE → INACTIVE / BLOCKED (por operación interna o mora)
Transacción
CREATED ──autorizar──▶ AUTHORIZED ──capturar──▶ APPROVED ──void──▶ PENDING (reverso)
│ │
│ └── si no capturas a tiempo ──▶ CANCELLED (automático)
│
└── cancelar ──▶ CANCELLED
Notas de implementación
- Crear usuario es idempotente: si ya existe alguien con el mismo documento, Migo te devuelve ese usuario en vez de duplicarlo.
- No hay un
GETde transacción: el estado lo obtienes en la respuesta de cada operación (y por webhook cuando aplica). - Consulta de cuenta necesita el
banky al menos uno detrxUIDo el documento del usuario.
Siguientes pasos
- Autenticación — el header requerido y el formato universal de respuesta.
- Usuarios y pre-calificados — crear y consultar usuarios.