Raiff logo
Documentation Powered by ReDoc

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

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

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

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

extra
object

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

object
creationDate
string non-empty

Дата создания

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

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

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

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

extra
object

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

object
creationDate
string non-empty

Дата создания

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": {
    • "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
id
required
string <^[Aa-Zz0-9_-]> <= 20 characters

id выплаты

header Parameters
Authorization
required

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

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

extra
object

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

object
creationDate
string non-empty

Дата создания

Response samples

Content type
application/json
Example
COMPLETED
COMPLETED
DECLINED
{
  • "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
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[ items ]

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

Responses

Response Schema: application/json
id
string

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

account
string

Номер счета

Array of objects (payoutResponse) [ items ]

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

Request samples

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
id
required
string

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

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

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

header Parameters
Authorization
required

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