Saltar al contenido principal
Migo Docs

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
Body
{
"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.

Respuesta exitosa
{
"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
Body
{
"account": "ACC-123456",
"processor": "bam",
"code": "123456"
}

Requeridos: account (cuenta a usar), processor (banco), code (OTP).

Respuesta exitosa
{
"success": true,
"data": {
"uid": "txn-abc123",
"status": "AUTHORIZED",
"channel": "wa",
"createdAt": "2026-01-01T10:00:00.000Z",
"paymentData": {}
}
}
Efecto secundario: auto-cancelación

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
Body (captureAmount es opcional)
{
"captureAmount": 1000.00
}

captureAmount es opcional; si se omite (o es inválido) se captura el total autorizado.

Respuesta exitosa
{
"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ónPrecondiciónEstado resultanteEfecto
CancelCREATED / USED / AUTHORIZED / EXPIREDCANCELLED / DISMISSEDLibera la reserva (antes del cobro)
VoidAPPROVED / IN_REVIEW / PENDINGPENDING → resuelto por webhookSolicita reverso del cobro al banco

Cancelar​

DELETE v2/credits/transactions/{trxUID}/cancel
Authorization: <token>
Respuesta
{
"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>
Respuesta
{
"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).