Raiff logo
API docs by Redocly

API интеграции выплат (1.0)

Download OpenAPI specification:Download

Support e-mail: ecom@raiffeisen.ru

Свои предложения и идеи о документации можно оставить в репозитории по адресу: https://github.com/Raiffeisen-DGTL/ecom-API/blob/master/payout.yaml

Описание API

Bзаимодействие осуществляется по протоколу HTTP с использованием методов GET/POST (в описании каждого запроса явно указан требуемый метод и адрес).

POST-запросы используют JSON-аргументы, GET-запросы работают со строками запросов.

API всегда возвращает ответ в формате JSON, независимо от типа запроса.

Стандартный ответ сервиса содержит код сообщения (code). Если в процессе обработки запроса произойдет логическая ошибка, API вернет описание ошибки (message).

Общие схемы работы

Одностадийная обработка

При получении запроса на выплату банк сразу проводит все проверки и в случае возможности проведения операции выполняет выплату.

Двухстадийная обработка

При двухстадийной обработке создается заявка на выплату, банк проверяет возможность проведения такой операции и возвращает результат. Далее ожидается подтверждение выплаты со стороны партнера. Данная схема взаимодействия подходит, когда требуется разделение создания заявки и ее согласования. Пример: менеджер создает заявку на выплату, руководитель или главный бухгалтер подтверждает выплату.

Авторизация

Авторизация производится посредством секретного ключа API (secretKey). Параметр авторизации указывается в заголовке Authorization, значение которого формируется как "Bearer secretKey".

Также настраивается список IP, с которых система будет пропускать запросы.

Работа с выплатами

Для реализации взаимодействия с партнёром Райффайзенбанк предоставляет API из следующих запросов:

  • получение списка банков, принимающих выплаты по СБП,
  • запрос на проведение выплаты,
  • запрос на cоздание заявки на выплату,
  • запрос на подтверждение заявки на выплату,
  • получение статуса выплаты.

Список банков, подключенных к приему выплат по СБП, Вы сможете посмотреть на сайте https://sbp.nspk.ru/participants/ в разделе "Оплата по QR".

Мы автоматически поддерживаем актуальный список и возвращаем его в запросе на получение банков-участников.

Получение списка банков Deprecated

Получение списка банков, принимающих выплаты по СБП

header Parameters
Authorization
required

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Получение списка банков

Получение списка банков, принимающих выплаты по СБП

header Parameters
Authorization
required

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Проведение выплаты

Проведение выплаты. Если в запросе переданы ФИО, по ним произойдет сверка данных с данными получателя в системе. Если данные не совпадут, платеж отобъется с ошибкой.

header Parameters
Authorization
required
Request Body schema: application/json
id
string <^[Aa-Zz0-9_-]+> non-empty

Уникальный идентификатор выплаты в вашей системе, используется как номер документа в выписке

account
required
string <= 20 characters

Счет, с которого будет происходить списание

amount
required
number

Сумма в рублях. Действует несколько лимитов от НСПК:

  1. Ограничение до 1000000 рублей (включительно) на одну операцию
  2. Ограничение до 2000000 рублей в сутки в пользу одного получателя Можно сделать 3 платежа на одинаковую сумму, например, по 400000. Главное, чтобы первые 2 платежа в общей сумме не превысили лимит в 1000000
currency
required
string = 3 characters
Value: "RUB"

Валюта платежа

paymentDetails
string [ 1 .. 140 ] characters

Назначение платежа. Значение попадает в выписку после системного префикса. Не может быть пустым или содержать только пробелы. Может сождержать:
• Символы латинского алфавита (A–Z и a–z) с десятичными кодами из диапазонов [065-090] и [097-122] в кодировке UTF-8;
• Символы русского алфавита (А-Я и а-я) с десятичными кодами из диапазона [1040-1103] в кодировке UTF-8;
• Цифры 0-9 с десятичными кодами из диапазона [048-057] в кодировке UTF-8;
• Специальные символы с десятичными кодами из диапазонов [032-047], [058-064], [091-096], [123-126] в кодировке UTF-8; - Символ «№» под номером 8470 в кодировке UTF-8

payoutMethod
required
string non-empty
Value: "SBP"

Тип выплаты

required
object
incomeTypeCode
string non-empty
Enum: "1" "2" "3" "4" "5"

Код вида дохода
Значения описаны тут

object

