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 samples

Content type

application/json

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

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

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

header Parameters

Authorization

required

string

Bearer secretKey

Responses

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

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

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

Получение информации по выплате Deprecated

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

path Parameters

required

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

id выплаты

header Parameters

Authorization

required

string

Bearer secretKey

Responses

Response samples

Content type

application/json

Example

COMPLETED

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

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

Получение информации по выплате. Метод позволяет сверить PAM получателя с ФИО, указанным в запросе на создание выплаты. API для данного сценария может быть расширяемым.

path Parameters

required

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

id выплаты

header Parameters

Authorization

required

string

Bearer secretKey

Responses

Response samples

Content type

application/json

Example

COMPLETED

{"id": "1404fhr7i272a22",
"amount": 1110.01,
"currency": "RUB",
"payoutMethod": "SBP",
"payoutParams": {"phone": "79191234567",
"bankAlias": "RAIFFEISEN",
"firstName": "Иван",
"middleName": "Иванович",
"lastName": "Иванов",
"inn": 123456789101
},
"receiverPam": "Иван Иванович И",
"incomeTypeCode": "1",
"extra": {"apiClient": "Payout Software",
"apiClientVersion": "1.0.0"
},
"status": {"value": "COMPLETED",
"date": "2025-02-11T12:58:44+03:00"
},
"creationDate": "2025-02-11T12:58:44+03:00"
}

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

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

header Parameters

Authorization

required

string

Bearer secretKey

Request Body schema: application/json

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

Responses

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

Request samples

Payload

Content type

application/json

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

Response samples

Content type

application/json

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

Реестр

Для подключения отправки реестров необходимо написать на 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