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".

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

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

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

header Parameters
Authorization:
required

Responses

Response samples

Content type
application/json
[
  • {
    • "alias": "RAIFFEISEN",
    • "name": "Райффайзенбанк"
    },
  • {
    • "alias": "TINKOFF",
    • "name": "Тинькофф"
    },
  • {
    • "alias": "VTB",
    • "name": "ВТБ"
    }
]

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

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

header Parameters
Content-type:
required
string

application/json

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

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

account
required
string <= 20 characters

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

amount
required
number

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

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

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

paymentDetails
string [ 1 .. 140 ] characters

Назначение платежа

payoutMethod
required
string non-empty
Value: "SBP"

Тип выплаты

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

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

extra
object

Дополнительные данные

Responses

Request samples

Content type
application/json
{
  • "id": "1404fhr7i272a2",
  • "account": "40700000000000000000",
  • "amount": 1110.01,
  • "currency": "RUB",
  • "paymentDetails": "Выплата от страховой компании",
  • "payoutMethod": "SBP",
  • "payoutParams": {
    • "phone": "79191234567",
    • "bankAlias": "RAIFFEISEN",
    • "firstName": "Петр",
    • "middleName": "Петрович",
    • "lastName": "Петров",
    • "inn": 123456789101
    },
  • "incomeTypeCode": "1",
  • "extra": {
    • "contract": "1234567/89012"
    }
}

Response samples

Content type
application/json
{
  • "id": "1404fhr7i272a2",
  • "amount": 1110.01,
  • "currency": "RUB",
  • "payoutMethod": "SBP",
  • "payoutParams": {
    • "phone": "79191234567",
    • "bankAlias": "RAIFFEISEN",
    • "firstName": "Петр",
    • "middleName": "Петрович",
    • "lastName": "Петров",
    • "inn": 123456789101
    },
  • "incomeTypeCode": "1",
  • "extra": {
    • "contract": "1234567/89012"
    },
  • "status": {
    • "value": "IN_PROGRESS",
    • "date": "2019-07-11T17:45:13+03:00"
    },
  • "creationDate": "2019-07-11T17:45:13+03:00"
}

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

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

header Parameters
Content-type:
required
string

application/json

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

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

account
required
string <= 20 characters

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

amount
required
number

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

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

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

paymentDetails
string [ 1 .. 140 ] characters

Назначение платежа

payoutMethod
required
string non-empty
Value: "SBP"

Тип выплаты

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

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

extra
object

Дополнительные данные

Responses

Request samples

Content type
application/json
{
  • "id": "1404fhr7i272a2",
  • "account": "40700000000000000000",
  • "amount": 1110.01,
  • "currency": "RUB",
  • "paymentDetails": "Выплата от страховой компании",
  • "payoutMethod": "SBP",
  • "payoutParams": {
    • "phone": "79191234567",
    • "bankAlias": "RAIFFEISEN",
    • "firstName": "Петр",
    • "middleName": "Петрович",
    • "lastName": "Петров",
    • "inn": 123456789101
    },
  • "incomeTypeCode": "1",
  • "extra": {
    • "contract": "1234567/89012"
    }
}

Response samples

Content type
application/json
{
  • "id": "1404fhr7i272a2",
  • "amount": 1110.01,
  • "currency": "RUB",
  • "payoutMethod": "SBP",
  • "payoutParams": {
    • "phone": "79191234567",
    • "bankAlias": "RAIFFEISEN",
    • "firstName": "Петр",
    • "middleName": "Петрович",
    • "lastName": "Петров",
    • "inn": 123456789101
    },
  • "incomeTypeCode": "1",
  • "extra": {
    • "contract": "1234567/89012"
    },
  • "status": {
    • "value": "PENDING",
    • "date": "2019-07-11T17:45:13+03:00"
    },
  • "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": {
    • "phone": "79191234567",
    • "bankAlias": "RAIFFEISEN",
    • "firstName": "Петр",
    • "middleName": "Петрович",
    • "lastName": "Петров",
    • "inn": 123456789101
    },
  • "incomeTypeCode": "1",
  • "extra": {
    • "contract": "1234567/89012"
    },
  • "status": {
    • "value": "COMPLETED",
    • "date": "2019-07-11T17:45:13+03:00"
    },
  • "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

Уведомления

Для информирования ТСП о проведенных операциях могут использоваться 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": {
    • "id": "p210730t2jboNkN0ft1",
    • "amount": 0.01,
    • "currency": "RUB",
    • "payoutMethod": "SBP",
    • "payoutParams": {
      • "phone": "79191234567",
      • "bankAlias": "RAIFFEISEN",
      • "firstName": "Петр",
      • "middleName": "Петрович",
      • "lastName": "Петров",
      • "inn": "123456789101"
      },
    • "extra": {
      • "contract": "1234567/89012"
      },
    • "status": {
      • "value": "COMPLETED",
      • "date": "2021-07-30T14:16:32+03:00"
      },
    • "creationDate": "2021-07-30T14:16:31+03:00",
    • "incomeTypeCode": "1"
    }
}

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

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

header Parameters
Content-type:
required
string

application/json

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)
id возврата Не используется
Комментарий Комментарий к заказу
Способ оплаты Instant Payment QR
Данные оплаты PAYOUT
id клиента Маскированный код получателя
Сумма Сумма транзакции
Комиссия Комиссия по транзакции
Дополнительные поля Дополнительная информация (Пока не используется)

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

Выписка

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

Пример выписки

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

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

09.09.2021

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