MagicPayments Integration Guides

Ecuador DeUna Gate

Pay-inUSDDeUnaQR

Accept DeUna QR pay-ins on a hosted page where the payer scans the code or opens the DeUna app, in US Dollars (USD). Pay-in only.

When to use it

The Ecuador DeUna Gate accepts DeUna QR pay-ins on a MagicPayments-hosted page. The payer scans the QR code with the DeUna app, or opens the app straight from the page on a phone, and approves the payment there. No confirmation is needed on our page. The result arrives on its own once the payer pays. Amounts are in USD, which Ecuador uses and which has two decimal places: 2500 minor units means 25.00 USD.

OperationRailHow the integration looks
Pay-inDeUna QR codeCreate an invoice, redirect the payer to the hosted page.
Pay-out—Not available for this method.
Limits

Pay-ins accept 1.00 – 200.00 USD per operation. In minor units that is 100–20000. Your account manager confirms the limits that apply to your account.

Prerequisites

Signing credentials from Getting started and a pay-in gate_id for the Ecuador DeUna gate. Your account manager provides it.

Pay-in — hosted DeUna QR page

  1. Create the invoice Call the gate endpoint with your gate_id, the amount in USD minor units and the payer's details: full name, email and identity document number.
  2. Redirect the payer Send the browser to invoice_url. If you didn't send all of the payer's details, the page first asks for the missing ones. Then it shows the QR code, a payment reference, a countdown and, on a phone, a button that opens the DeUna app. The page is available in Spanish and English.
  3. The payer pays in the app The payer scans the QR code or taps the button and approves the payment in DeUna. They don't need to come back to our page to confirm anything.
  4. Receive the result Once DeUna reports the payment we call your callback_url and the invoice moves to paid. If the payer doesn't pay, DeUna times the payment out and the invoice ends as payment_failed, the same as a declined payment.

Payer details

DeUna needs four details about the payer for every payment. Send them in customer to skip the details step on our page. Any you leave out, the payer types in before the QR code appears. If you send all four, the payer sees the QR code straight away.

FieldWhat to send
customer.full_name The payer's first and last name, separated by a space, as on their ID: "María López". The first word is taken as the first name and the rest as the last name. A single word counts as a first name only, and the page then asks for the last name.
customer.email The payer's email address.
customer.document The payer's identity document number: cédula, RUC or passport number. Send letters and digits only, 5–20 characters, for example 1712345675.
customer.ip_address Recommended. The payer's IP address as your site saw it.
POST/api/invoice
Request body
{
  "gate_id": "ec-deuna-gate",
  "invoice": {
    "invoice_id": "order-ec-2026-000123",
    "currency": "USD",
    "amount": 2500,
    "description": "Premium plan",
    "ttl_minutes": 30
  },
  "customer": {
    "id": "cust-55021",
    "full_name": "María López",
    "email": "[email protected]",
    "document": "1712345675",
    "ip_address": "203.0.113.24"
  },
  "workflow_hooks": {
    "callback_url": "https://merchant.example.com/mp/callbacks",
    "return_success_url": "https://merchant.example.com/orders/123/done",
    "return_decline_url": "https://merchant.example.com/orders/123/retry"
  }
}
Python
resp = signed_post("/api/invoice", {
    "gate_id": "ec-deuna-gate",
    "invoice": {
        "invoice_id": "order-ec-2026-000123",
        "currency": "USD",
        "amount": 2_500,             # 25.00 USD
        "description": "Premium plan",
        "ttl_minutes": 30,
    },
    "customer": {
        "id": "cust-55021",
        "full_name": "María López",
        "email": "[email protected]",
        "document": "1712345675",    # cédula, RUC or passport number
        "ip_address": "203.0.113.24",
    },
    "workflow_hooks": {
        "callback_url": "https://merchant.example.com/mp/callbacks",
        "return_success_url": "https://merchant.example.com/orders/123/done",
        "return_decline_url": "https://merchant.example.com/orders/123/retry",
    },
})
redirect_url = resp.json()["invoice_url"]
Response
{
  "request_id": "5723212f-b99a-4194-971c-f6b2c37102df",
  "request_status": "success",
  "invoice_id": "8381203a-4f9c-4482-b8ad-642b774e153b",
  "merchant_invoice_id": "order-ec-2026-000123",
  "invoice_status": "unpaid",
  "invoice_url": "https://stage.example-mp.com/public/invoice/8381203a-...",
  "message": "Invoice (Gate PayIn) with internal uid=8381203a-... has been created."
}
The QR code expires

The QR code is valid for a limited window (typically ~10 minutes), and the page shows the payer a countdown. Set a ttl_minutes that leaves the payer time to fill in any missing details and pay in the app. Rely on the callback rather than tight polling.

Tracking the pay-in

POST/api/invoice/status
resp = signed_post("/api/invoice/status", {
    "merchant_invoice_id": "order-ec-2026-000123"
})
invoice = resp.json()
# invoice["status"] -> "paid" once DeUna reports the payment
Fulfil only on paid

Don't fulfil the order before the invoice is paid. The page has no "I have paid" button, so the only signal is our callback, or the status endpoint.

Pay-out

Not available for this method

The Ecuador DeUna Gate does not support payouts. There is no payout endpoint to call for this method. For disbursements, use a payout-capable cascade and the relevant guide, or contact your account manager.

Testing & go-live