Payment Lifecycle

Every money movement in Migo passes through a state machine. The actual status values differ per surface, so this page describes the two real status sets separately. For reconciliation, always read the concrete status value returned by the API you call — never assume one surface's values appear on the other.

Two distinct status sets — don't mix them

The card program (wallet) surface uses the CardTransfersStatus set (including liquidated, reversed). The card-acceptance surface uses a different TransactionStatus set (including used, authorized, refunded, expired). A card charge will never return liquidated, and a card-program transfer will never return used. Confirm which surface you integrate against before writing reconciliation logic.

Card program (wallet) statuses

The card program (wallet) surface uses the CardTransfersStatus set. The conceptual states below map to its real values as shown.

Conceptual state	Real CardTransfersStatus value	Meaning	Terminal?
initiated	created	Request accepted, processing started	No
in progress	in_progress	Being processed	No
authorized	approved	Approved	No
declined	denied	Refused	Yes
settled	liquidated	Funds moved — merchant is paid	No (can still be reversed)
reversed	reversed	Reversed after settlement	Yes

note

created, approved, denied, in_progress, liquidated, and reversed are the values the card-program (card-transfer) flow actually sets. processed, refunded, and cancelled are defined in the CardTransfersStatus set but are not produced by the current flow, so do not build reconciliation logic that waits for them.

There are no pending_3ds, partial_refunded, chargeback, chargeback_won, or chargeback_lost states on this surface.

Card program state diagram

Using the real CardTransfersStatus values. Only two transition rules are enforced; everything else is permissive:

• A transfer may move to approved only from created or approved.
• A transfer may move to reversed only from liquidated.

                ┌───────────┐
                │  created  │
                └─────┬─────┘
                      │
          ┌───────────┼───────────┐
          ▼           ▼           ▼
     ┌────────┐  ┌───────────┐  ┌──────────┐
     │ denied │  │in_progress│─►│ approved │
     └────────┘  └───────────┘  └────┬─────┘
                                     │ funds settle
                                     ▼
                                ┌────────────┐
                                │ liquidated │──► reversed
                                └────────────┘

Time to settlement

An approved transfer typically reaches liquidated the next business day; non-business days and high-volume days can delay it by up to 48 h. Settlement timing follows Guatemala business days. Confirm the exact daily cutoff that applies to your account with your Migo contact, and reconcile by reading the concrete status value rather than assuming a fixed delay.

Card-acceptance transaction statuses

The card-acceptance surface uses a separate TransactionStatus set. It is larger than the card-program set and uses different spellings and values:

created, used, in progress, approved, denied, authorized, reversed, refunded, cancelled, expired, pending, challenge, and blocked.

Different surface, different values

A card charge on this surface never returns liquidated — that value belongs only to the card program (wallet) statuses above. Likewise, values such as used, authorized, refunded, and expired do not appear on the card-program surface. Always read the concrete status value returned by the endpoint you called.

Webhook events per transition

caution

The platform does not emit a per-transition catalog of payment events. The only lifecycle-related event name defined in code is transfer.status.updated; outbound delivery is driven by the merchant's own subscription template, and there is no platform-added eventType envelope. There are no payment.*, settlement.*, or refund.* event names. Do not build flows that key off invented event names — read the concrete status value instead.

There are no chargeback states or chargeback events in the platform today; do not build flows that depend on them.

One-step vs two-step

One-step transactions authorize and complete the charge in a single call (the default for retail).

Two-step transactions stop at the approved state, then capture or release in a separate call. These capture and release flows live on the Middleware (migo-api), not the Wallet Gateway:

• Capture: POST {mw base}/capture/{trxUid}
• Release (cancel): POST {mw base}/cancel/{trxUid} (named cancel, not void)

Both take the transaction's trxUid. See the Middleware reference.