Дополнительные данные.
При создании заказа рекомендуется передавать параметры apiClient и apiClientVersion. Данная информация позволит Банку определять клиентское ПО, отлавливать баги и улучшать сервис.

Responses

Request samples

Content type
application/json
{
  • "id": "1404fhr7i272a2",
  • "account": "40700000000000000000",
  • "amount": 1110.01,
  • "currency": "RUB",
  • "paymentDetails": "Выплата от страховой компании",
  • "payoutMethod": "SBP",
  • "payoutParams": {
    },
  • "incomeTypeCode": "1",
  • "extra": {
    }
}

Response samples

Content type
application/json
{
  • "id": "1404fhr7i272a2",
  • "amount": 1110.01,
  • "currency": "RUB",
  • "payoutMethod": "SBP",
  • "payoutParams": {
    },
  • "incomeTypeCode": "1",
  • "extra": {
    },
  • "status": {
    },
  • "creationDate": "2019-07-11T17:45:13+03:00"
}

Создание заявки на выплату

Метод позволяет создавать заявку на выплату для двухстадийного взаимодействия. При создании заявки также проводятся все необходимые проверки на возможность провести платеж. Если в запросе переданы ФИО, по ним произойдет сверка данных с данными получателя в системе. Если данные не совпадут, заявка отобъется с ошибкой. Для дальнейшей работы с заявкой необходимо смотреть на ее статус. Успешное прохождение проверок при создании заявки не гарантирует успешное проведение платежа.

header Parameters
Authorization
required
Request Body schema: application/json
id
string <^[Aa-Zz0-9_-]+> non-empty

Уникальный идентификатор выплаты в вашей системе, используется как номер документа в выписке

account
required
string <= 20 characters

Счет, с которого будет происходить списание

amount
required
number

Сумма в рублях. Действует несколько лимитов от НСПК:

  1. Ограничение до 1000000 рублей (включительно) на одну операцию
  2. Ограничение до 2000000 рублей в сутки в пользу одного получателя Можно сделать 3 платежа на одинаковую сумму, например, по 400000. Главное, чтобы первые 2 платежа в общей сумме не превысили лимит в 1000000
currency
required
string = 3 characters
Value: "RUB"

Валюта платежа

paymentDetails
string [ 1 .. 140 ] characters

Назначение платежа. Значение попадает в выписку после системного префикса. Не может быть пустым или содержать только пробелы. Может сождержать:
• Символы латинского алфавита (A–Z и a–z) с десятичными кодами из диапазонов [065-090] и [097-122] в кодировке UTF-8;
• Символы русского алфавита (А-Я и а-я) с десятичными кодами из диапазона [1040-1103] в кодировке UTF-8;
• Цифры 0-9 с десятичными кодами из диапазона [048-057] в кодировке UTF-8;
• Специальные символы с десятичными кодами из диапазонов [032-047], [058-064], [091-096], [123-126] в кодировке UTF-8; - Символ «№» под номером 8470 в кодировке UTF-8

payoutMethod
required
string non-empty
Value: "SBP"

Тип выплаты

required
object
incomeTypeCode
string non-empty
Enum: "1" "2" "3" "4" "5"

Код вида дохода
Значения описаны тут

object

Дополнительные данные.
При создании заказа рекомендуется передавать параметры apiClient и apiClientVersion. Данная информация позволит Банку определять клиентское ПО, отлавливать баги и улучшать сервис.

Responses

Request samples

Content type
application/json
{
  • "id": "1404fhr7i272a2",
  • "account": "40700000000000000000",
  • "amount": 1110.01,
  • "currency": "RUB",
  • "paymentDetails": "Выплата от страховой компании",
  • "payoutMethod": "SBP",
  • "payoutParams": {
    },
  • "incomeTypeCode": "1",
  • "extra": {
    }
}

Response samples

Content type
application/json
{
  • "id": "1404fhr7i272a2",
  • "amount": 1110.01,
  • "currency": "RUB",
  • "payoutMethod": "SBP",
  • "payoutParams": {
    },
  • "incomeTypeCode": "1",
  • "extra": {
    },
  • "status": {
    },
  • "creationDate": "2019-07-11T17:45:13+03:00"
}

Получение информации по платежу

Получение информации по платежу.

path Parameters
id
required
string <^[Aa-Zz0-9_-]> <= 20 characters

id выплаты

header Parameters
Authorization
required

Responses

Response samples

