Требования к применению Виджета СБП
При организации приема платежей через СБП в мобильных браузерах или нативных приложениях требуется использование одного из решений:
• API Виджета СБП,
• СБП онлайн-виджет.
Правила отображения перечня банков
Нельзя изменять:
• Порядок банков (кроме топ-3 выбранных клиентом);
• Названия и логотипы;
• Ссылки для перехода в банковские приложения.
Обязательно:
• Сохранять функцию поиска по банкам;
• Для кэшированных данных:
• Использовать только актуальные данные (≤ 24 часов);
• При ошибке запроса — брать последние рабочие данные.
Разрешено:
• Показывать первыми 3 банка, которые клиент выбирал ранее.
API Виджета СБП
Скачать спецификацию OpenAPIФайл может быть использован как для ознакомления с методами API, так и для генерации базового кода для работы с API на удобном языке программирования с помощью утилиты Swagger Codegen или онлайн-сервиса Swagger Editor.
Базовый URL API:
https://widget.cbrpay.ru/Общая информация
API получения списков: – Участников СБП (Банков Плательщика) – Участников платформы Цифровой рубль для формирования виджета на стороне Банка или Агента ТСП. Сокращения: СБП – Система Быстрых Платежей ЦР – Цифровой Рубль Банка России
Инструкция по использованию API Виджета СБП
1. Метод /v2/members «Получение списка участников для платежа по Payload» используется в момент совершения платежа
Сценарий использования:
Выбор способа оплаты:
• Клиент - плательщик в мобильном браузере или нативном приложении ТСП выбирает оплату через СБП.
Получение платежной ссылки (Payload)
• ТСП отправляет запрос в свой банк и получает платежную ссылку – Payload. Примеры Payload:
- С параметрами:https://qr.nspk.ru/AS10003P3RH0LJ2A9ROO038L6NT5RU1M?type=01&bank=000000000001&sum=10000&cur=RUB&crc=F3D0
- Без параметров:https://qr.nspk.ru/AS10003P3RH0LJ2A9ROO038L6NT5RU1M
- С параметрами:
Запрос списка банков:
• ТСП выполняет GET-запрос к/v2/members, используя полученный Payload.
Отображение списка банков:
• На экран выводится список банков из ответа API.
Выбор банка и редирект:
• Клиент выбирает нужный банк.
• ТСП перенаправляет клиента по ссылке из ответа (url), соответствующей выбранному банку.
2. Метод /v2/members/{type} – Получение списка участников для кэширования
Сценарий использования:
Кэширование списка банков:
• ТСП не реже 1 раза в сутки запрашивает список банков через GET /v2/members/{type}. Где {type} – это тип операции
Получение платежной ссылки (Payload):
• ТСП отправляет запрос в свой банк и получает платежную ссылку – Payload. Примеры Payload:
- С параметрами:https://qr.nspk.ru/AS10003P3RH0LJ2A9ROO038L6NT5RU1M?type=01&bank=000000000001&sum=10000&cur=RUB&crc=F3D0где:
QRC_ID: AS10003P3RH0LJ2A9ROO038L6NT5RU1M
QUERY_STRING: ?type=01&bank=000000000001&sum=10000&cur=RUB&crc=F3D0
- Без параметров QUERY_STRING:https://qr.nspk.ru/AS10003P3RH0LJ2A9ROO038L6NT5RU1M
- С параметрами:
Формирование ссылок:
• Из полученного Payload извлекается QRC_ID и QUERY_STRING (если имеется) и подставляется в шаблон ссылки (url), полученный методом GET /v2/members/{type}.
Отображение списка банков:
• На экран выводится список банков с готовыми ссылками.
Выбор банка и редирект:
• Клиент выбирает банк.
• ТСП перенаправляет клиента по сформированной ссылке.
Методы
Список Участников СБП по Payload (v1)
Метод для получения полного списка Участников СБП (Банков Плательщика) по операциям C2B, C2G, B2B или С2С, и формирования Виджета СБП на стороне Участника СБП – Банка Получателя или Агента ТСП, или ТСП.
HEADER PARAMETERS
https://qr.nspk.ru/AS1000670LSS7DN18SJQDNP4B05KLJL2?type=01&bank=100000000001&sum=10000&cur=RUB&crc=C08BОтветы
200Успешный ответ
{ version: string enum enum: 1.0 platform: string enum enum: ios | android | desktop type: string enum enum: qr | sub | b2b | c2g | c2c | b2c members: [{ name: string logo: string url: string }]}400Некорректный запрос
{ message: string}404Данные не найдены
{ message: string}Примеры ответов
{
"version": "1.0",
"platform": "desktop",
"type": "qr",
"members": [
{
"name": "Банк",
"logo": "https://qr.nspk.ru/proxyapp/logo/bank000000000001.png",
"url": "bank000000000001://qr.nspk.ru/AS100001ORTF4GAF80KPJ53K186D9A3G?type=01&bank=100000000001&sum=20000&cur=RUB&crc=5798"
}
]
}{
"message": "Не передан заголовок X-CLIENT"
}{
"message": "Неправильная платформа, тип платежа или QR код"
}Список Участников СБП по Payload (v2)
Метод для получения полного списка Участников СБП (Банков Плательщика) по операциям C2B, C2G, B2B или С2С, и формирования Виджета СБП на стороне Участника СБП – Банка Получателя или Агента ТСП, или ТСП.
HEADER PARAMETERS
https://qr.nspk.ru/AS1000670LSS7DN18SJQDNP4B05KLJL2?type=01&bank=100000000001&sum=10000&cur=RUB&crc=C08BОтветы
200Успешный ответ
{ version: string enum enum: 2.0 platform: string enum enum: ios | android | desktop type: string enum enum: qr | sub | b2b | c2g | c2c | b2c members: [{ id: string [12] name: string logo: string url: string }]}400Некорректный запрос
{ message: string}404Данные не найдены
{ message: string}Примеры ответов
{
"version": "2.0",
"platform": "desktop",
"type": "qr",
"members": [
{
"id": "100000000001",
"name": "Банк",
"logo": "https://qr.nspk.ru/proxyapp/logo/bank000000000001.png",
"url": "bank000000000001://qr.nspk.ru/AS100001ORTF4GAF80KPJ53K186D9A3G?type=01&bank=100000000001&sum=20000&cur=RUB&crc=5798"
}
]
}{
"message": "Не передан заголовок X-CLIENT-ID"
}{
"message": "Неправильная платформа, тип платежа или QR код"
}Список Участников СБП для кэширования (v1)
Метод для получения списка Участников СБП – Банков Плательщика для кэширования на срок не более чем 24 часа. Метод возвращает шаблоны прямой или доменной ссылки для перехода в приложение Банка Плательщика. Шаблоны передаются для каждого Банка Плательщика в параметре URL. Пример: «bank100000000000://qr.nspk.ru/{QRC_ID}{QUERY_STRING}». При формировании Прямой или Доменной ссылки необходимо самостоятельно подставлять в шаблон URL данные из Функциональной ссылки СБП вместо {QRC_ID} и {QUERY_STRING}. Если ссылка не содержит параметров запроса вместо {QUERY_STRING} подставляется пустая строка.
PATH PARAMETERS
HEADER PARAMETERS
Ответы
200Успешный ответ
{ version: string enum enum: 1.0 platform: string enum enum: ios | android | desktop type: string enum enum: qr | sub | b2b | c2g | c2c | b2c members: [{ name: string logo: string url: string }]}400Некорректный запрос
{ message: string}404Данные не найдены
{ message: string}Примеры ответов
{
"version": "1.0",
"platform": "desktop",
"type": "qr",
"members": [
{
"name": "Банк",
"logo": "https://qr.nspk.ru/proxyapp/logo/bank000000000001.png",
"url": "bank000000000001://qr.nspk.ru/{QRC_ID}{QUERY_STRING}"
}
]
}{
"message": "Не передан заголовок X-CLIENT"
}{
"message": "Неправильная платформа или тип платежа"
}Список Участников СБП для кэширования (v2)
Метод для получения списка Участников СБП – Банков Плательщика для кэширования на срок не более чем 24 часа. Метод возвращает шаблоны прямой или доменной ссылки для перехода в приложение Банка Плательщика. Шаблоны передаются для каждого Банка Плательщика в параметре URL. Пример: «bank100000000000://qr.nspk.ru/{QRC_ID}{QUERY_STRING}». При формировании Прямой или Доменной ссылки необходимо самостоятельно подставлять в шаблон URL данные из Функциональной ссылки СБП вместо {QRC_ID} и {QUERY_STRING}. Если ссылка не содержит параметров запроса вместо {QUERY_STRING} подставляется пустая строка.
PATH PARAMETERS
HEADER PARAMETERS
Ответы
200Успешный ответ
{ version: string enum enum: 2.0 platform: string enum enum: ios | android | desktop type: string enum enum: qr | sub | b2b | c2g | c2c | b2c members: [{ id: string [12] name: string logo: string url: string }]}400Некорректный запрос
{ message: string}404Данные не найдены
{ message: string}Примеры ответов
{
"version": "2.0",
"platform": "desktop",
"type": "qr",
"members": [
{
"id": "100000000001",
"name": "Банк",
"logo": "https://qr.nspk.ru/proxyapp/logo/bank000000000001.png",
"url": "bank000000000001://qr.nspk.ru/{QRC_ID}{QUERY_STRING}"
}
]
}{
"message": "Не передан заголовок X-CLIENT-ID"
}{
"message": "Неправильная платформа или тип платежа"
}Список участников платформы ЦР по Payload (v2)
Метод для получения полного списка Участников платформы ЦР и формирования Виджета СБП на стороне Участника СБП – Банка Получателя или Агента ТСП, или ТСП.
HEADER PARAMETERS
https://qr.nspk.ru/AS1000670LSS7DN18SJQDNP4B05KLJL2?type=01&bank=100000000001&sum=10000&cur=RUB&crc=C08BОтветы
200Успешный ответ
{ version: string enum enum: 2.0 platform: string enum enum: ios | android | desktop members: [{ id: string [12] name: string logo: string url: string }]}400Некорректный запрос
{ message: string}404Данные не найдены
{ message: string}Примеры ответов
{
"version": "2.0",
"platform": "desktop",
"members": [
{
"id": "100000000001",
"name": "Банк",
"logo": "https://qr.nspk.ru/proxyapp/logo/bank000000000001.png",
"url": "bank000000000001://qr.nspk.ru/AS100001ORTF4GAF80KPJ53K186D9A3G?type=01&bank=100000000001&sum=20000&cur=RUB&crc=5798"
}
]
}{
"message": "Не передан заголовок X-CLIENT-ID"
}{
"message": "Неправильная платформа, тип платежа или QR код"
}Список участников платформы ЦР для кэширования (v2)
Метод для получения списка Участников платформы ЦР – Банков Плательщика для кэширования на срок не более чем 24 часа. Метод возвращает шаблоны прямой или доменной ссылки для перехода в приложение Банка Плательщика. Шаблоны передаются для каждого Банка Плательщика в параметре URL. Пример: «bank100000000000://qr.nspk.ru/{QRC_ID}{QUERY_STRING}». При формировании Прямой или Доменной ссылки необходимо самостоятельно подставлять в шаблон URL данные из Функциональной ссылки СБП вместо {QRC_ID} и {QUERY_STRING}. Если ссылка не содержит параметров запроса вместо {QUERY_STRING} подставляется пустая строка.
HEADER PARAMETERS
Ответы
200Успешный ответ
{ version: string enum enum: 2.0 platform: string enum enum: ios | android | desktop members: [{ id: string [12] name: string logo: string url: string }]}400Некорректный запрос
{ message: string}404Данные не найдены
{ message: string}Примеры ответов
{
"version": "2.0",
"platform": "desktop",
"members": [
{
"id": "100000000001",
"name": "Банк",
"logo": "https://qr.nspk.ru/proxyapp/logo/bank000000000001.png",
"url": "bank000000000001://qr.nspk.ru/{QRC_ID}{QUERY_STRING}"
}
]
}{
"message": "Не передан заголовок X-CLIENT-ID"
}{
"message": "Неправильная платформа или тип платежа"
}Список платежных сервисов УПК для кэширования
Метод для получения списка платежных сервисов для формирования виджета УПК на стороне Участника УПК для кэширования на срок не более чем 24 часа. Метод возвращает шаблоны прямой или доменной ссылки для перехода в приложение Плательщика. Шаблоны передаются для каждого Плательщика в параметре URL. Пример: «bank100000000000://qr.nspk.ru/{QRC_ID}». При формировании Прямой или Доменной ссылки необходимо самостоятельно подставлять в шаблон URL данные из Функциональной ссылки УПК вместо {QRC_ID}.
HEADER PARAMETERS
Ответы
200Успешный ответ
{ version: string enum enum: 1.0 members: [{ id: string name: string paymentMethods: [{ id: string group: string enum enum: bnpl | pay-services name: string logo: string url: string }] }]}400Некорректный запрос
{ message: string}Примеры ответов
{
"version": "1.0",
"members": [
{
"id": "PS0000000001",
"name": "СБП",
"paymentMethods": [
{
"id": "PP0000000001",
"group": "bnpl",
"name": "Сервис Рассрочка",
"logo": "https://qr.nspk.ru/proxyapp/uniqr/PP0000000004.png",
"url": "https://www.service.ru/fintech/promo/c2b-qr-installment/{QRC_ID}"
},
{
"id": "PP0000000002",
"group": "pay-services",
"name": "Супер Пэй",
"url": "bank100000000190://qr.nspk.ru/{QRC_ID}?paymentServiceId=PS0000000001",
"logo": "https://qr.nspk.ru/proxyapp/uniqr/PP0000000002.svg"
}
]
},
{
"id": "PS0000000002",
"name": "Цифровой Рубль",
"paymentMethods": []
}
]
}{
"message": "Не передан заголовок X-CLIENT-ID"
}СБП онлайн-виджет
СБП онлайн-виджет позволяет встраивать готовый виджет СБП в приложение. Для внедрения СБП онлайн-виджета необходимо реализовать открытие ссылок в компоненте WebView. Примеры встраивания СБП онлайн-виджета для разных платформ представлены ниже.
iOS (Swift/WKWebView)
import UIKit import WebKit class ViewController: UIViewController, WKNavigationDelegate { var webView: WKWebView! var dialogMessage: UIAlertController! override func loadView() { webView = WKWebView() webView.navigationDelegate = self view = webView dialogMessage = UIAlertController( title: "Ошибка", message: "Приложение данного банка у вас не установлено.", preferredStyle: .alert ) dialogMessage.addAction(UIAlertAction(title: "Ок", style: .default, handler: nil)) } func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) { if (navigationAction.navigationType == .linkActivated) { if let url = navigationAction.request.url { if (UIApplication.shared.canOpenURL(url)) { UIApplication.shared.open(url) } else { self.present(dialogMessage, animated: true, completion: nil) } } decisionHandler(.cancel) return } decisionHandler(.allow) } override func viewDidLoad() { super.viewDidLoad() let url = URL(string: "https://qr.nspk.ru/AS100001ORTF4GAF80KPJ53K186D9A3G?type=01&bank=100000000007&crc=0C8A")! webView.load(URLRequest(url: url)) } }
Android (Kotlin/WebView)
class MainActivity : AppCompatActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_main) val paymentURL = "https://qr.nspk.ru/AS100001ORTF4GAF80KPJ53K186D9A3G?type=01&bank=100000000007&crc=0C8A" val webView = findViewById<View>(R.id.webview) as WebView webView.webViewClient = CustomWebClient() webView.settings.javaScriptEnabled = true webView.loadUrl(paymentURL) } } class CustomWebClient : WebViewClient() { override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean { val context = view.context try { context.startActivity(Intent(Intent.ACTION_VIEW, request.url)) } catch (e: Exception) { Toast.makeText( context, "Приложение не поддерживает переход", Toast.LENGTH_SHORT ).show() } return true } }
React Native (jsx)
// Внимание! Требуется компонент react-native-webview <WebView style={{flex: 1}} source={{uri: state.universalLink}} originWhitelist={["https://*", "bank*://*"]} onShouldStartLoadWithRequest={async (request) => { if (request.url.startsWith("bank") || (!request.url.includes("nspk.ru") && !request.url.includes("mc.yandex.ru")) ) { try { await Linking.openURL(request.url) } catch (e) { alert("Не возможности найти приложение для оплаты") } } return true }} />
Flutter (Dart)
// Внимание! Требуются пакеты: webview_flutter и url_launcher var controller = WebViewController() ..setJavaScriptMode(JavaScriptMode.unrestricted) ..setBackgroundColor(const Color(0x00000000)) ..setNavigationDelegate( NavigationDelegate( onProgress: (int progress) {}, onPageStarted: (String url) {}, onPageFinished: (String url) {}, onWebResourceError: (WebResourceError error) {}, onNavigationRequest: (NavigationRequest request) { final uri = Uri.parse(request.url); if (uri.scheme.startsWith("bank") || (!uri.host.contains("nspk.ru") && !uri.host.contains("mc.yandex.ru")) ) { var isLaunched = false; try { isLaunched = launchUrl(uri); } catch (e) { // } if (!isLaunched) { /* Обработка отсутствия приложения */ } return NavigationDecision.prevent; } return NavigationDecision.navigate; }, ), ) ..loadRequest(Uri.parse( 'https://qr.nspk.ru/AS100001ORTF4GAF80KPJ53K186D9A3G?type=01&bank=100000000007&crc=0C8A' ));