Skip to main content
Migo Docs

Overview

This page explains, without jargon, how Credit Core fits together and walks you through the full flow β€”from creating a user to charging themβ€” with a real example at each step.

How it fits together​

There are three actors: your application, Migo and the financial institution. You only talk to Migo; Migo talks to the bank for you.

Your application
β”‚ create user, affiliate, create and authorize the transaction
β–Ό
Migo Credit Core ─────────────► Financial institution (BAM, GE, ...)
β–² β”‚ sends the OTP to the end user
β”‚ notifies you via webhook β”‚
└────────────── β—„β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  • You send requests to Migo's API (create user, affiliate, transact).
  • The bank sends the OTP to the user's phone and, when something is confirmed on its side, Migo notifies you via webhook (for example, when the affiliation is approved).

The full flow at a glance​

1. Create user POST v2/credits/users ──► userUID
β”‚
β–Ό
2. Affiliate to a bank POST v2/credits/users/{uid}/banks/{slug}/affiliations (the bank sends an OTP)
β”‚
β–Ό
3. Validate affiliation OTP POST .../affiliations/otp (the bank confirms via webhook)
β”‚
β–Ό [user ACTIVE]
4. Create transaction POST v2/credits/transactions ──► trxUID + payment URL
β”‚
β–Ό
5. Authorize (preauthorize) POST v2/credits/transactions/{trxUID}/authorize (reserves the amount)
β”‚
β–Ό
6. Capture (charge) POST v2/credits/transactions/{trxUID}/capture ──► APPROVED

End-to-end example​

Let's follow Ana GarcΓ­a from scratch to the charge. Every request carries the Authorization: <token> header (see Authentication).

1. You create the user. You give Migo their basic data; you get back a userUID to identify them from now on.

POST v2/credits/users
{
"firstName": "Ana",
"lastName": "GarcΓ­a",
"document": { "type": "DPI", "number": "9988776655443" },
"dateOfBirth": "1992-03-15",
"gender": "female",
"userAddress": { "address": "Zona 1", "department": "Guatemala", "city": "Guatemala" }
}

β†’ { "success": true, "data": { "userId": "a1b2c3d4-...", "status": "CREATED" } }

2. You affiliate them to a bank. You set the bank in the URL (bam). The bank sends an OTP to Ana's phone.

POST v2/credits/users/{userUID}/banks/bam/affiliations
{ "merchant": "miComercio", "clientCode": "CLIENT-001", "phone": "50212345678" }

β†’ { "success": true, "data": { "status": "Affiliation requested" } }

3. You validate the OTP Ana received. Shortly after, the bank confirms the affiliation with a webhook and the user becomes ACTIVE with a credit account.

POST v2/credits/users/{userUID}/banks/bam/affiliations/otp
{ "merchant": "miComercio", "clientCode": "CLIENT-001", "code": "123456" }

4. You create the transaction for the amount to finance. You get a trxUID and a URL: the payment link where Ana picks her account and confirms with an OTP.

POST v2/credits/transactions
{ "merchant": "miComercio", "clientCode": "CLIENT-001", "amount": 250.00, "currency": "GTQ" }

β†’ { "success": true, "data": { "uid": "txn-abc123", "URL": "https://webview.migopayments.com/?orderId=txn-abc123" } }

5. You authorize the transaction: the bank reserves the amount (no charge yet).

POST v2/credits/transactions/{trxUID}/authorize
{ "account": "ACC-123456", "processor": "bam", "code": "123456" }

β†’ { "success": true, "data": { "status": "AUTHORIZED" } }

6. You capture to run the charge. If you don't send an amount, the full authorized total is charged.

POST v2/credits/transactions/{trxUID}/capture
{}

β†’ { "success": true, "data": { "status": "APPROVED", "total": 250.0 } }

With that, Ana bought on credit and the charge is confirmed.

Try it without writing code

You can run this same flow from the interactive reference ("Test Request" button) or by importing the OpenAPI spec into Postman.

Rules that always apply​

  1. Every request carries your token in the Authorization header. The only exceptions are the webhooks the bank sends to you. See Authentication.
  2. The contract doesn't change when banks are added: the bank always travels in the URL (bankSlug); you never change your code for a new institution.
  3. Every response has the same shape: { success: true, data } when all went well, or { success: false, error } when something failed.
  4. Some steps are asynchronous (affiliation, reversal and timeout cancellation): the final confirmation arrives via webhook, so don't assume the result instantly.

States​

As you progress, the user and the transaction change state:

User

CREATED β†’ ACTIVE (when the bank confirms the affiliation)
ACTIVE β†’ INACTIVE / BLOCKED (by internal operation or delinquency)

Transaction

CREATED ──authorize──▢ AUTHORIZED ──capture──▢ APPROVED ──void──▢ PENDING (reversal)
β”‚ β”‚
β”‚ └── if you don't capture in time ──▢ CANCELLED (automatic)
β”‚
└── cancel ──▢ CANCELLED

Implementation notes​

  • Creating a user is idempotent: if someone with the same document already exists, Migo returns that user instead of duplicating it.
  • There is no transaction GET: you get the state from each operation's response (and via webhook where applicable).
  • Account lookup needs the bank plus at least one of trxUID or the user's document.

Next steps​