Content type
application/json
Example
{
  • "id": "1404fhr7i272a2",
  • "amount": 1110.01,
  • "currency": "RUB",
  • "payoutMethod": "SBP",
  • "payoutParams": {
    },
  • "incomeTypeCode": "1",
  • "extra": {
    },
  • "status": {
    },
  • "creationDate": "2019-07-11T17:45:13+03:00"
}

Подтверждение выплаты

Подтверждение платежа при двухстадийной выплате.

path Parameters
id
required
string <^[Aa-Zz0-9_-]> <= 20 characters

id выплаты

header Parameters
Content-Type
required
string

application/json

Authorization
required

Responses

Создание пакета выплат

Данный метод позволяет произвести несколько выплат одним запросом. В одном пакете можно передать до 1000 выплат.

header Parameters
Authorization
required
Request Body schema: application/json
id
string

Идентификатор пакета

account
string

Номер счета

Array of objects

Массив выплат

Responses

Request samples

Content type
application/json
{
  • "id": "b-0001",
  • "account": "40700000000000000000",
  • "payouts": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "b-0001",
  • "account": "40700000000000000000",
  • "payouts": [
    ]
}

Получение статуса по пакету

Позволяет получить данные по пакету со статусами операций.

path Parameters
id
required
string

Идентификатор пакета

query Parameters
status
string
Enum: "IN_PROGRESS" "COMPLETED" "DECLINED" "PENDING"

Запрашиваемые статусы

header Parameters
Authorization
required

Responses

Response samples

Content type
application/json
{
  • "id": "b-0001",
  • "account": "40700000000000000000",
  • "payouts": [
    ]
}

Уведомления

Для информирования ТСП о проведенных операциях могут использоваться HTTP-уведомления на адрес, указанный в его настройках.

Для партнёра уведомление представляет собой входящий POST-запрос, который использует JSON-структуру.

Уведомление считается принятым, если получатель ответил на запрос кодом HTTP 200.

Ответы с любыми другими HTTP-кодами будут считаться невалидными.

Повторные попытки отправки будут проводиться в течение суток с нарастающим интервалом.

Для проверки подлинности уведомления к данным добавляется подпись в заголовке x-api-signature-sha256, полученная на основе общего секретного ключа и контрольной строки amount|id|statusValue|statusDate с помощью HMAC-SHA-256.

Уведомления отправляются с IP 193.28.44.23

Уведомление о платеже Webhook

Request Body schema: application/json
event
string

Тип уведомления

object

Request samples

Content type
application/json
{
  • "event": "payout",
  • "payout": {
    }
}

Настройка url для callback

Метод позволяет настроить url для получения уведомлений.

header Parameters
Authorization
required
Request Body schema: application/json
callbackUrl
required
string non-empty

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Реестр

Для подключения отправки реестров необходимо написать на ecom@raiffeisen.ru.

Реестры по платежам отправляются на ежедневной основе.

В случае отсуствия операций за день, реестр на следующий день не отправляется.

Формат реестра:

Наименование колонки Значение
Мерчант Идентификатор в системе СБП
Дата операции МСК Дата и время проведения операции (МСК)
Тип Тип операции
id заказа Id заказа в системе партнера (id)
Назначение платежа Назначение платежа (paymentDetails)
id клиента Маскированный код получателя
Сумма Сумма транзакции
Комиссия Комиссия по транзакции
Дополнительные поля Дополнительная информация (extra)
id операции НСПК Идентификатор операции в системе НСПК

Пример реестра

Выписка

Выписку можно выгрузить в банк-клиенте в разных форматах. Пример выписки

В назначении платежа есть системный префикс: номер проводки, тип операции, идентификатор мерчанта НСПК.

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

Если передан paymentDetails, то назначение платежа в выписке будет формироваться как:

  • {номер проводки} IPS B2C {часть Id мерчанта} {paymentDetails}
    Иначе:
  • {номер проводки} IPS B2C {часть Id мерчанта} {Id получателя в НСПК},
    где Id получателя в НСПК может в виде номера телефона, ИНН или E-mail.

    Пример назначения платежа: 11832614 IPS B2C 39843 Платеж физлицу

09.09.2021

  • Исправлена длина параметра paymentDetails

13.07.2022

  • Добавлена возможность пакетного проведения выплат

29.07.2022

  • Изменены хосты :
  • Боевой с e-commerce.raiffeisen.ru на pay.raif.ru
  • Тествый c ecom.test.raiffeisen.ru на pay-test.raif.ru

29.03.2023

  • Внесены ограничения поля paymentDetails