Afiliación bancaria y OTP
La afiliación asocia al usuario con una entidad financiera. Es un flujo parcialmente asíncrono: el banco confirma por webhook tras el OTP.
POST /users/{userUID}/banks/{bankSlug}/affiliations (inicia; el banco envía OTP)
↓
POST /users/{userUID}/banks/{bankSlug}/affiliations/otp (se valida el OTP con el banco)
↓
[ASYNC] Banco → POST /webhooks/merchants/{m}/users/{u}/banks/{b}/affiliations
(el banco confirma; el usuario pasa a ACTIVE si fue autorizado)
bankSlug es el banco configurado en MongoDB (por ejemplo bam, ge).
Iniciar afiliación
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
}
}
Requeridos: merchant, clientCode, phone. Opcionales: 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"
}
}
Errores: 2001 (config de cliente/banco no encontrada), 6001 (usuario no existe), 6010 (faltan datos), 6011 (email inválido), 6012 (teléfono inválido), 6013 (teléfono 2 inválido), 6000 (ya afiliado a ese banco), 5000 (el banco no soporta afiliación).
Validar OTP de afiliación
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"
}
}
Si el OTP no es válido, la respuesta tiene success: true con message: "OTP validation error". La validación final del banco llega por webhook.
Errores: 2001, 6001.
Webhook de respuesta del banco
El banco confirma la afiliación de forma asíncrona. Este endpoint no pasa por el 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. Si es authorized, Migo crea/enlaza la cuenta y el usuario pasa a ACTIVE. En caso de error se usa el objeto error: { code, description, message, name }.
Una vez que el usuario esté ACTIVE, puedes consultar su cuenta o crear una transacción.