Bank affiliation and OTP
Affiliation associates the user with a financial institution. It is a partially asynchronous flow: the bank confirms via webhook after the OTP.
POST /users/{userUID}/banks/{bankSlug}/affiliations (starts; the bank sends an OTP)
β
POST /users/{userUID}/banks/{bankSlug}/affiliations/otp (the OTP is validated with the bank)
β
[ASYNC] Bank β POST /webhooks/merchants/{m}/users/{u}/banks/{b}/affiliations
(the bank confirms; the user becomes ACTIVE if authorized)
bankSlug is the bank configured in MongoDB (for example bam, ge).
Start affiliationβ
POST v2/credits/users/{userUID}/banks/{bankSlug}/affiliations
Authorization: <token>
Content-Type: application/json
{
"merchant": "miComercio",
"clientCode": "CLIENT-001",
"phone": "50212345678",
"phone2": "50287654321",
"email": "usuario@ejemplo.com",
"callbackUrl": "https://tercero.com/callbacks/affiliation",
"additionalBankData": {
"businessName": "Tienda X",
"monthlyIncome": 8000,
"preApprovedAmount": 5000
}
}
Required: merchant, clientCode, phone. Optional: email, phone2, callbackUrl, additionalBankData.
{
"success": true,
"data": {
"userId": "a1b2c3d4-...",
"bank": "Banco X",
"merchant": "Mi Comercio",
"status": "Affiliation requested",
"message": "Request sent to the bank, pending response"
}
}
Errors: 2001 (client/bank config not found), 6001 (user does not exist), 6010 (missing data), 6011 (invalid email), 6012 (invalid phone), 6013 (invalid phone2), 6000 (already affiliated to that bank), 5000 (the bank does not support affiliation).
Validate affiliation OTPβ
POST v2/credits/users/{userUID}/banks/{bankSlug}/affiliations/otp
Authorization: <token>
Content-Type: application/json
{
"merchant": "miComercio",
"clientCode": "CLIENT-001",
"code": "123456"
}
{
"success": true,
"data": {
"uid": "a1b2c3d4-...",
"bank": "Banco X",
"merchant": "Mi Comercio",
"message": "OTP validated sucessfully"
}
}
If the OTP is not valid, the response has success: true with message: "OTP validation error". The bank's final validation arrives via webhook.
Errors: 2001, 6001.
Bank response webhookβ
The bank confirms the affiliation asynchronously. This endpoint does not go through the TOKEN Authorizer.
POST v2/credits/webhooks/merchants/{merchant}/users/{user}/banks/{bank}/affiliations
Content-Type: application/json
{
"status": "authorized",
"account": "ACC-001",
"approvedAmount": 5000,
"balance": 5000,
"currency": "GTQ",
"bankData": { "pin": "****", "productId": "P1", "offerId": "O1" }
}
status β authorized | not_authorized | error | missing_data | pending. If it is authorized, Migo creates/links the account and the user becomes ACTIVE. On error, the error: { code, description, message, name } object is used.
Once the user is ACTIVE, you can query its account or create a transaction.