Multibanco Португалія: ваучери та рефи

1) Контекст і позиціонування Multibanco

• MB References (Pagamento de Serviços / Compras): платіжні реквізити виду Entidade + Referência + Valor для оплати інвойсів в ATM або homebanking.
• MB Voucher / MB Cash at ATM: «ваучерний» сценарій - покупець отримує код/інструкцію і оплачує в ATM або в інтернет-банку; мерчант отримує онлайн-підтвердження від PSP і подальший банківський кредит.

Особливості: дуже низький фрод, фінальність як у банківського переказу (чарджбека немає), зручність для користувачів, які звикли платити через ATM/homebanking.

2) Терміни і формат реквізитів

Entidade (Entity/Service code) - код одержувача в системі SIBS (зазвичай 5 цифр).
Referência (Reference) - 9-значний унікальний ідентифікатор рахунку/замовлення.
Valor (Amount) - сума до оплати (фіксована) або «відкрита» (якщо так налаштовано у PSP/мерчанта).

3) Учасники

SIBS/Multibanco (схема/світч) - маршрутизація і кліринг платежів MB.
Банк платника - надає ATM/homebanking, застосовує ліміти/антифрод.
PSP/Acquirer - видає References/ваучери через API/панель, шле webhooks і реєстри, проводить розрахунки.
Merchant - генерує рахунок (Entity/Reference/Amount), отримує статуси/зарахування, робить повернення.

4) Потоки і канали

4. 1 MB References (інвойси через ATM/homebanking)

1. Мерчант/PSP створює Entidade + Referência + Valor + Expiry і показує їх на чекауті (і/або відправляє по email/SMS).
2. Клієнт платить в ATM або в своєму інтернет-банку → підтверджує операцію.
3. PSP передає мерчанту онлайн-статус (paid/pending/expired тощо) і потім - рух у фін-реєстрах (settlement).

• Динамічна Reference per-order (рекомендовано).
• Статична Reference (для донатів/гаманців) - частіше призводить до складної звірці, використовуйте акуратно.

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

Мерчант через PSP генерує «квазі-ваучер »/код оплати (по суті - короткоживуча Reference).
Клієнт йде в ATM або homebanking і оплачує за кодом → PSP повідомляє онлайн-успіх.
Часто використовується в high-risk/готівкових сценаріях і для клієнтів без карт.

4. 3 Оплата через MB WAY за MB-інвойс

У деяких PSP доступний флоу: клієнт оплачує виписану MB-Reference через MB WAY (гаманець). Це прискорює підтвердження і підвищує конверсію на мобайлі.

5) Статуси та розрахунки

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

Settlement: банківський кредит T + 0/T + 1 (залежить від банківських вікон/PSP). Навіть при миттєвому онлайн-підтвердженні в бухгалтерії спирайтеся на щоденні реєстри.

Часткові платежі: за замовчуванням заборонені (для фіксованого Valor). «Відкрита сума» допускає часткові, але це ускладнює звірку - вмикайте тільки усвідомлено.

6) Ліміти і політика ризику

• Per-transaction / per-day/24h; іноді weekly/monthly.
• Більш жорсткі пороги для нових одержувачів/мерчантів.
• Канальні відмінності: ATM vs homebanking; у деяких банків - різні вікна/пороги.
• Velocity/девайс/гео-сигнали на стороні банку/PSP.

7) Економіка та комісії

Вартість прийому нижче типового картового MDR; умови - у вашого PSP.
Врахуйте витрати на інвойс-розсилку, обробку'expired/pending', саппорт і recon.

8) Повернення і диспути

Chargeback (як в картах) відсутній.
Повернення робиться як нова кредитова операція (зазвичай SEPA Credit Transfer) на IBAN клієнта або через гаманець MB WAY (якщо так погоджено).
Підтримуйте partial refunds в бек-офісі; зберігайте зв'язку'refund↔original reference'.

9) Безпека та відповідність

Підтвердження платежу відбувається в банку платника (ATM/online-banking) → низький фрод.
GDPR/PII-мінімізація: зберігайте тільки необхідні атрибути (Entity/Ref/Amount, маски клієнта).
Веб-хуки - HMAC/nonce, захист від replay, дедуп подій, журнал аудиту.
Враховуйте вимоги Banco de Portugal та договірні умови SIBS/PSP.

10) Звірка і звітність (recon)

