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; для наличных/ATM-аудитории — MB Voucher.
Стройте процесс вокруг webhooks + реестров SIBS, четкой сверки и управляемых возвратов (SCT/MB WAY).
Держите конфиги лимитов по банкам/каналам, мониторьте `expired` и тайминги подтверждений.
Для подписок — первый MB → мандат (SEPA/MB WAY) с прозрачным управлением и уведомлениями.