Создание и обновление
Два метода описывают сделку: create_deal создаёт новую, update_deal меняет ещё не исполненную.
Создание сделки
Метод create_deal создаёт сделку, в рамках которой пройдут выплаты. Вы описываете общую сумму, плательщиков и получателей — а сервис в ответ возвращает идентификатор сделки и результат предварительной проверки платежей комплаенс-службой. Поля метода — в автогенерируемом описании Создать сделку.
Каждый получатель в recipients имеет тип, который задаёт направление выплаты. Полный список типов — в обзоре раздела. Набор полей получателя зависит от типа: например, для оплаты по договору нужны реквизиты счёта, для выплаты на карту — зашифрованный номер карты, для СБП — номер телефона и банк.
Чтобы сделка не создалась дважды, передайте ext_key — внешний идентификатор сделки. Если сделка с таким ключом уже есть, вернётся ошибка 4442.
При оплате в пользу нерезидента РФ указывайте код валютной операции {VO21200} до текста назначения платежа, иначе платёж не пройдёт.
Тип получателя payment_contract_by_sbp_v2 — это новый флоу выплат по номеру телефона через СБП. Он доступен только по запросу. Чтобы подключить его, обратитесь в техподдержку.
Бюджетные платежи в сделке
Если среди получателей есть тип ndfl, это платёж в бюджет — его нужно снабдить налоговыми полями tax_fields. С 1 апреля 2026 года правила заполнения этих полей ужесточены: платёж с некорректными полями отклоняется с ошибкой 4002. Все допустимые значения полей 101, 106, 107, 108 и 109 собраны на странице Бюджетные платежи.
Возможные ошибки
| Код | Текст |
|---|---|
4411 | Virtual account not found |
4415 | Insufficient funds on the virtual account |
4428 | Not found SBP bank by id |
4436 | An error occurred while requesting compliance |
4437 | Compliance has introduced a restriction on b2c transfers |
4442 | Deal with the provided external key already exists |
4556 | Virtual account is not associated with the nominal account of the payer |
4557 | Virtual accounts must be associated with only one nominal account |
4451 | The purpose of the non-resident's payment contains incorrect or missing VO codes |
4558 | It is impossible to perform the operation due to the fact that restrictions are imposed on the beneficiary based on the writ of execution |
4947 | Payment type not allowed for system |
Обновление сделки
Метод update_deal меняет данные сделки, пока она не исполнена. Структура deal_data полностью повторяет то, что вы передавали при создании: сумму, плательщиков и получателей. Поля метода — в автогенерируемом описании Обновить сделку.
Получателя в сделке изменить нельзя — при попытке вернётся ошибка 4419. Можно менять суммы и состав, но не подменять уже заведённого получателя другим.
Возможные ошибки
| Код | Текст |
|---|---|
4411 | Virtual account not found |
4415 | Insufficient funds on the virtual account |
4418 | This operation is impossible with the current status of the deal |
4419 | You cannot change the recipient |
4428 | Not found SBP bank by id |
4436 | An error occurred while requesting compliance |
4437 | Compliance has introduced a restriction on b2c transfers |
4451 | The purpose of the non-resident's payment contains incorrect or missing VO codes |
4558 | It is impossible to perform the operation due to the fact that restrictions are imposed on the beneficiary based on the writ of execution |
4947 | Payment type not allowed for system |