Saltar al contenido principal
Migo Docs

Colombia — recetas de integración

Los rails cableados en el endpoint /payments de pagos alternativos para Colombia son Nequi (nequi) y GlobalPay PSE (globalPay-PSE).

Setup​

Todas las recetas asumen las variables de abajo. Configúralas en tu shell antes de ejecutar cualquier curl. El host (sb-mw.migopayments.com) y el path (/api/v1/integrations/...) son el sandbox público alcanzable por integradores externos. Las rutas de Pagos Alternativos aceptan el token de comercio de larga duración de 64 caracteres como token Bearer.

export MIGO_BASE="https://sb-mw.migopayments.com"
export MIGO_CLIENT="<your-client-slug>"
export MIGO_TOKEN="<your-64-char-merchant-token>" # 64 hex chars
export MIGO_USER_ID="+57300000000"

export UID=$(
curl -s -X POST "$MIGO_BASE/api/v1/integrations/transactions" \
-H "Authorization: Bearer $MIGO_TOKEN" \
-H "Content-Type: application/json" \
-d "{
\"amount\": 50000,
\"channel\": \"web\",
\"client\": \"$MIGO_CLIENT\",
\"userId\": \"$MIGO_USER_ID\",
\"customKeys\": { \"orderId\": \"recipe-test\" }
}" | jq -r '.data.uid'
)

Inspecciona los paymentMethods retornados para confirmar qué rails tiene habilitados tu cliente (resueltos en runtime desde clientConfig.processors).


Nequi (nequi) — directo​

País: Colombia · Tipo: Push notification a la app Nequi del cliente · payment-intents previo: Opcional (retorna fixture de teléfono en sandbox) · Payload de respuesta: payButton.

Paso A (opcional) — Obtener datos del fixture​

curl -X POST "$MIGO_BASE/api/v1/integrations/transactions/$UID/payment-intents" \
-H "Authorization: Bearer $MIGO_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "processor": "nequi" }'

El handler de payment-intents trata de forma especial a nequi; los integradores en producción típicamente recolectan el teléfono del usuario.

Paso B — Procesar el pago​

curl -X POST "$MIGO_BASE/api/v1/integrations/transactions/$UID/payments" \
-H "Authorization: Bearer $MIGO_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "processor": "nequi", "data": { "phoneNumber": "3001234567" } }'

Respuesta esperada — data.data lleva el paymentRequest.message de Nequi:

{
"success": true,
"message": "Success",
"data": {
"transaction_id": "…",
"type": "payButton",
"data": "<paymentRequest.message>",
"cancelAt": null
}
}

payButton significa que el cliente está autorizando dentro de su app Nequi. No hay un endpoint público GET-by-uid en esta superficie para hacer polling — depende del callback del comercio configurado en clientConfig.callback para el estado (ve Merchant Generic Callback).

Reembolsos: revert de nequi vía POST $MIGO_BASE/revert con body {"transactionUid":"$UID","processor":"nequi"} (esquema JWT-Bearer, separado de esta superficie de token de comercio).


GlobalPay PSE (globalPay-PSE)​

País: Colombia · Tipo: PSE — el cliente es redirigido al portal en línea de su banco · payment-intents previo: Requerido (retorna la lista de bancos) · Payload de respuesta: html.

Paso A — Obtener la lista de bancos​

curl -X POST "$MIGO_BASE/api/v1/integrations/transactions/$UID/payment-intents" \
-H "Authorization: Bearer $MIGO_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "processor": "globalPay-PSE" }'

Respuesta — banks, fisTypes, userTypes y accountTypes se pueblan todos desde la configuración del procesador (processorCfg.extras); los contenidos de abajo son solo ilustrativos:

{
"data": {
"banks": [{ "key": "1007", "value": "Bancolombia" }, …],
"fisTypes": [{ "key": "0", "value": "Natural" }, { "key": "1", "value": "Jurídica" }],
"userTypes": [{ "key": "CC", "value": "Cédula de Ciudadanía" }, …],
"accountTypes": [{ "key": "…", "value": "…" }, …]
}
}

Renderiza selects para bank, fisType, userType y recolecta userName, email, fiscalNumber, installments.

Paso B — Procesar el pago​

curl -X POST "$MIGO_BASE/api/v1/integrations/transactions/$UID/payments" \
-H "Authorization: Bearer $MIGO_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"processor": "globalPay-PSE",
"data": {
"bank": { "key": "1007", "value": "Bancolombia" },
"fisType": { "key": "0", "value": "Natural" },
"userType": { "key": "CC", "value": "Cédula de Ciudadanía" },
"userName": "Test User",
"email": "test@example.com",
"fiscalNumber": "1020304050",
"installments": 1
}
}'

Respuesta — el formulario de auto-submit está en data.html (no data.value):

{
"success": true,
"message": "success",
"data": {
"uid": "trx_…",
"type": "html",
"html": "<form …></form>",
"cancelAt": null
}
}

Inyecta data.html en tu página (se auto-envía al banco). El cliente se autentica dentro del portal de su banco y es devuelto al successUrl / failureUrl del comercio. El estado se entrega vía el callback del comercio (clientConfig.callback).

Tanto revert como refund están soportados vía POST $MIGO_BASE/revert y POST $MIGO_BASE/refund con body {"transactionUid":"$UID","processor":"globalPay-PSE"} (esquema JWT-Bearer).

Datos de sandbox​

  • bank.key = "0" (banco de prueba en QA) siempre aprueba.
  • fiscalNumber = "1234567890" → decline simulado.

Errores comunes a todos los rails​

El middleware de pagos alternativos devuelve códigos de 4 dígitos en error.code, no el catálogo 7xxx del ALI Gateway:

HTTPerror.codeCuándo
4005000Params faltantes/inválidos (amount, channel, client, userId, customKeys, o processor)
400—processor no permitido para este cliente
4005004Config del cliente no encontrada
4002002Falló la creación de la transacción
4002003Monto fuera del rango permitido

Consulta el Catálogo de errores para la descripción completa de cada código.

Entrega del estado​

El estado del pago se entrega a través del callback del comercio que configuras en clientConfig.callback — ve Merchant Generic Callback. No hay un envoltorio de webhook fijo definido por la plataforma.

Verificación​

  • Token de comercio enviado como Authorization: Bearer $MIGO_TOKEN; transacción creada.
  • nequi y globalPay-PSE probados en sandbox.
  • Rutas de refund/void probadas para nequi, globalPay-PSE.
  • Recorrido del cliente cubierto para la forma de respuesta de cada rail (payButton, html).

Relacionado​