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

Download OpenAPI specification:Download

Свои предложения и идеи о документации можно оставить в репозитории по адресу: 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

string

Bearer secretKey

Responses

Response Schema: application/json

Array (non-empty)

alias	string [ 1 .. 255 ] characters Алиас банка
name	string [ 1 .. 255 ] characters Наименование банка

Response samples

Content type

application/json

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

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

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

header Parameters

Authorization

required

string

Bearer secretKey

Responses

Response Schema: application/json

Array (non-empty)

alias	string [ 1 .. 255 ] characters Алиас банка
name	string [ 1 .. 255 ] characters Наименование банка
bankId	string Идентификатор банка

Response samples

Content type

application/json

[{"alias": "RAIFFEISEN",
"name": "Райффайзенбанк",
"bankId": "100000000007"
},
{"alias": "TINKOFF",
"name": "Тинькофф Банк",
"bankId": "100000000004"
},
{"alias": "YANDEX BANK",
"name": "Яндекс Банк",
"bankId": "100000000150"
}
]

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

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

header Parameters

Authorization

required

string

Bearer secretKey

Request Body schema: application/json

id	string <^[Aa-Zz0-9_-]+> non-empty Уникальный идентификатор выплаты в вашей системе, используется как номер документа в выписке
account required	string <= 20 characters Счет, с которого будет происходить списание
amount required	number Сумма в рублях. Действует несколько лимитов от НСПК: Ограничение до 1000000 рублей (включительно) на одну операцию Ограничение до 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

Response Schema: application/json

id	string Уникальный идентификатор выплаты в вашей системе, используется как номер документа в выписке
amount	number Сумма в рублях
currency	string 3 characters Value: "RUB" Валюта платежа
payoutMethod	string non-empty Value: "SBP" Тип выплаты
	object
incomeTypeCode	string non-empty Enum: 1 2 3 4 5 Код вида дохода Значения описаны тут
extra	object Дополнительные данные. При создании заказа рекомендуется передавать параметры apiClient и apiClientVersion. Данная информация позволит Банку определять клиентское ПО, отлавливать баги и улучшать сервис.
	object
creationDate	string non-empty Дата создания

Request samples

Payload

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": {"apiClient": "Payout Software",
"apiClientVersion": "1.0.0"
}
}

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": {"apiClient": "Payout Software",
"apiClientVersion": "1.0.0"
},
"status": {"value": "IN_PROGRESS",
"date": "2019-07-11T17:45:13+03:00"
},
"creationDate": "2019-07-11T17:45:13+03:00"
}

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

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

header Parameters

Authorization

required

string

Bearer secretKey

Request Body schema: application/json

id	string <^[Aa-Zz0-9_-]+> non-empty Уникальный идентификатор выплаты в вашей системе, используется как номер документа в выписке
account required	string <= 20 characters Счет, с которого будет происходить списание
amount required	number Сумма в рублях. Действует несколько лимитов от НСПК: Ограничение до 1000000 рублей (включительно) на одну операцию Ограничение до 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

Response Schema: application/json

id	string Уникальный идентификатор выплаты в вашей системе, используется как номер документа в выписке
amount	number Сумма в рублях
currency	string 3 characters Value: "RUB" Валюта платежа
payoutMethod	string non-empty Value: "SBP" Тип выплаты
	object
incomeTypeCode	string non-empty Enum: 1 2 3 4 5 Код вида дохода Значения описаны тут
extra	object Дополнительные данные. При создании заказа рекомендуется передавать параметры apiClient и apiClientVersion. Данная информация позволит Банку определять клиентское ПО, отлавливать баги и улучшать сервис.
	object
creationDate	string non-empty Дата создания

Request samples

Payload

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": {"apiClient": "Payout Software",
"apiClientVersion": "1.0.0"
}
}

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": {"apiClient": "Payout Software",
"apiClientVersion": "1.0.0"
},
"status": {"value": "PENDING",
"date": "2019-07-11T17:45:13+03:00"
},
"creationDate": "2019-07-11T17:45:13+03:00"
}

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

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

