República Dominicana — recetas de integración
República Dominicana tiene dos rails: los pagos con tarjeta se procesan a través del acquirer Azul dentro del webview hosteado por Migo, y Banco Popular (bancoPopular) permite cobrar contra una cuenta bancaria enviando al cliente a autorizar el débito en su banca en línea. Es el primer rail de pago alternativo cableado para do.
Cómo elegir. Un cobro creado para
country: "DO"sin más es un link de pago con tarjeta vía Azul. Para cobrar contra cuenta de Banco Popular se procesa el pago explícitamente conprocessor: "bancoPopular"sobre la transacción ya creada.
Setup
Los links de pago usan el token de comercio de larga duración de 64 caracteres enviado como Authorization: <token> (sin prefijo de esquema). No se requiere ida y vuelta de login.
export MIGO_BASE="https://sb-mw.migopayments.com"
export MIGO_TOKEN="<your-64-char-merchant-token>" # 64 hex chars
export MIGO_USER_ID="+1809000000"
Link de pago enrutado a Azul (azul)
País: República Dominicana · Tipo: Webview hosteado (Migo) → tarjeta procesada por Azul ·
payment-intentsprevio: No · Payload de respuesta:url(la URL del webview).
Prerrequisitos
clientConfig.processorsincluyeazul.- Tu
clientConfig.callbackes alcanzable para webhooks. - Opcional: configura
successUrl/failureUrlpara que el cliente sea devuelto a tu dominio después de autorizar en el webview.
Paso 1 — Crear un link de pago
curl -X POST "$MIGO_BASE/transactions" \
-H "Authorization: $MIGO_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"amount": 50000,
"currency": "DOP",
"country": "DO",
"channel": "wa",
"userId": "'"$MIGO_USER_ID"'",
"externalId": "your-internal-order-id",
"customKeys": { "orderId": "your-internal-order-id" }
}'
El flujo de creación POST /transactions (contrato request/response) está documentado en Crear un link de pago. Envía la URL de checkout retornada al cliente a través del canal que coincida con tu valor channel (WhatsApp, email, SMS, app o web).
Paso 2 — El cliente autoriza en el webview
El cliente abre data.url, escribe su tarjeta, y Migo enruta la autorización a Azul. Azul realiza:
- Autenticación 3-D Secure cuando la marca de tarjeta lo requiere.
- Cuotas opcionales (selector
Cuotasdentro del webview). - Tokenización (el cliente puede guardar la tarjeta para cobros futuros).
Luego el cliente es redirigido a tu successUrl o failureUrl.
Paso 3 — Webhook
Una vez que Azul confirma la autorización, Migo emite el Merchant Generic Callback a la URL de callback configurada en tu clientConfig.callback. El payload exacto (URL, body, headers) es lo que defina tu plantilla clientConfig.callback.data — no hay un envoltorio fijo generado por la plataforma. Un body típico se ve así:
{
"uid": "trx_…",
"externalId": "your-internal-order-id",
"status": "approved",
"processor": "azul",
"reference": "MIGO-…",
"amount": 50000,
"currency": "DOP",
"country": "DO"
}
Hoy no existe un firmador de webhook saliente en el código — la plataforma no emite actualmente un header X-Migo-Signature.
Refund / reversión
Azul soporta ambos. Revert y refund viven bajo /pay, con el mismo token de comercio que el resto de las llamadas:
# Reversión el mismo día (antes de la liquidación)
curl -X POST "$MIGO_BASE/pay/revert" \
-H "Authorization: Bearer $MIGO_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "transactionUid": "'"$UID"'", "processor": "azul" }'
# Reembolso después de la liquidación
curl -X POST "$MIGO_BASE/pay/refund" \
-H "Authorization: Bearer $MIGO_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "transactionUid": "'"$UID"'", "processor": "azul", "amount": 50000 }'
Datos de sandbox
| Tarjeta | Comportamiento |
|---|---|
4035 8740 0000 0029 | Aprueba |
4035 8740 0000 0011 | Rechaza (card_declined) |
4035 8740 0000 1111 | Dispara challenge 3DS — pasa success / fail en el paso del challenge |
Usa cualquier fecha de expiración futura y cualquier CVV de 3 dígitos.
Errores comunes
El flujo de creación de link de pago valida los params requeridos y retorna un 400 en caso de falla. Expón las razones de decline desde el estado del callback en lugar de sintetizar códigos de error.
| Cuándo | Cómo reaccionar |
|---|---|
country faltante o distinto de DO | Envía country: "DO" al momento de crear. |
currency no soportada | Usa DOP (peso dominicano). |
Azul rechazó el cobro (card_declined, insufficient_funds, expired_card) | Expón la razón del decline al cliente; ofrece una tarjeta diferente. |
| Azul tuvo timeout | Reintenta el flujo de creación; reconcilia vía el callback. |
Banco Popular (bancoPopular)
País: República Dominicana · Tipo: Banca en línea del banco (dominio de Banco Popular) ·
payment-intentsprevio: No · Payload de respuesta:url.
Prerrequisitos
clientConfig.processorsincluyebancoPopular, con las credenciales del convenio dadas de alta por Operaciones de Migo.- Puedes redirigir al cliente a un dominio externo desde tu checkout.
- Tu
clientConfig.callbackes alcanzable para webhooks: el resultado llega por callback, no por el retorno del cliente. - La transacción está en
DOPoUSD. En cualquier otra moneda el método no se ofrece. Si el cliente paga desde una cuenta en otra moneda, el banco convierte con la tasa del día.
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": "bancoPopular" }'
No lleva data: el rail no le pide ningún dato adicional al cliente.
Respuesta esperada — el enlace está en data.data:
{
"success": true,
"message": "Success",
"data": {
"uid": "trx_…",
"type": "url",
"data": "https://mw.migopayments.com/configs/redirect/banco-popular/trx_…",
"cancelAt": 900
}
}
Redirige al cliente a data.data. El host cambia por ambiente (sb-mw.migopayments.com en sandbox): usa siempre el enlace que devuelve la API.
A diferencia de otros botones hosteados, data.data no apunta al banco: apunta a una página de Migo que reenvía al cliente a Banco Popular. El banco exige un POST de formulario firmado en lugar de aceptar una URL, y esa página es la que hace la conversión sin exponer la firma. Trátala como cualquier otro redirect: mándale al cliente y no intentes reconstruirla ni postear por tu cuenta.
cancelAt son los segundos hasta que el enlace expira (900 s por defecto).
Entrega del estado
El cliente autoriza el débito en la banca en línea de Banco Popular. El estado siempre llega por el callback del comercio, disparado por la notificación firmada que el banco envía a Migo.
Banco Popular devuelve al cliente a Migo por una redirección independiente de la notificación del pago. Esa redirección no confirma nada: puede llegar antes que la notificación, o no llegar nunca si el cliente cierra la pestaña. No marques la orden como pagada al recibir al cliente de vuelta — espera el callback.
Pagos empresariales: el estado pending
Una cuenta empresarial puede exigir segunda firma. En ese caso el banco notifica que el pago quedó en espera de aprobación y la transacción se queda en pending:
- No se dispara el callback todavía. Solo
approvedydeniedcierran la transacción. - Puede resolverse mucho después, cuando el aprobador confirma en su banca en línea. La ventana por defecto es de 24 horas; pasada esa ventana la transacción expira.
- Si consultas el estado,
pendingsignifica «esperando al aprobador», no «fallido». No la reintentes: un reintento no consulta el pago que está esperando, abre uno nuevo. Consulta el estado conGET $MIGO_BASE/api/v1/integrations/transactions/{uid}.
Diseña tu integración para que una orden de República Dominicana pueda quedar abierta horas y cerrarse por callback.
Refund / reversión
No soportados. Este rail no expone reembolso ni reversión por API. Cualquier devolución al cliente se gestiona directamente con Banco Popular, fuera de la plataforma.
Datos de sandbox
- El rail apunta al ambiente de pruebas de Banco Popular; se requieren credenciales de prueba de banca en línea, que provee Operaciones de Migo.
- Prueba al menos un pago aprobado, uno rechazado y uno que quede en
pending.
Errores comunes
| Cuándo | Cómo reaccionar |
|---|---|
400 con Processor not allowed | La transacción no está en DOP ni USD, o el método no está habilitado para tu cliente. Crea la transacción en DOP o USD; si ya lo está, pide la habilitación a Operaciones de Migo. |
404 con Transaction not found | El uid no existe o no pertenece a tu comercio. Verifica el uid que te devolvió la creación. |
403 al procesar el pago | El token de autorización falta o no es válido. No tiene que ver con el estado de la transacción. |
El enlace responde 409 al abrirlo | La transacción ya no es pagable (se pagó, se procesó o expiró). Crea una nueva. |
400 con el rechazo del banco | El banco rechazó el pedido. Expón el motivo y ofrece otro método. |
| El cliente volvió pero no llegó el callback | Comportamiento esperado si el banco aún no notificó. Consulta el estado; no marques la orden como pagada. |
Quedó en pending y no avanza | Es un pago empresarial esperando al aprobador. Espera el callback hasta el vencimiento de la ventana. |
Otras superficies de webview
- Apple Pay / Google Pay no están cableados para
dohoy. Donde se soporta en otros mercados, Apple Pay se procesa a través del flujo de tarjeta de link de pago / webview hosteado. - Fallback de Cybersource no está habilitado para
dohoy; si lo necesitas, contacta a Operaciones de Migo.
Verificación
- Token de comercio enviado como
Authorization: <token>;POST /transactionsprobado concountry: "DO",currency: "DOP". - El cliente llegó al webview y autorizó con la tarjeta de sandbox.
- Challenge 3DS probado al menos una vez, con la tarjeta 3DS de sandbox.
- Callback recibido con
processor: "azul"para al menos un evento aprobado y uno rechazado. - Rutas de refund y reversión probadas en sandbox (solo aplican a
azul). bancoPopular: pago procesado, cliente redirigido al enlace de Migo y callback recibido para un aprobado y un rechazado.bancoPopular: probado al menos un pago que queda enpendingy se resuelve por callback más tarde.bancoPopular: transacciones creadas enDOPoUSD; en otra moneda el método no aparece.- Credenciales de producción rotadas por separado de las de sandbox.
Relacionado
- Recetas de integración — matriz país × rail
- Métodos de pago disponibles — catálogo de rails filtrado por país
- Procesar pago — el cuerpo unificado y la forma de respuesta por
data.type - Crear un link de pago — el contrato de creación que usa esta receta
- Merchant Generic Callback — la entrega del estado