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

POST /api/agent-payments
Создаёт заказ в эквайринге и возвращает ссылку для оплаты клиентом.

Авторизация

Используйте Basic Authentication агента.

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

Передавайте Content-Type: application/json. Ограничение тела JSON — 32 КБ. Неизвестные поля отклоняются на верхнем уровне и внутри recipient и reportData.
ПолеТип/форматОбязательноОписание
merchantUserNameСтрока, 1–2000 символовДаИмя назначенного мерчанта, не логин агента.
agentOrderIdСтрока, 1–2000 символовДаНомер заказа в вашей системе.
amountПоложительная десятичная строкаДаСумма получателю в рублях, без комиссий. Не более двух знаков после точки.
recipientОбъектДаРеквизиты получателя; см. ниже.
purposeСтрока, 1–2000 символовДаНазначение платежа получателю.
successUrlАбсолютный URL, 1–2000 символовДаАдрес возврата клиента после успешной оплаты.
failureUrlАбсолютный URL, 1–2000 символовДаАдрес возврата клиента после неуспешной оплаты.
billingAccountСтрока, 1–255 символовНетЛицевой счёт.
reportDataОбъект или nullНетДополнительные данные плательщика для отчёта; см. ниже.

Получатель

ПолеТип/форматОбязательноОписание
nameСтрока, 1–2000 символовДаНаименование получателя.
tinСтрока, 10 или 12 цифрДаИНН получателя.
bicСтрока, 9 цифрДаБИК банка получателя.
bankAccountСтрока, 20 цифрДаРасчётный счёт получателя.
territoryCodeСтрока, 8 цифрНетКод территории получателя.
iecСтрока, 1–2000 символовНетКПП получателя.
bankNameСтрока, 1–2000 символовНетНаименование банка получателя.
offsettingAccountСтрока, 1–2000 символовНетКорреспондентский счёт банка.
Передавайте идентификаторы и номера счетов строками, сохраняя ведущие нули. Переданные строки должны быть непустыми и без пробелов по краям.

Данные отчёта

ПолеТип/форматОбязательноОписание
payerNameСтрока, 1–2000 символовНетФИО или наименование плательщика.
addressСтрока, 1–2000 символовНетАдрес плательщика.
periodСтрока, YYYY-MMНетРасчётный период; месяц от 01 до 12, например 2026-10.

Адреса возврата

Используйте абсолютные URL. Поддерживаются HTTP(S) и deep link, например myapp://payments/success. Относительные URL, пробелы по краям, некорректное URL-кодирование и адреса, содержащие javascript: (в том числе в закодированном виде), отклоняются. Допустимые URL передаются в эквайринг без изменений; эквайринг может предъявлять дополнительные требования.
Внимание: Адреса возврата перенаправляют клиента; это не серверные уведомления и не подтверждение оплаты.

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

Примеры иллюстративные. Используйте учётные данные, мерчанта и реквизиты, согласованные при подключении. Сохраните тело в файл agent-payment.json:
json
{
    "merchantUserName": "agent-merchant",
    "agentOrderId": "order-2026-001",
    "amount": "100.00",
    "recipient": {
        "name": "Пример получателя",
        "tin": "9731062087",
        "bic": "046577674",
        "bankAccount": "40702810516540077181",
        "territoryCode": "12345678"
    },
    "purpose": "Оплата услуг по заказу order-2026-001",
    "billingAccount": "000123",
    "reportData": {
        "payerName": "Пример плательщика",
        "address": "Пример адреса для отчёта",
        "period": "2026-10"
    },
    "successUrl": "https://agent.example/payments/success",
    "failureUrl": "https://agent.example/payments/failure"
}
Настройте переменные окружения для авторизации и выполните:
bash
curl --request POST \
    --url "${RB_API_BASE_URL%/}/api/agent-payments" \
    --user "${AGENT_USERNAME}:${AGENT_PASSWORD}" \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data-binary @agent-payment.json

Ответ

Успешная регистрация возвращает HTTP 201 и JSON-объект:
ПолеТип/форматОписание
idСтрока, UUIDИдентификатор платежа для проверки статуса.
orderIdСтрокаИдентификатор заказа в эквайринге.
paymentUrlСтрока, URLСсылка для оплаты клиентом.
amountДесятичная строкаИсходная сумма получателю в рублях.
modifiedAmountДесятичная строкаПолная сумма к оплате клиентом в рублях, включая комиссии.
json
{
    "id": "d325725f-6c73-4dab-910f-88e3274b66d7",
    "orderId": "7a0eb568-4d20-4a2a-8d20-b7e79201e05d",
    "paymentUrl": "https://acquiring.example/payment/demo-order",
    "amount": "100.00",
    "modifiedAmount": "101.78"
}
Сохраните ответ вместе со своим agentOrderId до перенаправления клиента на paymentUrl. Метод проверки статуса не возвращает ссылку на оплату.

Суммы и комиссии

Передавайте рубли положительной десятичной строкой, например "100.00" или "0.01".
Сервис добавляет доплату по тарифу мерчанта; не рассчитывайте и не добавляйте комиссии к amount самостоятельно. В примере ответа получателю предназначено 100 рублей, а клиент оплачивает 101,78 рубля. Фактические комиссии зависят от тарифа мерчанта, который фиксируется для платежа при регистрации.

Коды ошибок

Ошибки используют общий формат.
HTTPextensions.codeextensions.typeПричина и действие
400BAD_USER_INPUTINVALID_AGENT_PAYMENT_REQUESTНеверные поля или реквизиты. Исправьте запрос.
400BAD_USER_INPUTINVALID_REQUEST_BODYНеверный JSON или неподдерживаемый формат/кодирование. Проверьте тело и Content-Type.
401UNAUTHENTICATEDAUTHORIZATION_REQUIREDПроверьте учётные данные и включён ли агент.
413PAYLOAD_TOO_LARGEINVALID_REQUEST_BODYТело больше 32 КБ. Уменьшите запрос.
500INTERNAL_ERRORREGISTRATION_FAILEDОшибка регистрации, настройки мерчанта или эквайринга. Не повторяйте автоматически.
500INTERNAL_ERRORINTERNAL_SERVER_ERRORНепредвиденная ошибка сервиса. Не повторяйте автоматически; обратитесь в поддержку.

Повторные запросы и неопределённый результат

Внимание: POST не идемпотентен. Повтор с тем же agentOrderId может создать ещё один заказ в эквайринге и ещё одну попытку платежа.
После успешного создания используйте сохранённую ссылку и проверяйте статус существующего платежа. Тайм-аут, сетевая ошибка, HTTP 500 или ответ шлюза не в формате JSON-ошибок не доказывают, что регистрация не состоялась. Не повторяйте POST автоматически.
Если известен id платежа — запросите статус. Иначе обратитесь в поддержку с merchantUserName, agentOrderId, суммой, временем запроса и доступными идентификаторами ошибки и запроса. Поиска по agentOrderId нет. Не передавайте учётные данные. Новый платёж не отменяет предыдущую попытку.
Редактировать эту страницу на Github
Назад: Авторизация
Далее: Проверка статуса платежа