República Dominicana — integration recipes
The Dominican Republic has two rails: card payments are processed through the Azul acquirer inside the Migo-hosted webview, and Banco Popular (bancoPopular) charges a bank account by sending the customer to authorize the debit in their online banking. It is the first alternative payment rail wired for do.
How to choose. A charge created for
country: "DO"with nothing else is a card Payment Link routed to Azul. To charge a Banco Popular account, process the payment explicitly withprocessor: "bancoPopular"against the transaction you already created.
Setup
Payment Links use the long-lived 64-char merchant token sent as Authorization: <token> (no scheme prefix). 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"
Payment Link routed to Azul (azul)
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.processorsincludesazul.- Your
clientConfig.callbackis reachable for webhooks. - Optional: configure
successUrl/failureUrlso 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 (
Cuotasselector 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"
}
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 and refund live under /pay, with the same merchant token as every other call:
# Same-day reversal (before settlement)
curl -X POST "$MIGO_BASE/pay/revert" \
-H "Authorization: Bearer $MIGO_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "transactionUid": "'"$UID"'", "processor": "azul" }'
# Refund after settlement
curl -X POST "$MIGO_BASE/pay/refund" \
-H "Authorization: Bearer $MIGO_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "transactionUid": "'"$UID"'", "processor": "azul", "amount": 50000 }'
Sandbox data
| Card | Behaviour |
|---|---|
4035 8740 0000 0029 | Approves |
4035 8740 0000 0011 | Declines (card_declined) |
4035 8740 0000 1111 | Triggers 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.
| When | How to react |
|---|---|
country missing or not DO | Send country: "DO" at create time. |
currency not supported | Use 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 out | Retry the create flow; reconcile via the callback. |
Banco Popular (bancoPopular)
Country: Dominican Republic · Type: Bank online banking (Banco Popular domain) ·
payment-intentspre-call: No · Response payload:url.
Prerequisites
clientConfig.processorsincludesbancoPopular, with the agreement credentials provisioned by Migo Operations.- You can redirect the customer to an external domain from your checkout.
- Your
clientConfig.callbackis reachable for webhooks: the result arrives by callback, not by the customer coming back. - The transaction is in
DOPorUSD. In any other currency the method is not offered. If the customer pays from an account in another currency, the bank converts at the day's rate.
Process the payment
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 data block: the rail asks the customer for nothing extra.
Expected response — the link is in data.data:
{
"success": true,
"message": "Success",
"data": {
"uid": "trx_…",
"type": "url",
"data": "https://mw.migopayments.com/configs/redirect/banco-popular/trx_…",
"cancelAt": 900
}
}
Redirect the customer to data.data. The host changes per environment (sb-mw.migopayments.com in sandbox): always use the link the API returns.
Unlike other hosted buttons, data.data does not point at the bank: it points at a Migo page that forwards the customer to Banco Popular. The bank requires a signed form POST instead of accepting a URL, and that page is what performs the conversion without exposing the signature. Treat it like any other redirect: send the customer to it, and do not try to rebuild it or POST on your own.
cancelAt is the number of seconds until the link expires (900 s by default).
Status delivery
The customer authorizes the debit in Banco Popular's online banking. The status always arrives through the merchant callback, triggered by the signed notification the bank sends Migo.
Banco Popular returns the customer to Migo through a redirect that is independent of the payment notification. That redirect confirms nothing: it can arrive before the notification, or never arrive at all if the customer closes the tab. Do not mark the order as paid when the customer returns — wait for the callback.
Business payments: the pending status
A business account may require a second signature. When it does, the bank notifies that the payment is awaiting approval and the transaction stays pending:
- The callback does not fire yet. Only
approvedanddeniedclose the transaction. - It may resolve much later, when the approver confirms in their online banking. The default window is 24 hours; past that window the transaction expires.
- If you poll the status,
pendingmeans "waiting for the approver", not "failed". Do not retry it: a retry does not check on the payment that is waiting, it opens a new one. Poll the status withGET $MIGO_BASE/api/v1/integrations/transactions/{uid}.
Design your integration so a Dominican Republic order can stay open for hours and close by callback.
Refund / reversal
Not supported. This rail exposes neither refund nor reversal over the API. Any money returned to the customer is arranged directly with Banco Popular, outside the platform.
Sandbox data
- The rail points at Banco Popular's test environment; test online-banking credentials are required and provided by Migo Operations.
- Test at least one approved payment, one declined, and one that stays
pending.
Common errors
| When | How to react |
|---|---|
400 with Processor not allowed | The transaction is not in DOP or USD, or the method is not enabled for your client. Create the transaction in DOP or USD; if it already is, ask Migo Operations to enable it. |
404 with Transaction not found | The uid does not exist or does not belong to your merchant. Check the uid the creation call returned. |
403 when processing the payment | The authorization token is missing or invalid. It has nothing to do with the transaction's state. |
The link answers 409 when opened | The transaction is no longer payable (paid, processed or expired). Create a new one. |
400 with the bank's rejection | The bank rejected the request. Surface the reason and offer another method. |
| The customer came back but no callback arrived | Expected if the bank has not notified yet. Poll the status; do not mark the order as paid. |
Stuck in pending | It is a business payment waiting for the approver. Wait for the callback until the window expires. |
Other webview surfaces
- Apple Pay / Google Pay are not wired for
dotoday. Where supported on other markets, Apple Pay is processed through the Payment Link / hosted-webview card flow. - Cybersource fallback is not enabled for
dotoday; if you need it, contact Migo Operations.
Verification
- Merchant token sent as
Authorization: <token>;POST /transactionstested withcountry: "DO",currency: "DOP". - Customer reached the webview and authorized with the sandbox card.
- 3DS challenge tested at least once, with the sandbox 3DS card.
- Callback received with
processor: "azul"for at least one approved and one declined event. - Refund and reversal paths tested in sandbox (they only apply to
azul). bancoPopular: payment processed, customer redirected to Migo's link and callback received for one approved and one declined.bancoPopular: tested at least one payment that stayspendingand resolves by callback later.bancoPopular: transactions created inDOPorUSD; in any other currency the method does not appear.- Production credentials rotated separately from sandbox.
Related
- Integration recipes — country × rail matrix
- Available payment methods — rail catalog filtered by country
- Process payment — the unified body and the response shape per
data.type - Create a Payment Link — the create contract this recipe uses
- Merchant Generic Callback — status delivery