Платежи с Wealth Reader

Архитектура в два этапа

Интеграция платежей осуществляется по строгому разделению обязанностей в два этапа:

sequenceDiagram
autonumber
actor Usuario as Пользователь
participant Front as Frontend (Commerce)
participant Back as Бэкенд (Commerce)
participant API as API Wealth Reader
participant Widget as Платежи по виджетам
participant Banco as Банк (SCA)
Note over Back,API: Предыдущий шаг (только управляемые профили)
Back->>API: POST /payments/?action=profile-institutions
API-->>Back: Каталог профиля (institution_code)
Note over Back,API: Шаг 1: Создание неизменяемого намерения (сервер-сервер)
Back->>API: POST /payments/?action=create (с X-API-Key и Idempotency-Key)
API-->>Back: 201 с payment.id + payment.widget.token эфемерным
Note over Front,Widget: Шаг 2: Загрузка и авторизация в виджете (браузере)
Back->>Front: Доставка payment.id и payment.widget.token
Front->>Widget: WealthReaderPayments.mount(...) или load-payments.js
Widget->>Usuario: Показывает неизменяемые банк, сумму и назначение платежа
Usuario->>Widget: Авторизация оплаты
Widget->>Banco: Перенаправить / Приложение в приложение (SCA)
Banco->>API: Возвращение SCA в callback Wealth Reader
API-->>Widget: Техническое подтверждение авторизации
Note over Back,API: Финансовое примирение и конфирмация
loop В конечное состояние
Back->>API: POST /payments/?action=status
API-->>Back: payment_status: not_initiated | pending | settled | ...
end

1. Шаг 1 (Безопасный бэкенд): Ваш сервер создаёт намерение оплаты (POST /payments/?action=create) с помощью вашего X-API-Key, Idempotency-Key и Content-Type: application/json. В этом звонке сумма (amount_minor, в центах), валюта (currency, сегодня только EUR), бенефициар (beneficiary.name и beneficiary.iban), назначение платежа в выписке (reference), её внутренняя ссылка (customer_reference) и разрешённый веб-источник (allowed_origin) неизменно фиксированы. Эти шесть полей обязательны, а корпус — это строгий белый список: любое нераспознанное поле возвращает 422 invalid_request.
2. Ответ: 201 с {"success": true, "payment": {…}} — или 200 при идемпотентном повторе. Идентификатор намерения находится в payment.id, а краткосрочный токен виджета — в payment.widget.token.
3. Шаг 2 (Фронтенд сделки): Браузер монтирует виджет с помощью официального скрипта load-payments.js или функции WealthReaderPayments.mount(), доставляя только payment.id и payment.widget.token. Пользователь выбирает свой банк (если он не был заранее выбран в замысле) и завершает сильную аутентификацию (SCA) в банковском интерфейсе.
4. Финансовое подтверждение: ваш бэкенд запрашивает статус платежа с помощью POST /payments/?action=status, чей корпус точно {"payment_intent_id": "<id>"}. Нет вебхука: он опрашивается, пока не достигнет конечного состояния.

Две модели оплаты

Wealth Reader поддерживает две модели в зависимости от потребностей бизнеса:

1. Стандартная интеграция для торговцев (собственный бенефициар):
   • Торговец свободно определяет имя и IBAN бенефициара, сумму, валюту (EUR), концепцию и ссылку на заказ.
   • Вы можете отфильтровать, какие банки сделать доступными пользователю с помощью allowed_institution_codes или разрешить весь каталог.
2. Управляемые профили (например, cruz_roja_demo):
   • Предназначен для пожертвований и публичных демонстраций.
   • Сервер устанавливает официальные счета назначения так, чтобы средства могли быть направлены только в благотворительную организацию (например, в Испанский Красный Крест с суммами от 0,01 EUR до 1,00 EUR).

Единый каталог банковских организаций

Wealth Reader предоставляет единый каталог европейских организаций, подготовленных к инициации платежей через PSD2 через:

• GET https://api.wealthreader.com/payments/entities/?country=ES

Он позволяет получить список банков с их стандартизированными названиями, логотипами, поддерживаемыми методами перевода и техническими требованиями (например, необходимостью запросить IBAN должника у плательщика). Он поддерживает фильтры country, search (псевдоним q), code, payment_method, limit и offset.

Эта конечная точка публичная: она не требует X-API-Key. Отправка не приносит ничего и потребляет звонок из вашей квоты вызовов ключа API.

Всегда используйте эти коды по мере их поступления code. Создание намерения подтверждает форматирование allowed_institution_codes, но не проверяет наличие их в каталоге: ошибочный код не вызывает ошибку при создании и позже появляется как пустой банк picker.

Разделение обязанностей

• Ключ доступа к оплате (X-API-Key) используется только между серверами. Он никогда не должен включаться в фронтенд или публичные репозитории.
• Браузер получает только идентификатор намерения и кратковременный эфемерный token , связанный с исходным HTTPS.
• Виджет не может изменять сумму, валюту, бенефициара, концепцию или уполномоченные учреждения.
• Закрытие модала или виджета не заменяет запрос финансового статуса платежа на бэкенде.
• Платежи не разделяют ключи доступа, токены или обратные вызовы с продуктом агрегации банков Wealth Reader.

Учётные данные и квота вызовов

Для ключа API платежей должен быть включён продукт PAYMENTS; иначе API возвращает 403 payments_not_allowed. Отсутствующий или неверно оформленный ключ API приводит к 401 invalid_api_key.

Следующий шаг

Продолжайте Интеграция и виджет.