Saltar al contenido principal
Migo Docs

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.

POST v2/credits/users
{
"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.

POST v2/credits/users/{userUID}/banks/bam/affiliations
{ "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.

POST v2/credits/users/{userUID}/banks/bam/affiliations/otp
{ "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.

POST v2/credits/transactions
{ "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).

POST v2/credits/transactions/{trxUID}/authorize
{ "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.

POST v2/credits/transactions/{trxUID}/capture
{}

→ { "success": true, "data": { "status": "APPROVED", "total": 250.0 } }

Con esto, Ana compró a crédito y el cobro quedó confirmado.

Pruébalo sin escribir código

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​

  1. 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.
  2. El contrato no cambia al sumar bancos: el banco siempre viaja en la URL (bankSlug), nunca cambias tu código por una entidad nueva.
  3. Todas las respuestas tienen la misma forma: { success: true, data } cuando todo salió bien, o { success: false, error } cuando algo falló.
  4. 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 GET de transacción: el estado lo obtienes en la respuesta de cada operación (y por webhook cuando aplica).
  • Consulta de cuenta necesita el bank y al menos uno de trxUID o el documento del usuario.

Siguientes pasos​