Skip to main content
Migo Docs

República Dominicana — integration recipes

The Dominican Republic market is Payment Links only today. Card payments are processed through the Azul acquirer inside the Migo-hosted webview. There are no alternative payment rails (no Nequi/QR-aggregator equivalents wired for do at this time).

Single rail. Every charge created for country: "DO" is a Payment Link. Use POST /transactions (or /transactions-hook) and let the customer settle it inside the hosted webview.

Setup (do this once)​

Payment Links use the long-lived 64-char merchant token sent as Authorization: <token> (no scheme prefix) — see Authentication → Header format by endpoint. No login round-trip is required.

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

Country: Dominican Republic · Type: Hosted webview (Migo) → card processed by Azul · Pre-call payment-intents: No · Response payload: url (the webview URL).

Pre-requisites​

  • clientConfig.processors includes azul.
  • Your clientConfig.callbackUrl is reachable for webhooks.
  • Optional: configure successUrl / failureUrl so the customer is bounced back to your domain after authorizing on the webview.

Step 1 — Create a 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" }
  }'

The POST /transactions create flow (request/response contract) is documented in Create a Payment Link. Send the returned checkout URL to the customer through whatever channel matches your channel value (WhatsApp, email, SMS, app, or web).

Step 2 — Customer authorizes on the webview​

The customer opens data.url, types their card, and Migo routes the authorization to Azul. Azul performs:

  • 3-D Secure authentication when required by the card brand.
  • Optional installments (Cuotas selector inside the webview).
  • Tokenization (the customer can save the card for future charges).

The customer is then redirected to your successUrl or failureUrl.

Step 3 — Webhook​

Once Azul confirms the authorization, Migo emits the Merchant Generic Callback to the callback URL configured in your clientConfig.callback. The exact payload (URL, body, headers) is whatever your clientConfig.callback.data template defines — there is no fixed platform-generated envelope. A typical body looks like:

{
  "uid": "trx_…",
  "externalId": "your-internal-order-id",
  "status": "approved",
  "processor": "azul",
  "reference": "MIGO-…",
  "amount": 50000,
  "currency": "DOP",
  "country": "DO"
}
Signature header

No outbound webhook signer exists in code today — the platform does not currently emit an X-Migo-Signature header.

Refund / reversal​

Azul supports both. Revert/refund are on the middleware-pay surface (JWT-Bearer scheme, separate from the merchant-token Payment Link surface):

# Same-day reversal (before settlement)
curl -X POST "$MIGO_BASE/revert" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "transactionUid": "'"$UID"'", "processor": "azul" }'

# Refund after settlement
curl -X POST "$MIGO_BASE/refund" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "transactionUid": "'"$UID"'", "processor": "azul", "amount": 50000 }'

Sandbox data​

CardBehaviour
4035 8740 0000 0029Approves
4035 8740 0000 0011Declines (card_declined)
4035 8740 0000 1111Triggers 3DS challenge — pass success / fail in the challenge step

Use any future expiry and any 3-digit CVV.

Common errors​

The Payment Link create flow validates required params and returns a 400 on failure. Surface decline reasons from the callback status rather than synthesizing error codes.

WhenHow to react
country missing or not DOSend country: "DO" at create time.
currency not supportedUse DOP (Dominican peso).
Azul declined the charge (card_declined, insufficient_funds, expired_card)Surface the decline reason to the customer; offer a different card.
Azul timed outRetry the create flow; reconcile via the callback.

Done checklist​

  • POST /transactions returned a Migo webview URL for country: "DO".
  • Customer reached the webview and authorized with the sandbox card.
  • 3DS challenge tested at least once (use the 3DS card above).
  • Generic Callback received with processor: "azul".
  • Refund and reversal endpoints exercised in sandbox.

Other webview surfaces​

  • Apple Pay / Google Pay are not wired for do today. Where supported on other markets, Apple Pay is processed through the Payment Link / hosted-webview card flow.
  • Cybersource fallback is not enabled for do today; if you need it, contact Migo Operations.

Final checklist​

  • Merchant token sent as Authorization: <token>; POST /transactions tested with country: "DO", currency: "DOP".
  • Callback received for at least one approved and one declined event.
  • Refund/reversal paths tested.
  • Production credentials rotated separately from sandbox.