path Parameters

required

string <^[Aa-Zz0-9_-]> <= 20 characters

id выплаты

header Parameters

Authorization

required

string

Bearer secretKey

Responses

Response Schema: application/json

id	string Уникальный идентификатор выплаты в вашей системе, используется как номер документа в выписке
amount	number Сумма в рублях
currency	string 3 characters Value: "RUB" Валюта платежа
payoutMethod	string non-empty Value: "SBP" Тип выплаты
	object
incomeTypeCode	string non-empty Enum: 1 2 3 4 5 Код вида дохода Значения описаны тут
extra	object Дополнительные данные. При создании заказа рекомендуется передавать параметры apiClient и apiClientVersion. Данная информация позволит Банку определять клиентское ПО, отлавливать баги и улучшать сервис.
	object
creationDate	string non-empty Дата создания

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": {"apiClient": "Payout Software",
"apiClientVersion": "1.0.0"
},
"status": {"value": "COMPLETED",
"date": "2019-07-11T17:45:13+03:00"
},
"creationDate": "2019-07-11T17:45:13+03:00"
}

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

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

path Parameters

required

string <^[Aa-Zz0-9_-]> <= 20 characters

id выплаты

header Parameters

Content-Type required	string application/json
Authorization required	string Bearer secretKey

Responses

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

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

header Parameters

Authorization

required

string

Bearer secretKey

Request Body schema: application/json

id	string Идентификатор пакета
account	string Номер счета
	Array of objects[ items ] Массив выплат

Responses

Response Schema: application/json

id	string Идентификатор пакета
account	string Номер счета
	Array of objects (payoutResponse) [ items ] Массив выплат

Request samples

Payload

Content type

application/json

{"id": "b-0001",
"account": "40700000000000000000",
"payouts": [{"id": "1404fhr7i272a2",
"amount": 1110.01,
"currency": "RUB",
"paymentDetails": "Выплата от страховой компании",
"payoutMethod": "SBP",
"payoutParams": {"phone": "79191234567",
"bankAlias": "RAIFFEISEN",
"firstName": "Иван",
"middleName": "Иванович",
"lastName": "Иванов",
"inn": 123456789101
},
"incomeTypeCode": "1",
"extra": {"apiClient": "Payout Software",
"apiClientVersion": "1.0.0"
}
},
{"id": "120445r7i272a2",
"amount": 500,
"currency": "RUB",
"paymentDetails": "Выплата от страховой компании",
"payoutMethod": "SBP",
"payoutParams": {"phone": "79191234567",
"bankAlias": "VTB",
"firstName": "Иван",
"middleName": "Иванович",
"lastName": "Иванов",
"inn": 123456789101
},
"incomeTypeCode": "1",
"extra": {"apiClient": "Payout Software",
"apiClientVersion": "1.0.0"
}
}
]
}

Response samples

Content type

application/json

{"id": "b-0001",
"account": "40700000000000000000",
"payouts": [{"id": "1404fhr7i272a2",
"amount": 1110.01,
"currency": "RUB",
"payoutMethod": "SBP",
"payoutParams": {"phone": "79191234567",
"bankAlias": "RAIFFEISEN",
"firstName": "Иван",
"middleName": "Иванович",
"lastName": "Иванов",
"inn": 123456789101
},
"incomeTypeCode": "1",
"extra": {"apiClient": "Payout Software",
"apiClientVersion": "1.0.0"
},
"status": {"value": "IN_PROGRESS",
"date": "2019-07-11T17:45:13+03:00"
},
"creationDate": "2019-07-11T17:45:13+03:00"
},
{"id": "120445r7i272a2",
"amount": 500,
"currency": "RUB",
"payoutMethod": "SBP",
"payoutParams": {"phone": "79191234567",
"bankAlias": "VTB",
"firstName": "Иван",
"middleName": "Иванович",
"lastName": "Иванов",
"inn": 123456789101
},
"incomeTypeCode": "1",
"extra": {"apiClient": "Payout Software",
"apiClientVersion": "1.0.0"
},
"status": {"value": "IN_PROGRESS",
"date": "2019-07-11T17:45:13+03:00"
},
"creationDate": "2019-07-11T17:45:13+03:00"
}
]
}

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

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

