Ciclo de vida transaccional
El servicio cr-transactions opera el ciclo de vida completo: crear, preautorizar, capturar, cancelar y reversar. Precondición para crear una transacción: usuario ACTIVE con cuenta afiliada.
CREATED ──authorize──▶ AUTHORIZED ──capture──▶ APPROVED ──void──▶ PENDING (reverso async)
│ │
│ └── timeout ──▶ AUTO-CANCELLED (EventBridge)
│
└── cancel ──▶ CANCELLED / DISMISSED
1. Nueva transacción
POST v2/credits/transactions/
Authorization: <token>
Content-Type: application/json
{
"merchant": "miComercio",
"clientCode": "USR-001",
"amount": 1000.00,
"currency": "GTQ",
"channel": "wa",
"externalId": "ORDER-001",
"processorAmount": { "bam": 1000.00 },
"userInfo": { "phone": "50212345678", "email": "usuario@ejemplo.com" },
"emailTo": ["usuario@ejemplo.com"],
"postback": {
"approved": "https://tercero.com/ok",
"denied": "https://tercero.com/denied",
"cancel": "https://tercero.com/cancel",
"error": "https://tercero.com/error"
},
"customerKeys": { "orderRef": "X-123" }
}
Requeridos: merchant (clientSlug), clientCode (id del usuario en el comercio), amount.
Opcionales: currency, channel, externalId, processorAmount, userInfo, emailTo, postback, customerKeys, createdBy, ads.
{
"success": true,
"data": {
"uid": "txn-abc123",
"reference": "REF-000123",
"URL": "https://webview.migopayments.com/?orderId=txn-abc123"
}
}
URL es el link de la webview para completar el flujo (selección de cuenta + OTP). Errores: 2003 (monto inválido / processorAmount inválido), 2004 (usuario bloqueado), 6001 (usuario de crédito inválido).
2. Autorización (preautorización del monto)
Reserva el crédito con la entidad financiera (no ejecuta el cobro). Precondición: transacción en CREATED / USED / CHALLENGE.
POST v2/credits/transactions/{trxUID}/authorize
Authorization: <token>
Content-Type: application/json
{
"account": "ACC-123456",
"processor": "bam",
"code": "123456"
}
Requeridos: account (cuenta a usar), processor (banco), code (OTP).
{
"success": true,
"data": {
"uid": "txn-abc123",
"status": "AUTHORIZED",
"channel": "wa",
"createdAt": "2026-01-01T10:00:00.000Z",
"paymentData": {}
}
}
Al autorizar, Migo arranca un temporizador: si no capturas dentro de la ventana configurada, la transacción se cancela sola y la reserva se libera. Ver Cancelación automática.
Errores: 2000 (no encontrada / estado inválido), 2004 (usuario bloqueado u OTP inválido — "OTP validation faild"), 2002 (cuenta no encontrada). Si la cuenta está en default, no hay saldo suficiente o el banco rechaza, la transacción se marca DENIED.
3. Captura (cobro efectivo)
Confirma el monto preautorizado y ejecuta el cobro. Precondición: transacción en AUTHORIZED.
POST v2/credits/transactions/{trxUID}/capture
Authorization: <token>
Content-Type: application/json
{
"captureAmount": 1000.00
}
captureAmount es opcional; si se omite (o es inválido) se captura el total autorizado.
{
"success": true,
"data": {
"uid": "txn-abc123",
"status": "APPROVED",
"total": 1000.0,
"bank": "Banco X"
}
}
Errores: 2000 (no encontrada / no está en AUTHORIZED), 2001 (config de cliente), 2002 (config de banco o cuenta), 2003 ("Bank no response").
4. Cancelación y void (reverso)
| Operación | Precondición | Estado resultante | Efecto |
|---|---|---|---|
| Cancel | CREATED / USED / AUTHORIZED / EXPIRED | CANCELLED / DISMISSED | Libera la reserva (antes del cobro) |
| Void | APPROVED / IN_REVIEW / PENDING | PENDING → resuelto por webhook | Solicita reverso del cobro al banco |
Cancelar
DELETE v2/credits/transactions/{trxUID}/cancel
Authorization: <token>
{
"success": true,
"data": {
"uid": "txn-abc123",
"status": "CANCELLED",
"message": "Transaction dismissed"
}
}
Errores: 2001 (no encontrada), 2000 ("The transaction is not in cancel status").
Void (reverso)
DELETE v2/credits/transactions/{trxUID}/void
Authorization: <token>
{
"success": true,
"data": {
"uid": "txn-abc123",
"status": "PENDING",
"message": "The request was sent to the financial institution, the result will be notified in the webhook."
}
}
El void es asíncrono: el banco confirma el reverso por webhook. Errores: 2001 (no encontrada), 2000 (no es reversable / el banco no tiene reverso / error al reversar).
5. Cancelación automática
Si autorizas una transacción pero no la capturas dentro de una ventana de tiempo configurada, Migo la cancela por ti y libera la reserva. Esto evita que un monto quede apartado indefinidamente.
No tienes que implementar nada: es automático. La transacción simplemente pasa a CANCELLED, igual que si la hubieras cancelado a mano. Si quieres enterarte, ese cambio también se refleja en los avisos que recibes (ver Webhooks y notificaciones).