Skip to main content
Migo Docs

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
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" }
}

Required: merchant (clientSlug), clientCode (the user's id at the merchant), amount. Optional: currency, channel, externalId, processorAmount, userInfo, emailTo, postback, customerKeys, createdBy, ads.

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

Required: account (account to use), processor (bank), code (OTP).

Successful response
{
"success": true,
"data": {
"uid": "txn-abc123",
"status": "AUTHORIZED",
"channel": "wa",
"createdAt": "2026-01-01T10:00:00.000Z",
"paymentData": {}
}
}
Side effect: auto-cancellation

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

captureAmount is optional; if omitted (or invalid) the full authorized amount is captured.

Successful response
{
"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)​

OperationPreconditionResulting stateEffect
CancelCREATED / USED / AUTHORIZED / EXPIREDCANCELLED / DISMISSEDReleases the reservation (before charge)
VoidAPPROVED / IN_REVIEW / PENDINGPENDING β†’ resolved by webhookRequests a charge reversal from the bank

Cancel​

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