Saltar al contenido principal
Migo Docs

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 con processor: "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"

País: República Dominicana · Tipo: Webview hosteado (Migo) → tarjeta procesada por Azul · payment-intents previo: No · Payload de respuesta: url (la URL del webview).

Prerrequisitos​

  • clientConfig.processors incluye azul.
  • Tu clientConfig.callback es alcanzable para webhooks.
  • Opcional: configura successUrl / failureUrl para que el cliente sea devuelto a tu dominio después de autorizar en el webview.
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 Cuotas dentro 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"
}
Header de firma

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​

TarjetaComportamiento
4035 8740 0000 0029Aprueba
4035 8740 0000 0011Rechaza (card_declined)
4035 8740 0000 1111Dispara 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ándoCómo reaccionar
country faltante o distinto de DOEnvía country: "DO" al momento de crear.
currency no soportadaUsa 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 timeoutReintenta el flujo de creación; reconcilia vía el callback.

País: República Dominicana · Tipo: Banca en línea del banco (dominio de Banco Popular) · payment-intents previo: No · Payload de respuesta: url.

Prerrequisitos​

  • clientConfig.processors incluye bancoPopular, 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.callback es alcanzable para webhooks: el resultado llega por callback, no por el retorno del cliente.
  • La transacción está en DOP o USD. 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.

El enlace es de Migo, no del banco

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.

Que el cliente vuelva no significa que pagó

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 approved y denied cierran 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, pending significa «esperando al aprobador», no «fallido». No la reintentes: un reintento no consulta el pago que está esperando, abre uno nuevo. Consulta el estado con GET $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ándoCómo reaccionar
400 con Processor not allowedLa 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 foundEl uid no existe o no pertenece a tu comercio. Verifica el uid que te devolvió la creación.
403 al procesar el pagoEl 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 abrirloLa transacción ya no es pagable (se pagó, se procesó o expiró). Crea una nueva.
400 con el rechazo del bancoEl banco rechazó el pedido. Expón el motivo y ofrece otro método.
El cliente volvió pero no llegó el callbackComportamiento esperado si el banco aún no notificó. Consulta el estado; no marques la orden como pagada.
Quedó en pending y no avanzaEs 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 do hoy. 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 do hoy; si lo necesitas, contacta a Operaciones de Migo.

Verificación​

  • Token de comercio enviado como Authorization: <token>; POST /transactions probado con country: "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 en pending y se resuelve por callback más tarde.
  • bancoPopular: transacciones creadas en DOP o USD; en otra moneda el método no aparece.
  • Credenciales de producción rotadas por separado de las de sandbox.

Relacionado​