Transaction lifecycle
The cr-transactions service runs the full lifecycle: create, preauthorize, capture, cancel and void. Precondition to create a transaction: an ACTIVE user with an affiliated account.
CREATED ββauthorizeβββΆ AUTHORIZED ββcaptureβββΆ APPROVED ββvoidβββΆ PENDING (async reversal)
β β
β βββ timeout βββΆ AUTO-CANCELLED (EventBridge)
β
βββ cancel βββΆ CANCELLED / DISMISSED
1. New transactionβ
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" }
}
Required: merchant (clientSlug), clientCode (the user's id at the merchant), amount.
Optional: 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 is the webview link to complete the flow (account selection + OTP). Errors: 2003 (invalid amount / invalid processorAmount), 2004 (blocked user), 6001 (invalid credit user).
2. Authorization (amount preauthorization)β
Reserves the credit with the financial institution (does not execute the charge). Precondition: transaction in CREATED / USED / CHALLENGE.
POST v2/credits/transactions/{trxUID}/authorize
Authorization: <token>
Content-Type: application/json
{
"account": "ACC-123456",
"processor": "bam",
"code": "123456"
}
Required: account (account to use), processor (bank), code (OTP).
{
"success": true,
"data": {
"uid": "txn-abc123",
"status": "AUTHORIZED",
"channel": "wa",
"createdAt": "2026-01-01T10:00:00.000Z",
"paymentData": {}
}
}
On authorization, Migo starts a timer: if you don't capture within the configured window, the transaction cancels itself and the reservation is released. See Automatic cancellation.
Errors: 2000 (not found / invalid state), 2004 (blocked user or invalid OTP β "OTP validation faild"), 2002 (account not found). If the account is in default, there is not enough balance or the bank rejects, the transaction is marked DENIED.
3. Capture (actual charge)β
Confirms the preauthorized amount and executes the charge. Precondition: transaction in AUTHORIZED.
POST v2/credits/transactions/{trxUID}/capture
Authorization: <token>
Content-Type: application/json
{
"captureAmount": 1000.00
}
captureAmount is optional; if omitted (or invalid) the full authorized amount is captured.
{
"success": true,
"data": {
"uid": "txn-abc123",
"status": "APPROVED",
"total": 1000.0,
"bank": "Banco X"
}
}
Errors: 2000 (not found / not in AUTHORIZED), 2001 (client config), 2002 (bank or account config), 2003 ("Bank no response").
4. Cancellation and void (reversal)β
| Operation | Precondition | Resulting state | Effect |
|---|---|---|---|
| Cancel | CREATED / USED / AUTHORIZED / EXPIRED | CANCELLED / DISMISSED | Releases the reservation (before charge) |
| Void | APPROVED / IN_REVIEW / PENDING | PENDING β resolved by webhook | Requests a charge reversal from the bank |
Cancelβ
DELETE v2/credits/transactions/{trxUID}/cancel
Authorization: <token>
{
"success": true,
"data": {
"uid": "txn-abc123",
"status": "CANCELLED",
"message": "Transaction dismissed"
}
}
Errors: 2001 (not found), 2000 ("The transaction is not in cancel status").
Void (reversal)β
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."
}
}
Void is asynchronous: the bank confirms the reversal via webhook. Errors: 2001 (not found), 2000 (not reversible / the bank has no reversal / reversal error).
5. Automatic cancellationβ
If you authorize a transaction but don't capture it within a configured time window, Migo cancels it for you and releases the reservation. This prevents an amount from staying held indefinitely.
You don't have to implement anything: it is automatic. The transaction simply moves to CANCELLED, just as if you had cancelled it by hand. If you want to be notified, that change is also reflected in the notices you receive (see Webhooks and notifications).