path Parameters

required

string

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

query Parameters

status

string

Enum: "IN_PROGRESS" "COMPLETED" "DECLINED" "PENDING"

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

header Parameters

Authorization

required

string

Bearer secretKey

Responses

Response Schema: application/json

id	string Идентификатор пакета
account	string Номер счета
	Array of objects (payoutResponse) [ items ] Массив выплат

Response samples

Content type

application/json

{"id": "b-0001",
"account": "40700000000000000000",
"payouts": [{"id": "1404fhr7i272a2",
"amount": 1110.01,
"currency": "RUB",
"payoutMethod": "SBP",
"payoutParams": {"phone": "79191234567",
"bankAlias": "RAIFFEISEN",
"firstName": "Иван",
"middleName": "Иванович",
"lastName": "Иванов",
"inn": 123456789101
},
"incomeTypeCode": "1",
"extra": {"apiClient": "Payout Software",
"apiClientVersion": "1.0.0"
},
"status": {"value": "COMPLETED",
"date": "2019-07-11T17:45:13+03:00"
},
"creationDate": "2019-07-11T17:45:13+03:00"
},
{"id": "120445r7i272a2",
"amount": 500,
"currency": "RUB",
"payoutMethod": "SBP",
"payoutParams": {"phone": "79191234567",
"bankAlias": "VTB",
"firstName": "Иван",
"middleName": "Иванович",
"lastName": "Иванов",
"inn": 123456789101
},
"incomeTypeCode": "1",
"extra": {"apiClient": "Payout Software",
"apiClientVersion": "1.0.0"
},
"status": {"value": "DECLINED",
"declineReason": "RECEIVER_ACCOUNT_ERROR",
"date": "2019-07-11T17:45:13+03:00"
},
"creationDate": "2019-07-11T17:45:13+03:00"
}
]
}

Уведомления

Для информирования ТСП о проведенных операциях могут использоваться 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

Payload

Content type

application/json

{"event": "payout",
"payout": {"id": "p210730t2jboNkN0ft1",
"amount": 0.01,
"currency": "RUB",
"payoutMethod": "SBP",
"payoutParams": {"phone": "79191234567",
"bankAlias": "RAIFFEISEN",
"bankId": 100000000007,
"firstName": "Иван",
"middleName": "Иванович",
"lastName": "Иванов",
"inn": "123456789101"
},
"extra": {"apiClient": "Payout Software",
"apiClientVersion": "1.0.0"
},
"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

Authorization

required

string

Bearer secretKey

Request Body schema: application/json

callbackUrl

required

string non-empty

Responses

Response Schema: application/json

callbackUrl

required

string non-empty

Request samples

Payload

Content type

application/json

{"callbackUrl": "https://yoururl.ru"
}

Response samples

Content type

application/json

{"callbackUrl": "https://yoururl.ru"
}

Реестр

To receive a registry, you need write request to enable the functionaly to ecom@raiffeisen.ru

Transaction registers are sent on a daily basis.

If there are no transactions for the day, the register is not sent the next day.

Registry format:

Column name	Value
Мерчант	Merchant
Дата операции МСК	Operation datetime (Moscow)
Тип	Operation type
id заказа	Operation id in partner system
id возврата	Not used
Комментарий	Comment
Способ оплаты	Payment method
Данные оплаты	Payment data
id клиента	Masked recipient code
Сумма	Amount
Комиссия	Comission
Дополнительные поля	Additional fields

Registry sample

Выписка

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

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

В примере выписки указаны стандартные назначения платежа. Вы можете его изменить, для этого необходимо при выплате передавать параметр 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