Multibanco Portugal: Vouchers and refs

1) Multibanco context and positioning

• MB References (Pagamento de Serviços/Compras): payment details of the form Entidade + Referência + Valor for payment of invoices in ATM or homebanking.
• MB Voucher/MB Cash at ATM: "voucher" scenario - the buyer receives the code/instruction and pays in ATM or in the Internet bank; the merchant receives an online confirmation from the PSP and a subsequent bank credit.

Features: very low fraud, finality like a bank transfer (no chargeback), convenience for users who are used to paying via ATM/homebanking.

2) Terms and format of details

Entidade (Entity/Service code) - recipient code in the SIBS system (usually 5 digits).
Referência (Reference) - 9-digit unique identifier of the invoice/order.
Valor (Amount) - amount payable (fixed) or "open" (if so configured at the PSP/merchant).

3) Participants

SIBS/Multibanco (scheme/switch) - routing and clearing of MB payments.
Payer bank - provides ATM/homebanking, applies limits/anti-fraud.
PSP/Acquirer - issues References/vouchers through the API/panel, sends webhooks and registers, conducts calculations.
Merchant - generates an account (Entity/Reference/Amount), receives statuses/credits, makes returns.

4) Flows and channels

4. 1 MB References (invoices via ATM/homebanking)

1. Merchant/PSP creates Entidade + Referência + Valor + Expiry and shows them on the checkout (and/or sends them by email/SMS).
2. The client pays in ATM or in his Internet bank → confirms the transaction.
3. The PSP transmits the online status (paid/pending/expired, etc.) to the merchant and then the movement in the fin registers (settlement).

• Dynamic Reference per-order (recommended).
• Static Reference (for donations/wallets) - more often leads to complex reconciliation, use carefully.

4. 2 MB Voucher (cash at ATM / pay-code)

The merchant generates a "quasi-voucher "/payment code (essentially a short-lived Reference) through the PSP.
The client goes to ATM or homebanking and pays by code → PSP reports online success.
Often used in high-risk/cash scenarios and for customers without cards.

4. 3 Payment via MB WAY for an MB invoice

In some PSPs, flow is available: the client pays for the discharged MB-Reference through MB WAY (wallet). This speeds up confirmation and increases conversion on the mobile.

5) Statuses and calculations

• `created` → `pending` → `paid` / `expired` / `canceled` / `failed`.

Settlement: bank credit T + 0/T + 1 (depends on bank windows/PSP). Even with instant online confirmation in accounting, rely on daily registries.

Partial payments are not allowed by default (for fixed Valor). "Open amount" allows partial, but this complicates reconciliation - include only consciously.

6) Limits and risk policy

• Per-transaction / per-day/24h; sometimes weekly/monthly.
• Tighter thresholds for new recipients/merchants.
• Channel differences: ATM vs homebanking; some banks have different windows/thresholds.
• Velocity/device/geo-signals on the bank/PSP side.

7) Economics and commissions

The cost of reception is lower than a typical card MDR; conditions - at your PSP.
Consider invoice costs, 'expired/pending' processing, support, and recon.

8) Returns and disputes

Chargeback (as in cards) is missing.
The refund is done as a new credit transaction (usually SEPA Credit Transfer) on the customer's IBAN or through the MB WAY wallet (if so agreed).
Support partial refunds in the back office; store the 'refund↔original reference' bundle.

9) Safety and compliance

Payment confirmation takes place at the payer's bank (ATM/online-banking) → low fraud.
GDPR/PII minimization: store only the necessary attributes (Entity/Ref/Amount, client masks).
Web hooks - HMAC/nonce, replay protection, event dedup, audit log.
Consider Banco de Portugal requirements and SIBS/PSP contractual terms.

10) Reconciliation and reporting (recon)

• 'entity '(Entidade),' reference '(9-digit),' amount '(valor),' orderId ',' status', 'paidAt', 'channel' (ATM/homebanking/MB WAY), 'pspTxnId', bank reference/UTR from registries.
• Daily: auto-recon by PSP/SIBS registers (credits/returns/corrections) + periodic full-recon.
• Alerts for out of sync: "there is online success, there is no entry in the register," "double payment of one Ref," "incorrect amount."

11) UX patterns (what to show the user)

Big margins: Entidade/Referência/Valor + deadline (expiry) and timer.
Copy buttons for each field; QR with a hardcoded set of details (if your PSP supports).
Instructions "How to pay in ATM/online banking" with 3-4 steps.
Order status Pending Payment and Background Update. With'expired '- "create a new reference" in one click.
After confirmation: check with 'entity', 'reference', 'paidAt', 'UTR' and support contacts.

12) Merchant integration

Options

1. Hosted/Embedded at PSP - fast start, auto-generation of References, webhooks and uploads.
2. Server-to-Server - own check-out/invoices, dynamic references per-order, custom expiration date.
3. Pay-by-Link - sending a link with details by email/SMS/instant messengers.

• API: `createReference` (entity/ref/amount/expiry), `cancelReference`, `refund`, `webhook`, `reconcile`.
• Idempotence (by 'orderId'), exponential retrays for statuses, dedupe of incoming web hooks.
• Catalogs: banks/limits, error codes, SLA metrics (ATM vs homebanking), expiration card.

13) MB WAY and subscriptions

Basic MB References/vouchers - one-off with confirmation from the bank.
For recurring write-offs, use a bundle: the first payment → e-mandate/SEPA Direct Debit or MB WAY tickets (if available in PSP), with limits and notifications.

14) High-risk verticals (including iGaming)

Multibanco is often applied, but terms/limits depend on PSP/banks and local law.
Expect lowered thresholds, extended KYC and possible holds.
Plan alternative rails (maps, MB WAY, SEPA, other PIS) and smart-routing.

15) Multibanco Gateway architecture

API layer (REST/GraphQL) for cash desk/invoice service.
Event queues: status events → billing/CRM/analytics.
Security: vault for secrets, IP-allowlist PSP, strict callback-URL validation, anti-replay.
Observability: conversion 'created→paid', share 'expired', average time to payment, ATM vs homebanking, SLA by web hooks/registries.

16) Output checklist

1. Connect the PSP with MB References/Voucher; agree on the timing of the settlement and the format of the registers.
2. Implement 'createReference' (dynamic, with expiry) and instruction pages (ATM/homebanking).
3. Connect webhooks, idempotency, retrai, deadup.
4. Configure daily auto-recon + full-recon, UTR storage, and auditing.
5. Enable partial/full refunds (SEPA/MB WAY), ODR regulations.
6. Build SLA dashboards and alerts by'expired ', out of sync, sum errors.
7. Run e2e ATM/homebanking tests from top banks, web hook timings and extreme cases (expired ref, double payment).

Landmark card

Статусы: `created/pending/paid/expired/canceled/failed`.
Settlement: more often T + 0/T + 1.
Partial payments: no default (for a fixed amount).
Return: SEPA SCT/MB WAY purse as a new credit transaction.
Recurrence: via e-mandate/SEPA DD (first payment → mandate).

Summary

For invoices/deferred payment, use MB References with dynamic ref and expiry; for cash/ATM audience - MB Voucher.
Build the process around webhooks + SIBS registries, clear reconciliation and managed returns (SCT/MB WAY).
Keep limit configs by bank/channel, monitor'expired 'and confirmation timings.
For subscriptions, the first MB → ticket (SEPA/MB WAY) with transparent management and notifications.