Skip to main content

Создание платежа

Обязательные параметры

Коды банков

Каждый код банка — это одновременно и банк плательщика, и провайдер, который обслуживает платёж. Коды 16 и 712 — это одни и те же шесть банков у двух разных провайдеров. Один и тот же мерчант может одновременно работать с обоими: балансы, выплаты и реквизиты у них раздельные.
Коды 713 доступны только после подключения провайдера BankApi к вашему аккаунту. Запрос с этими кодами без подключения вернёт 400.
Для кодов 712 поддерживается только выдача карты: paymentMethod: "TO_PHONE" вернёт 400, а в ответе всегда заполнен cardNumber. Поле phoneNumber при этом остаётся в ответе со значением null (если paymentMethod не передан) — не рассчитывайте на его отсутствие, проверяйте значение.

Код 13 — СБП QR

Код 13 — это не банк, а платёжная ссылка СБП. Плательщик открывает приложение любого своего банка и сканирует QR-код; банк отправителя заранее не известен и не выбирается. Отличия от всех остальных кодов:
  • Параметр paymentMethod не поддерживается. Ни TO_CARD, ни TO_PHONE — оба значения вернут 400. Просто не передавайте этот параметр.
  • В dealRequisites приходит url вместо cardNumber. Полей cardNumber и phoneNumber в ответе нет вообще — платёжным инструментом является сама ссылка. Отрисуйте её как QR-код или передайте плательщику ссылкой.
  • bankName в ответе — bankapi_sbp_qr.
Сумма в ответе может отличаться от запрошенной. Для кода 13 банк-получатель выставляет счёт на скорректированную сумму — например, вы запросили 1000, а в ответе пришло 1050. Так разделяются платежи на один общий QR-реквизит.Определяющей является сумма из ответа, поле amount. Именно её должен перевести плательщик, и именно по ней вы будете рассчитаны. Если вы покажете клиенту свою исходную сумму и он переведёт её, платёж не будет засчитан автоматически и потребует ручного разбора.Всегда берите сумму для показа плательщику из поля amount ответа, а не из своего запроса. Это же значение приходит во всех вебхуках по платежу.
Неизвестный код банка возвращает 400 со списком допустимых значений. Ранее такой запрос мог быть молча обработан основным провайдером — теперь он всегда отклоняется.

Пример запроса


Пример ответа (успех)

HTTP Status: 200 OK

Поля ответа


Структура dealRequisites

Поле dealRequisites содержит JSON-строку с реквизитами, куда клиент должен отправить платеж.
Важно: Поле bankName в ответе — это запрошенный российский банк. Фактический банк назначения находится в dealRequisites.bankName и является одним из узбекских банков-партнеров.

Поля объекта

Пример парсинга


Ошибки создания платежа

При создании платежа могут возникнуть следующие ошибки:

Пример ответа с ошибкой

HTTP Status: 400 Bad Request

Проверка статуса

Endpoint для проверки статуса платежа:

Пример запроса

Пример ответа


Webhook-уведомления

При изменении статуса платежа или разрешении апелляции система отправляет webhook на указанный notificationUrl.

HTTP запрос

Формат тела webhook

Поля webhook

Верификация подписи

Webhook подписывается HMAC-SHA256. Используйте ваш notificationToken для верификации:

Создание апелляции

Если автоматическая привязка платежа не сработала (клиент оплатил, но статус не изменился), создайте апелляцию для ручной проверки.
Когда создавать апелляцию: Клиент утверждает, что оплатил, но платеж остается в статусе new или expired.
Важно: После создания апелляции платеж переходит в статус dispute, и все средства замораживаются.

Endpoint

Параметры запроса

URL параметры

Тело запроса (multipart/form-data)

Допустимые значения reason:

Пример запроса

Пример ответа

HTTP Status: 201 Created

Поля ответа апелляции


Автоматическое разрешение

Важно: Если апелляция не будет разрешена в течение 60 минут, система автоматически разрешит её в пользу мерчанта (merchant_win).

Проверка статуса апелляции

Пример запроса

Пример ответа