Skip to main content
Migo Docs

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

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.callback is reachable for webhooks.
  • Optional: configure successUrl / failureUrl so the customer is bounced back to your domain after authorizing on the 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" }
}'

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 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​

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.

Country: Dominican Republic · Type: Bank online banking (Banco Popular domain) · payment-intents pre-call: No · Response payload: url.

Prerequisites​

  • clientConfig.processors includes bancoPopular, with the agreement credentials provisioned by Migo Operations.
  • You can redirect the customer to an external domain from your checkout.
  • Your clientConfig.callback is reachable for webhooks: the result arrives by callback, not by the customer coming back.
  • The transaction is in DOP or USD. 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.

The link is Migo's, not the bank's

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.

The customer coming back does not mean they paid

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 approved and denied close 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, pending means "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 with GET $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​

WhenHow to react
400 with Processor not allowedThe 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 foundThe uid does not exist or does not belong to your merchant. Check the uid the creation call returned.
403 when processing the paymentThe authorization token is missing or invalid. It has nothing to do with the transaction's state.
The link answers 409 when openedThe transaction is no longer payable (paid, processed or expired). Create a new one.
400 with the bank's rejectionThe bank rejected the request. Surface the reason and offer another method.
The customer came back but no callback arrivedExpected if the bank has not notified yet. Poll the status; do not mark the order as paid.
Stuck in pendingIt 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 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.

Verification​

  • Merchant token sent as Authorization: <token>; POST /transactions tested with country: "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 stays pending and resolves by callback later.
  • bancoPopular: transactions created in DOP or USD; in any other currency the method does not appear.
  • Production credentials rotated separately from sandbox.