Платежи

Платежные намерения и идемпотентность

Платежное намерение неизменно устанавливает экономические условия транзакции до того, как пользователь взаимодействует с виджетом. Это предотвращает вмешательство вредоносного клиента в сумму, целевой счет или концепцию перевода на фронтенде.

Параметры создания намерения оплаты (`POST /payments/?action=create`)

1. Стандартная модель для торговцев (собственный бенефициар)

В этой модели продавец определяет все данные о сборе:

Поле	Тип	Обязательно	Описание и правила
`amount_minor`	Целое число	Да	Сумма в меньших единицах (центах). Например, `1500` обозначает `15,00 EUR`.
`currency`	Текстовая строка	Да	ISO 4217 3-буквенный валютный код. В настоящее время `EUR`.
`beneficiary`	Объект данных JSON	Да	Данные аккаунта назначения: `name` (владелец, от 1 до 140 текстовых символов) и `iban` (действительныйIBAN без пробелов, с проверенной контрольной цифрой). Поддерживается только эти два ключа.
`reference`	Строка	Да	Назначение платежа, отображаемое в банковской выписке (не более 140 символов).
`customer_reference`	Текстовая строка	Да	Внутренний идентификатор вашего заказа или клиента (от 1 до 128 символов текста: буквы, цифры, `.`, `_`, `:`, `-`должен начинаться с буквы или цифры).
`allowed_origin`	Текстовая строка	Да	Точно HTTPS источник, который встраивает виджет (например, `https://tienda.example.com`), без пути.
`allowed_institution_codes`	Массив данных	Нет	Список разрешённых кодов сущностей (например, `["santander-es", "bbva-es"]`). Если он опущен, разрешён любой объект из каталога.
`locale`	Текстовая строка	Нет	Язык интерфейса виджета. В этом релизе принимаются только `es`; любое другое значение возвращает `422 invalid_locale`.
`expected_mode`	Строка	Нет	`mock` или `live`. Проверяет, что запрос направлен в ожидаемую среду; не переключает среду. При несовпадении возвращается `409 payment_mode_mismatch`.

Тело — это строгий белый список: отправка поля, отсутствующего в этой таблице, возвращает 422 invalid_request, как и пропуск обязательного. Заголовок Content-Type: application/json обязателен (415 json_required), а корпус ограничен 32 КБ.

2. Модель с управляемым профилем (пожертвования/демонстрации)

Для регулируемых дел или публичных демонстраций, таких как cruz_roja_demo, сервер устанавливает финансовые правила и устанавливает официальные целевые счета:

Поле	Тип	Обязательно	Описание и правила
`profile`	Текстовая строка	Да	Идентификатор профиля (например, `cruz_roja_demo`).
`institution_code`	Текстовая строка	Да	Выбранный пользователем код сущности (от `profile-institutions`).
`amount_minor`	Целое число	Да	Сумма ограничена правилами профиля (например, от 1 до 100 центов).
`customer_reference`	Текстовая строка	Да	Референс по аудиту вашей системы.
`allowed_origin`	Текстовая строка	Да	Виджет HTTPS источник.
`locale`	Текстовая строка	Нет	Язык виджетов (`es`).
`expected_mode`	Текстовая строка	Нет	Ожидаемый режим (`mock` или `live`).

Когда profileуказано, сервер автоматически назначает официального получателя и соответствующую концепцию. Не отправляйте beneficiary или reference на запросы с управляемым профилем.

Правило `Idempotency-Key`

Заголовок Idempotency-Key необходим в любом запросе для создания платежного намерения. Он должен содержать от 16 до 128 символов видимого ASCII-текста без пробелов (например, UUID v4). Его область деятельности уникальна для аутентифицированной компании:

Тот же ключ идемпотентности и то же тело: возвращает ранее созданный первоначальный намерение вместе с idempotent_replay: true. Новый списание не генерируется, и банковский заказ не дублируется.
Тот же ключ идемпотентности и другое тело: API немедленно возвращает HTTP 409 Conflict.
Тот же ключ идемпотентности в другой компании: принадлежит другому полностью изолированному пространству идемпотентности.

Если запрос на создание платежного намерения приводит к сбою сети или тайм-ауту, попробуйте повторить с точно тем же заголовком Idempotency-Key и тем же телом. Не генерируйте новый ключ в случае временного сбоя.

Стойкость и жизненный цикл

Предшествующая устойчивость: Намерение фиксируется в базе данных до возврата ответа или взаимодействия с любым банковским коннектором.
Эфемерный токен виджета: Ответный token (payment.widget.token) имеет короткий срок действия (обычно 15–30 минут) и может использоваться только из объявленного allowed_origin .
Блокировка параллелизма: Система реализует оптимистичный и leases контроль, чтобы предотвратить авторизацию или изменение одного и того же намерения двумя одновременными вызовами.

Распространённые коды ошибок

HTTP	Код	Причина	Рекомендуемые действия
`400`	`idempotency_key_required`	Заголовок `Idempotency-Key` отсутствует или неправильно отформатирован.	Сгенерируйте допустимый ключ от 16 до 128 символов видимого ASCII-текста без пробелов.
`409`	`idempotency_conflict`	Ключ был повторно использован с другими платежными данными.	Создайте новый ключ для разных платежей или повторно используйте точно такое же тело запроса.
`409`	`payment_mode_mismatch`	`expected_mode` не совпадает с режимом окружающей среды, которую вы вызываете.	Проверьте, нацелены ли вы на песочницу или в продакшн; режим задаётся развёртыванием, а не вызовом.
`401`	`invalid_api_key`	Заголовок `X-API-Key`отсутствует, его формат невалиден, или ключ доступа отсутствует или неактивен.	Проверьте ключ API. Никогда не включайте его в интерфейс.
`403`	`payments_not_allowed`	Для ключа API не включён продукт `PAYMENTS`.	Обратитесь в поддержку Wealth Reader для активации платежей в аккаунте.
`403`	`payment_profile_not_allowed`	Управляемый профиль не включён для вашей компании.	Запросите регистрацию аккаунта профиля у Wealth Reader.
`429`	`api_limit_reached`	Для вашего ключа API исчерпан накопительный лимит вызовов.	Это не решается повторной попыткой или ожиданием: нет окна или автоматического сброса. Запрос на продлить лимит.
`415`	`json_required`	Отсутствует `Content-Type: application/json`заголовок.	Отправьте тело как JSON.
`422`	`invalid_request`	Отсутствует обязательное поле или передано неизвестное поле.	Проверьте таблицу параметров: тело запроса использует строгий разрешающий список.
`422`	`invalid_institution`	Выбранная банковская организация недоступно или недействительно.	См. `GET /payments/entities/` для действительных кодов.
`422`	`invalid_amount`	Сумма меньше минимального (€0,01) или не является целым числом.	Проверьте, что вы отправляете целое число в центах (`amount_minor`).

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

Продолжайте Статусы, периодические консультации по статусу и примирение.

Последнее обновление 2026-09-10

Параметры создания намерения оплаты (POST /payments/?action=create)