Saltar al contenido principal
Migo Docs

República Dominicana — recetas de integración

El mercado de República Dominicana es solo Payment Links hoy. Los pagos con tarjeta se procesan a través del acquirer Azul dentro del webview hosteado por Migo. No hay rails de pago alternativo (ningún equivalente de Nequi/agregador-QR cableado para do en este momento).

Un solo rail. Cada cobro creado para country: "DO" es un Payment Link. Usa POST /transactions (o /transactions-hook) y deja que el cliente lo liquide dentro del webview hosteado.

Setup (hazlo una sola vez)​

Los Payment Links usan el token de comercio de larga duración de 64 caracteres enviado como Authorization: <token> (sin prefijo de esquema) — ve Autenticación → Formato del header por endpoint. 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.callbackUrl es alcanzable para webhooks.
  • Opcional: configura successUrl / failureUrl para que el cliente sea devuelto a tu dominio después de autorizar en el webview.

Paso 1 — Crear un Payment Link​

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 Payment Link. 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/refund están en la superficie middleware-pay (esquema JWT-Bearer, separado de la superficie de token de comercio de Payment Link):

# Reversión el mismo día (antes de la liquidación)
curl -X POST "$MIGO_BASE/revert" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "transactionUid": "'"$UID"'", "processor": "azul" }'

# Reembolso después de la liquidación
curl -X POST "$MIGO_BASE/refund" \
  -H "Authorization: Bearer <jwt>" \
  -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 Payment Link 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.

Checklist de hecho​

  • POST /transactions retornó una URL de webview de Migo para country: "DO".
  • El cliente llegó al webview y autorizó con la tarjeta de sandbox.
  • Challenge 3DS probado al menos una vez (usa la tarjeta 3DS de arriba).
  • Generic Callback recibido con processor: "azul".
  • Endpoints de refund y reversión ejercitados en sandbox.

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 Payment Link / webview hosteado.
  • Fallback de Cybersource no está habilitado para do hoy; si lo necesitas, contacta a Operaciones de Migo.

Checklist final​

  • Token de comercio enviado como Authorization: <token>; POST /transactions probado con country: "DO", currency: "DOP".
  • Callback recibido para al menos un evento aprobado y uno rechazado.
  • Rutas de refund/reversión probadas.
  • Credenciales de producción rotadas por separado de las de sandbox.