• 'entity'( Entidade),'reference'( 9-digit),'amount'( valor),'orderId','status','paidAt','channel'( ATM/homebanking/MB WAY),'pspTxnId', банківську референцію/UTR з реєстрів.
• Щодня: auto-recon за реєстрами PSP/SIBS (зарахування/повернення/корекції) + періодичний full-recon.
• Алерти за розсинхронами: «є онлайн-успіх, немає запису в реєстрі», «подвійна оплата однієї Ref», «невірна сума».

11) UX-патерни (що показати користувачеві)

Великі поля: Entidade/Referência/Valor + дедлайн (expiry) і таймер.
Кнопки копіювати для кожного поля; QR з зашитим набором реквізитів (якщо підтримує ваш PSP).
Інструкції «Як оплатити в ATM/в інтернет-банку» з 3-4 кроками.
Статус замовлення «Очікує оплати» та фонове оновлення. При'expired'- «створити нову референцію» в один клік.
Після підтвердження: чек з'entity','reference','paidAt','UTR'і контактами саппорту.

12) Інтеграція мерчанта

Варіанти

1. Hosted/Embedded у PSP - швидкий старт, авто-генерація References, webhooks і вивантаження.
2. Server-to-Server - власний чекаут/інвойси, динамічні референси per-order, кастомний термін дії.
3. Pay-by-Link - відправка посилання з реквізитами по email/SMS/месенджерам.

• API: `createReference` (entity/ref/amount/expiry), `cancelReference`, `refund`, `webhook`, `reconcile`.
• Ідемпотентність (по'orderId'), експоненціальні ретраї для статусів, dedupe вхідних веб-хуків.
• Каталоги: банки/ліміти, коди помилок, SLA-метрики (ATM vs homebanking), карта витікань.

13) MB WAY і підписки

Базові MB References/ваучери - one-off з підтвердженням у банку.
Для рекурентних списань використовуйте зв'язку: перший платіж → e-mandate/SEPA Direct Debit або MB WAY-мандати (якщо доступні в PSP), з лімітами та повідомленнями.

14) High-risk вертикалі (включаючи iGaming)

Multibanco часто застосовується, але умови/ліміти залежать від PSP/банків і локального права.
Очікуйте знижені пороги, розширений KYC і можливі hold'и.
Плануйте альтернативні рейки (карти, MB WAY, SEPA, інші PIS) і smart-routing.

15) Архітектура «Multibanco Gateway»

API-шар (REST/GraphQL) для каси/інвойс-сервісу.
Черги подій: статус-івенти → білінг/CRM/аналітика.
Security: vault для секретів, IP-allowlist PSP, сувора валідація callback-URL, анти-replay.
Observability: конверсія'created→paid', частка'expired', середній час до оплати, ATM vs homebanking, SLA по веб-хукам/реєстрам.

16) Чек-лист виведення в прод

1. Підключіть PSP з MB References/Voucher; узгодьте терміни settlement і формат реєстрів.
2. Реалізуйте'createReference'( динамічна, з expiry) і сторінки інструкції (ATM/homebanking).
3. Підключіть webhooks, ідемпотентність, ретраї, дедуп.
4. Налаштуйте daily auto-recon + full-recon, зберігання UTR та аудиту.
5. Увімкніть partial/full refunds (SEPA/MB WAY), регламенти ODR.
6. Побудуйте дашборди SLA і алерти по'expired', розсинхронам, помилкам сум.
7. Проженіть e2e-тести ATM/homebanking у топ-банків, таймінги веб-хуків і крайні випадки (минулий ref, подвійна оплата).

Картка орієнтирів

Статуси: `created/pending/paid/expired/canceled/failed`.
Settlement: частіше T + 0/T + 1.
Часткові платежі: за замовчуванням немає (для фіксованої суми).
Повернення: SEPA SCT/гаманець MB WAY як нова кредитова операція.
Рекурент: через e-mandate/SEPA DD (перший платіж → мандат).

Резюме

Для інвойсів/відкладеної оплати використовуйте MB References з динамічним ref і expiry; для готівки/АТМ-аудиторії - MB Voucher.
Будуйте процес навколо webhooks + реєстрів SIBS, чіткої звірки і керованих повернень (SCT/MB WAY).
Тримайте конфіги лімітів по банках/каналах, моніторьте'expired'і таймінги підтверджень.
Для підписок - перший MB → мандат (SEPA/MB WAY) з прозорим управлінням і повідомленнями.