Download OpenAPI specification:Download
Свои предложения и идеи о документации можно оставить в репозитории по адресу: https://github.com/Raiffeisen-DGTL/ecom-API/blob/master/sbp.yaml
Для приема СБП-платежей оставьте заявку на сайте.
Райффайзенбанк выполнит регистрацию. После завершения процесса вы будете оповещены по электронной почте.
По закону от 22.05.2003 № 54–ФЗ "О применении контрольно-кассовой техники при осуществлении расчетов в Российской Федерации" при оплате товаров, работ или услуг необходимо формировать фискальный чек и отправлять его в налоговую с помощью кассы.
Райффайзенбанк предоставляет возможность фискализировать чеки через API банка.
B случае если прием платежей планируется на сайте или в мобильном приложении, рекомендуем использовать протокол с отображением QR-кода на нашей форме.
Вы можете предложить клиенту привязать оплату по СБП к программе лояльности или к аккаунту в вашем сервисе. Для этого вы можете сгенерировать QR-код и отобразить его клиенту либо перенаправить его на специальную ссылку, которая есть в ответе на запрос генерации QR-кода на подписку.
После по уникальному идентификатору подписки вы можете обращаться за безакцептным списанием средств с клиента за ваши товары и услуги.
Также есть схема, когда одним запросом создается QR-код на получение оплаты и заведение подписки.
В данном случае клиент проводит оплату, после чего ему отображается окно с предложением подключения подписки.
Клиент может провести оплату, но отказаться от подписки. Также клиент может провести оплату из приложения банка, который не подключен к сервису подписок.
Bзаимодействие осуществляется по протоколу HTTP с использованием методов GET/POST/DELETE (в описании каждого запроса явно указан требуемый метод и адрес).
POST-запрос использует JSON-аргументы, GET и DELETE-запросы работают со строками запросов.
API всегда возвращает ответ в формате JSON, независимо от типа запроса.
Ответ любого метода содержит код сообщения (code). Если в процессе обработки любого запроса произойдет логическая ошибка, API вернет дополнительно описание ошибки (message).
Запросы, связанные с получением данных по платежу и управлением платежами, авторизуются посредством секретного ключа API (secretKey). Параметр авторизации указывается в заголовке Authorization, значение которого формируется как "Bearer secretKey".
Для получения тестовых данных для интеграции необходимо заполнить анкету на pay.raif.ru.
Посмотреть боевой sbpMerchantId и сгенерировать ключи можно в личном кабинете во вкладке "Прием платежей".
Секретный ключ необходимо хранить в доверенной среде, так как по нему возможно проведение возвратов.
При работе в мобильной версии сайта или приложении необходимо перенаправлять клиента по URL из параметра payload.
У клиента откроется мобильное приложение банка или список для выбора банка.
Для полного цикла тестирования оплаты Райффайзенбанк предоставляет возможность использования демо-приложения для сканирования QR-кода от имени покупателя по адресу: https://pay.raif.ru/pay/rfuture/
Указанный адрес можно открыть в браузере любого устройства, где есть камера. Никакого дополнительного софта/плагинов устанавливать не нужно. Далее нажать на значок СБП (при необходимости разрешить браузеру доступ к камере) и поднести к ней изображение QR-кода. Если камера не открылась, проверьте, что в адресе указан протокол HTTPS.
Для реализации взаимодействия с партнёром Райффайзенбанк предоставляет API из следующих запросов:
Регистрация QR-кода выполяется без авторизации, что позволяет сгенерировать его на сайте или в приложении. Данный метод позволяет генерировать как статические QR-коды, так и динамические QR-коды и кассовую ссылку СБП (QRVariable) для каждой кассы. Также с помощью данного метода вы можете сгенерировать QR-код для оплаты с подпиской.
При каждом новом запросе будет возвращаться новый QR.
Тестовые QR можно оплатить только с помощью тестового приложения.
Content-Type required | string application/json |
qrType required | string Тип QR-кода QRStatic QRStatic QRDynamic QRVariable |
account | number <= 20 Счет для зачисления. Параметр используется, если необходимо разносить платежи на разные счета |
additionalInfo | string <= 140 characters Дополнительная информация, заполняемая по желанию партнёра при генерации QR-кода. Может быть доступна для пользователя в зависимости от банка |
amount | number Сумма в рублях |
currency | string 3 characters Value: "RUB" Валюта платежа. Обязательно для заполнения, если заполнена сумма |
order required | string [ 1 .. 40 ] characters ^[A-z0-9-_.] Уникальный идентификатор заказа в системе партнёра. Рекомендуем использовать длинный формат без возможности перебора. Например, использовать формат UUID v4 |
paymentDetails | string <= 185 characters Назначение платежа. Необязательно для заполнения |
qrExpirationDate | string <YYYY-MM-DD ТHH24:MM:SS±HH:MM / +nM / +nm> Срок действия QR-кода |
sbpMerchantId required | string <= 12 characters Идентификатор зарегистрированного партнёра в СБП |
{- "account": 40700000000000000000,
- "qrType": "QRVariable",
- "sbpMerchantId": "MA0000000552"
}
{- "qrId": "AD1F2CD7212E48FA919AB52EF0AEFB33",
- "subscriptionId": "120059"
}
Регистрация QR-кода выполяется без авторизации, что позволяет сгенерировать его на сайте или приложении. Данный метод позволяет генерировать как статические QR-коды, так и динамические QR-коды. Также с помощью данного метода вы можете сгенерировать QR-код для оплаты с подпиской.
Тестовые QR можно оплатить только нашим тестовым приложением.
Content-Type required | string application/json |
qrType required | string Тип QR-кода QRStatic QRStatic QRDynamic |
account | number <= 20 Счет для зачисления. Параметр используется, если необходимо разносить платежи на разные счета |
additionalInfo | string <= 140 characters Дополнительная информация, заполняемая по желанию партнёра при генерации QR-кода. Может быть доступна для пользователя в зависимости от банка |
amount | number Сумма в рублях |
currency | string 3 characters Value: "RUB" Валюта платежа. Обязательно для заполнения, если заполнена сумма |
order required | string [ 1 .. 40 ] characters ^[A-z0-9-_.] Уникальный идентификатор заказа в системе партнёра. Рекомендуем использовать длинный формат без возможности перебора. Например, использовать формат UUID v4 |
paymentDetails | string <= 185 characters Назначение платежа. Необязательно для заполнения |
qrExpirationDate | string <YYYY-MM-DD ТHH24:MM:SS±HH:MM / +nM / +nm> Срок действия QR-кода |
sbpMerchantId required | string <= 12 characters Идентификатор зарегистрированного партнёра в СБП |
{- "account": 40700000000000000000,
- "additionalInfo": "Доп. информация",
- "amount": 1110.11,
- "currency": "RUB",
- "order": "1-22-333",
- "paymentDetails": "Назначение платежа",
- "qrType": "QRDynamic",
- "qrExpirationDate": "2023-07-22T09:14:38+03:00",
- "sbpMerchantId": "MA0000000552"
}
{- "code": "SUCCESS",
- "qrId": "AD1F2CD7212E48FA919AB52EF0AEFB33",
- "subscriptionId": "120059"
}
Метод позволяет отменить ранее созданный QR. QRDynamic можно отменить только до момента его оплаты.
qrId required | string Уникальный идентификатор QR |
Authorization required | string |
curl --location --request DELETE 'https://test.ecom.raiffeisen.ru/api/sbp/v2/qrs/ADAC306DDBF443CA94EBE3FA85CA4872' \ --header 'Authorization: Bearer eyJ0eXA***'
Метод позволяет получить данные по зарегистрированному ранее QR-коду
qrId required | string Уникальный идентификатор QR |
Authorization required | string |
curl --location --request GET 'https://test.ecom.raiffeisen.ru/api/sbp/v2/qrs/ADAC306DDBF443CA94EBE3FA85CA4872' \ --header 'Authorization: Bearer eyJ0eXA***'
{- "qrId": "AD100004BAL7227F9BNP6KNE007J9B3K",
- "qrStatus": "NEW",
- "qrExpirationDate": "2023-07-22T09:14:38+03:00",
}
Метод позволяет получить данные по зарегистрированному ранее QR-коду
qrId required | string Уникальный идентификатор QR |
Authorization required | string |
curl --location --request GET 'https://test.ecom.raiffeisen.ru/api/sbp/v1/qr/AS6E5A7F9E3A4E648C536EC930AECDF6/info' \ --header 'Authorization: Bearer eyJ0eXA***'
{- "code": "SUCCESS",
- "qrId": "AD100004BAL7227F9BNP6KNE007J9B3K",
}
Метод позволяет получить данные по платежу по QR
qrId required | string Уникальный идентификатор QR |
Authorization required | string |
curl --location --request GET 'https://test.ecom.raiffeisen.ru/api/sbp/v1/qr/AS6E5A7F9E3A4E648C536EC930AECDF6/payment-info' \ --header 'Authorization: Bearer eyJ0eXA***'
{- "additionalInfo": "Доп. информация",
- "paymentPurpose": "Назначение платежа",
- "amount": 1110.11,
- "code": "SUCCESS",
- "createDate": "2020-01-31T09:14:38.107227+03:00",
- "currency": "RUB",
- "merchantId": 123,
- "order": "282a60f8-dd75-4286-bde0-af321dd081b3",
- "paymentStatus": "SUCCESS",
- "qrId": "AD100051KNSNR64I98CRUJUASC9M72QT",
- "sbpMerchantId": "MA0000000552",
- "transactionDate": "2019-07-11T17:45:13.109227+03:00",
- "transactionId": 23,
- "qrExpirationDate": "2020-01-15T13:00:40+03:00"
}
Метод позволяет осуществлять полный и частичный возврат по QR
Content-Type required | string application/json |
Authorization required | string |
amount required | number Сумма возврата в рублях |
order required | string <= 40 characters Уникальный идентификатор заказа в системе партнёра |
paymentDetails | string <= 140 characters Назначение платежа |
refundId required | string <= 40 characters Уникальный идентификатор запроса на возврат в системе партнера |
transactionId | number Идентификатор операции платежа в Райффайзенбанке, обязателен только для QRStatic |
{- "amount": 150,
- "order": "test_order_007",
- "paymentDetails": "Test",
- "refundId": "test_refundId_007"
}
{- "code": "SUCCESS",
- "amount": 150,
- "refundStatus": "IN_PROGRESS"
}
Получение информации по возврату
refundId required | string Уникальный идентификатор запроса на возврат в системе партнера |
Authorization required | string |
curl --location --request GET 'https://test.ecom.raiffeisen.ru/api/sbp/v1/refund/111112222200046' \ --header 'Authorization: Bearer eyJ0eXA***'
{- "code": "SUCCESS",
- "amount": 150,
- "refundStatus": "COMPLETED"
}
Для реализации взаимодействия с QRVariable (Кассовой ссылкой) Райффайзенбанк предоставляет API из следующих запросов:
Данный тип QR позволяет сгенерировать статическое изображение QR под каждую кассы, и далее под каждую продажу создавать заказ с указанием QRid этой кассы.
Схема взаимодействия приведена выше.
Метод позволяет создать новый заказ без возможности его редактирования. Для связки заказа с QR-кодом (с типом QRVariable) необходимо также передать блок с данными о QR в теле запроса. Необходимо передать тот идентификатор QR-кода, который был получен в ответе на запрос регистрации QR-кода.
Authorization required | string |
Content-Type required | string application/json |
id | string [ 1 .. 40 ] characters ^[A-z0-9-_.] Уникальный идентификатор заказа. Рекомендуется использовать формат, не допускающий возможность перебора, например, UUID v4 |
amount required | number <float> Сумма заказа |
comment | string Комментарий к заказу |
extra | object Дополнительные поля |