Multibanco

Multibanco is Portugal's ATM and home-banking voucher network. Demo Pay returns an Entity + Reference + Amount triplet that the customer pays at any ATM, in their bank's app, or via online banking. Settlement: 1–3 business days.

#Flow at a glance

text

1. POST /v1/payments  ──────▶  Demo Pay returns transactionId
2. GET  /v1/payments/{id} ───▶  Within ~1s, mbEntity / mbReference / mbExpiresAt populate
3. Display Entity, Reference, Amount, and expiry to the customer
4. Customer pays at any ATM or via home-banking
5. Webhook payment.completed arrives at your endpoint (1–3 business days later)

#1. Create the payment

Endpoint POST /v1/payments

bash

curl -X POST https://demo.zentry.cloud/v1/payments \
  -H "apikey: $DEMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 12500,
    "currency": "EUR",
    "paymentMethods": ["MULTIBANCO"],
    "customerName": "Rui Mendes",
    "customerEmail": "rui@example.com",
    "metadata": { "orderId": "ORD-3311" },
    "idempotencyKey": "ORD-3311"
  }'

Response 201 Created

json

{
  "id": "d4e5f6a7-b8c9-4012-9def-012345678901",
  "status": "WAITING_PAYMENT",
  "amount": 12500,
  "currency": "EUR",
  "paymentMethods": ["MULTIBANCO"],
  "createdAt": "2026-04-25T16:00:11.000Z"
}

#2. Fetch the voucher

bash

curl https://demo.zentry.cloud/v1/payments/d4e5f6a7-b8c9-4012-9def-012345678901 \
  -H "apikey: $DEMO_API_KEY"

json

{
  "id": "d4e5f6a7-b8c9-4012-9def-012345678901",
  "status": "WAITING_PAYMENT",
  "amount": 12500,
  "currency": "EUR",
  "paymentMethods": ["MULTIBANCO"],
  "mbEntity": "12345",
  "mbReference": "987 654 321",
  "mbExpiresAt": "2026-05-02T16:00:11.000Z",
  "createdAt": "2026-04-25T16:00:11.000Z"
}

Field	Description
`mbEntity`	5-digit Demo Pay Entity (Entidade).
`mbReference`	9-digit Reference (Referência) — payment-specific.
`mbExpiresAt`	Voucher expiry. After this, status moves to `EXPIRED`.

#3. Display the voucher

The customer needs all three values. Recommended UI layout:

text

┌─────────────────────────────────────────┐
│  Pagamento Multibanco                   │
├─────────────────────────────────────────┤
│  Entidade        12345                  │
│  Referência      987 654 321            │
│  Valor           € 125,00               │
│  Validade        02 Maio 2026           │
└─────────────────────────────────────────┘

Pague em qualquer caixa Multibanco ou
através do seu home-banking até à data
de validade.

Email confirmations should include the same three values plus the amount — Portuguese customers expect this format.

#4. Confirm via webhook

json

{
  "event": "payment.completed",
  "data": {
    "transactionId": "d4e5f6a7-b8c9-4012-9def-012345678901",
    "amount": 12500,
    "status": "PAID",
    "previousStatus": "WAITING_PAYMENT",
    "paidWith": "MULTIBANCO",
    "providerFee": 100,
    "platformFee": 125,
    "netAmount": 12275,
    "occurredAt": "2026-04-26T11:32:18.000Z"
  }
}

#Lifecycle

text

WAITING_PAYMENT  ──▶  PAID      ✓ fulfill order
                 ──▶  EXPIRED   voucher window passed (default 7 days)

There is no REFUSED — the voucher is either paid or it expires.

#Edge cases & FAQ

Q: How long does the customer have to pay? A: Default 7 days. Email suporte@demo.zentry.cloud to extend up to 30 days.

Q: Can the customer pay a different amount? A: No. Multibanco vouchers are exact-match on amount and reference. A wrong amount is rejected at the ATM.

Q: My customer paid but the webhook still hasn't fired. A: Multibanco settlement files are batched — expect up to 24h between payment-at-ATM and the payment.completed webhook. If it's been over 48h, contact suporte@demo.zentry.cloud.

Q: Can I generate the same voucher twice? A: Use the same idempotencyKey and you'll get back the original transaction (with the original Entity/Reference). Issue a new transaction only if you want a new voucher.

Q: Bank fees for the customer? A: ATM payments are typically free. Home-banking may charge a small processing fee depending on the bank — out of Demo Pay's control.

#Next

→ API Reference · Sandbox plan