Published using Google Docs
Система быстрых платежей (СБП) НКО ЭЛПЛАТ версия 1.0.16
Updated automatically every 5 minutes

1. Термины и определения        2

2. Алгоритмы работы:        3

2.1 Для сайта, мобильного приложения или точки оплаты        3

2.2 Для точки оплаты c повышенной проходимостью.        3

3. Ключи доступа к системе        4

3.1 Метод createQr.        5

3.2 Расчёт hashId при createQr.        6

3.3 callback.        7

3.4 Метод getQrDynPay.        7

3.5 Метод deleteQr.        8

3.6 Возврат.        9

3.7 Подготовка кассовой платежной ссылки        10

3.8 Активация кассовой платежной ссылки        12

3.9 Деактивация кассовой платежной ссылки        13

4. Тестирование        14

5. Требования к оформлению страницы оплаты        15

6. Примеры реализаций        16

7. Список изменений        17


1. Термины и определения

 КЛИЕНТ – физическое лицо желающее осуществить перевод от своего имени при помощи мобильного приложения банка подключенного к СБП.

БАНК – НКО ЭЛПЛАТ.

ТСП - торгово-сервисное предприятие

ПАРТНЕР – юридическое лицо, заключившее договор с БАНКОМ, в ТСП или на сайте которого размещаем платежный инструмент.

СБП – Система быстрых платежей — это сервис Банка России, позволяющий физическим лицам совершать мгновенные переводы по номеру мобильного телефона в любой банк — участник СБП, а также производить оплату товаров и услуг в розничных магазинах и сети интернет по QR-коду. https://sbp.nspk.ru/


2. Алгоритмы работы:

2.1 Для сайта, мобильного приложения или точки оплаты

 

Клиент в мобильном приложении (как вариант на сайте, или в магазине ПАРТНЕРА), далее ТОЧКА, набирает корзину для оплаты и выбирает метод оплаты корзины через СБП.

 

ТОЧКА формирует при помощи метода createQr QR код и отображает клиенту на дисплее, в виде страницы оплаты или печатает на бумаге.

Требования к странице оплате определены в разделе 5

Внимание!

Если клиент набрал корзину в мобильном телефоне и хочет оплатить мобильным телефоном по СБП, он не сможет считать.одним телефон QR который Вы ему отобразите. Для того чтоб ему как то можно было оплатить необходимо на платежной странице добавлять “Кнопку” или “Платежную ссылку” (детальнее в 5.Требованиях к оформлению страницы оплаты).

 

Клиент:

  1. Переходит в мобильное приложение своего банка, подключенного к СБП оплата по QR список подключенных: https://sbp.nspk.ru/participants/ 
  2. Выбирает оплату по QR коду.
  3. Наводит камеру на QR код, считывает, видит информацию.
  4. Подтверждает свое желание осуществить перевод в пользу юридического лица.

После успешной/неуспешной оплаты, процессинг БАНКа, формирует callback в ТОЧКУ, об успешности (не успешности) платежа.

Внимание! Если по какой то причине ТОЧКА не смогла принять callback, она может запросить статус оплаты при помощи метода getQrDynPay.

2.2 Для точки оплаты c повышенной проходимостью.

Вводная:

Торговый магазин, одна или несколько касс. на каждой кассе уже распечатаны и висят на видном месте QR коды (раздел 3.7. Подготовка кассовой платежной ссылки).

Оплата:

Клиент подходит на кассу с набранной корзиной, или набирает корзину покупок прямо у продавца.

Продавец в своём кассовом ПО вводит сумму оплаты для клиента, формирует назначение платежа (раздел 3.8. Активация кассовой платежной ссылки).

Клиент наводит на QR, считывает, видит информацию о магазине, сумму и назначение покупки. Принимает решение об оплате. Оплачивает.

Забирает покупки.

Альтернативный вариант:

Клиент наводит на QR, считывает, видит информацию о магазине, сумму и назначение покупки. И не оплачивает. В этом случае продавец отменяет оплату (раздел 3.9. Деактивация кассовой платежной ссылки).

3. Ключи доступа к системе

Адрес боевого шлюза: https://sbpekv.el-plat.ru

Адрес тестового шлюза: http://sbpekvtest.el-plat.ru

Только после успешного тестирования, будет доступен боевой шлюз.

Запросы на шлюз направлять методом POST. Кодировка UTF-8.

 

тестовые ключи доступа:

login = evolenta

passwd = 58b39410314c551b81bd24fac1d817ab

orgId = 430

 

ВНИМАНИЕ!

Во всех текстовых полях исключить занесение спец.символов, особенно:

\               обратный СЛЭШ

‘              одинарная кавычка

"              двойная кавычка

 

 


3.1 Метод createQr.

Виды QR кодов:

  1. Динамический QR (одноразовый, со сроком экспирации).
  2. Статический QR (многоразовый, без срока экспирации).

Для интернет Сайтов подходит исключительно динамические QR.

Статический код хорошо подходит для точек с небольшой проходимостью.

Таблица 3.1

Наименование

 

Пример

Описание

type

O

createQr

Создание QR

login

O

evolenta

Логин в системе БАНКа

callback

O

http://sbpekvaring.el-plat.ru/test.php

УРЛ, куда будет отправлен callback (п.3.3)

elplatPhone

Н

0079226837651

Телефон продавца, куда будет направлено дополнительное PUSH уведомление об оплате, если установлено приложение ЭЛПЛАТ-ОНЛАЙН

qrcType

O

01

Тип Qr кода:

01 – статический

02 – динамический

hashId

O

80269203370aaf0362385e5e3d433b6b

Расчётное величина (п.3.2)

currency

O

RUB

Валюта, только RUB

orgId

O

430

Id организации в БАНКе, на которую будет зачисление денежных средств, выдаётся после регистрации ТСП в СБП и проведении всех тестов.

amount

У

12

Сумма в коп

paymentPurpose

У

Тест

Назначение платежа

qrTtl

Н

20

Время жизни от 5 до 129600 минут. Действует только для динамических QR кодов. Если не задан параметр, то он принимает значение в 4320 минут (3е суток).

email

Н

help@el-plat.ru

Email клиента (при наличии), он необходим для направления фискального чека

 

У – условно-обязателен, но обязателен для динамических QR кодов

О – обязателен.

Н – необязательный параметр.

Пример 1:

curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{"type":"createQr","hashId":"635454e6a3c3f8336fade5b5f41d2582","login":"evolenta","callback":"http://sbpekvaring.el-plat.ru/test.php", "qrcType":"01", "currency":"RUB","orgId":"430"}' http://sbpekvtest.el-plat.ru

Пример 2:

curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{"type":"createQr","elplatPhone":"0079226837651","hashId":"635454e6a3c3f8336fade5b5f41d2582","login":"evolenta","callback":"http://sbpekvaring.el-plat.ru/test.php", "qrcType":"01", "currency":"RUB","orgId":"430"}' http://sbpekvtest.el-plat.ru

 
        Пример 3:

curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{"type":"createQr","elplatPhone":"0079226837651","hashId":"189f826134f6f8bc3a9f68376b7034f2","login":"evolenta","callback":"http://sbpekvaring.el-plat.ru/test.php", "qrcType":"02", "currency":"RUB","orgId":"430","email":"ru@el-plat.ru","amount":"13","paymentPurpose":""}' http://sbpekvtest.el-plat.ru

При успехе:

{"code":0,"comment":"","info":{"status":true,"qrData":"https:\/\/qr.nspk.ru\/AS10004CG89LPR8U9ID8TATP0RTVIDV0?type=01&bank=100000000086&crc=3391","qrcId":"AS10004CG89LPR8U9ID8TATP0RTVIDV0"}}

При неуспехе:

{"code":0,"comment":"","info":{"status":false,"descr":"Ошибка hashId"}}

Об успешности говорит параметр status.

В разделе qrData – payload.

ПАРНТЕРу необходимо сгенерировать и отобразить QR клиенту, с данными из qrData.

3.2 Расчёт hashId при createQr.

Последовательная конкатенация полей в следующем порядке:

'login', "passwd", "callback", "qrcType", "currency", "orgId", "amount", "paymentPurpose", “email”

От полученной строки вычисляется md5.

 

3.3 callback.

Callback будет приходить из сети 91.223.44.0/24.

Пример callback:

{"action":"send","phone":"","callbackUrl":"http:\/\/epaytest.el-plat.ru\/sbp\/sbpCallback.php","qrcId":"AD10006GU99GDJGG880AR2IVLGUOOONI","amount":"1","allAmount":"1","ebl27":"A1088074553015010000041FC7C19FDE","title":"ЭЛПЛАТ С2B","message":"УСПЕШНО. QR Зачисление. 0.01 руб. Через систему быстрых платежей. A1088074553015010000041FC7C19FDE","type":"AD","payStatus":1,"payPhone":"9824010086","vTerminal":"9226837651","orgId":"596"}

Об успешности говорит параметр payStatus = 1, иной payStatus – не успешно.

Если в поле phone занесен номер телефона, информирование будет еще и на телефон в виде push сообщения в приложение ЭЛПЛАТ-ОНЛАЙН.

type указывает какой тип qr кода был оплачен, AS – статический, AD – динамический.

qrcId указывает какой идентификатор QR кода, который был оплачен.

amount - сумма к перечислению ПАРТНЕРу в копейках = сумма оплаты - торговая уступка БАНКа.

allAmount - сумма оплаты КЛИЕНТОМ.

ebl27 – уникальный номер перевода в системе быстрых платежей, необходим для разбора информации о платеже.

payPhone - телефон плательщика

 

Ожидается http ответ 200, Content-Type: application/json, в теле ответа {"status":true}

При неверном ответе или отсутствии, каждые 3 сек будет повторяться callback, 10 попыток.

3.4 Метод getQrDynPay.

Метод дает возможность запросить статус оплаты по динамическим QR кодам, если по какой то причине вы не смогли принять callback, например у вас пропал Интернет и вы не получили callback и статус оплаты неизвестен.

Расчёт hashId:

Последовательная конкатенация полей в следующем порядке:

'login', "passwd", "qrcId"

От полученной строки вычисляется md5.

Пример запроса:

curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{"type":"getQrDynPay","login":"evolenta", "qrcId":"AD10007RCLUBFD6U95MB24906KHT39P8","hashId":"deec7d2398d155a1ca7cbdeee98dbd30"}' http://sbpekvtest.el-plat.ru

При успехе:

{"code":0,"comment":"","info":{"status":true,"amount":"100","ebl27":"A02030639087280100000472958D6246","message":"QR Зачисление. 1 руб. Через систему быстрых платежей. Успешно. A02030639087280100000472958D6246","payStatus":"1"}}

При неуспехе:

{"code":0,"comment":"","info":{"status":false,"descr":"Ошибка hashId"}}

Об успехе говорит параметр status, true - успешный, иной не успешный.

amount - сумма к перечислению ПАРТНЕРу в копейках = сумма оплаты - торговая уступка БАНКа.

ebl27 – уникальный номер перевода в системе быстрых платежей, необходим для разбора информации о платеже.


3.5 Метод deleteQr.

Метод дает возможность удалить ранее созданный статичный QR код.

Расчёт hashId:

Последовательная конкатенация полей в следующем порядке:

login, passwd, qrcId, orgId

От полученной строки вычисляется md5.

Пример запроса:

curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{"type":"deleteQr",

"login":"evolenta","hashId":"cf0e8fb1c3c9008ac33de015b08f2e26","qrcId":"AS10006HNMK4MCNB92J84VD9AN63KTIR",

"orgId":"430"}' http://sbpekvtest.el-plat.ru

При успехе:

{"code":0,"comment":"","info":{"status":true}}

При неуспехе:

{"code":0,"comment":"","info":{"status":false,"descr":"Ошибка hashId"}}

Об успехе говорит параметр status, true - успешный, иной не успешный.


3.6 Возврат.

Метод дает возможность возвратить деньги клиента за покупку.

Расчёт hashId:

Последовательная конкатенация полей в следующем порядке:

login, passwd, ebl27, amount,orgId,descr

От полученной строки вычисляется md5.

Пример запроса:

curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{"type":"undone",

"hashId":"1a7bf319249a37d3f741c0571a2e6120","login":"evolenta","ebl27":"A1068073926539010000041B5CB54189",

"amount":"1", "orgId":"430", "descr":"Возврат по инициативе клиента", "vTerminal":"9226837651"}' http://sbpekvtest.el-plat.ru

ebl27 – уникальный номер перевода C2B(покупка) в СБП.

vTerminal - виртуальный терминал, по API он равен логину.

При успехе:

{"code":0,"comment":"","info":{"status":true,"msgId":"202010301100086D0500001604036982"}}

При неуспехе:

{"code":0,"comment":"","info":{"status":false,"descr":"Недопустимая сумма к возврату"}}

Об успехе говорит параметр status, true - успешный, иной не успешный.

msgId - номер сообщения СБП.


3.7 Подготовка кассовой платежной ссылки

Наименование

 

Пример

Описание

type

O

cashQr

работа с кассовыми платежными ссылками

action

О

create

Создание

login

O

evolenta

Логин в системе БАНКа

callback

O

http://sbpekvaring.el-plat.ru/test.php

УРЛ, куда будет отправлен callback (п.3.3)

elplatPhone

Н

0079226837651

Телефон продавца, куда будет направлено дополнительное PUSH уведомление об оплате, если установлено приложение ЭЛПЛАТ-ОНЛАЙН

hashId

O

80269203370aaf0362385e5e3d433b6b

Последовательная конкатенация полей в следующем порядке:

'login', "passwd", "callback", "orgId", “vTerminal”

От полученной строки вычисляется md5.

orgId

O

430

Id организации в БАНКе, на которую будет зачисление денежных средств, выдается после регистрации ТСП в СБП и проведении всех тестов.

vTerminal

О

Касса 1

Идентификатор вашей кассы, не более 10 символов. Уникальный в пределах Вашей организации. Контроль за уникальностью на стороне ПАРТНЕРа.

 

У – условно-обязателен, но обязателен для динамических QR кодов

О – обязателен.

Н – необязательный параметр.

Пример:

curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{"type":"cashQr","action":"create",

"elplatPhone":"0079226837651", "vTerminal":"Касса1",

"hashId":"392964888013c5b634a6c2490aea9344","login":"evolenta","callback":"http://sbpekvaring.el-plat.ru/test.php",

"orgId":"430"}' http://sbpekvtest.el-plat.ru

При успехе:

{"code":0,"comment":"","info":{"status":true,"qrData":"https:\/\/qr.nspk.ru\/AS10004CG89LPR8U9ID8TATP0RTVIDV0?type=01&bank=100000000086&crc=3391","qrcId":"AS10004CG89LPR8U9ID8TATP0RTVIDV0"}}

При неуспехе:

{"code":0,"comment":"","info":{"status":false,"descr":"Ошибка hashId"}}

Об успешности говорит параметр status.

В разделе qrData – кассовый payload.

ПАРНТЕРу необходимо сгенерировать QR, распечатать его, и поставить рядом с кассой.


3.8 Активация кассовой платежной ссылки

Наименование

 

Пример

Описание

type

O

cashQr

работа с кассовыми платежными ссылками

action

О

activate

Активация оплаты

login

O

evolenta

Логин в системе БАНКа

hashId

O

80269203370aaf0362385e5e3d433b6b

Последовательная конкатенация полей в следующем порядке:

'login', "passwd", "qrcId", "amount", “paymentPurpose”,”currency”

От полученной строки вычисляется md5.

currency

O

RUB

Валюта, только RUB

qrcId

O

AS10004O7T4048LF98E9TPPLDQLJG5JK

qrcId из Кассовой ссылки (п.3.7)

amount

О

12

Сумма в коп

paymentPurpose

О

Тест

Назначение платежа

qrTtl

Н

20

Время жизни от 5 до 20 минут.

email

Н

help@el-plat.ru

Email клиента (при наличии), он необходим для направления фискального чека

У – условно-обязателен, но обязателен для динамических QR кодов

О – обязателен.

Н – необязательный параметр.

Пример:

curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{"type":"cashQr","action":"activate",

"hashId":"1025caadcdb9dc037da270913cb1d405","login":"evolenta",

"qrcId":"AS10004O7T4048LF98E9TPPLDQLJG5JK","amount":"123","paymentPurpose":"тест 1.23 р", "currency":"RUB","email":"ru@el-plat.ru"

}' http://sbpekvtest.el-plat.ru

При успехе:

{"code":0,"comment":"","info":{"status":true}}

При неуспехе:

{"code":0,"comment":"","info":{"status":false,"descr":"Ошибка hashId"}}

3.9 Деактивация кассовой платежной ссылки

Наименование

 

Пример

Описание

type

O

cashQr

работа с кассовыми платежными ссылками

action

О

deactivate

Деактивация оплаты

login

O

evolenta

Логин в системе БАНКа

hashId

O

80269203370aaf0362385e5e3d433b6b

Последовательная конкатенация полей в следующем порядке:

'login', "passwd", "qrcId"

От полученной строки вычисляется md5.

qrcId

О

AS10004O7T4048LF98E9TPPLDQLJG5JK

qrcId из Кассовой ссылки (п.3.7)

Пример:

curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{"type":"cashQr","action":"deactivate",

"hashId":"bff7c46e18e1971aa33792b0fa38dcc5","login":"evolenta",

"qrcId":"AS10004O7T4048LF98E9TPPLDQLJG5JK"}' http://sbpekvtest.el-plat.ru

При успехе:

{"code":0,"comment":"","info":{"status":true}}

При неуспехе:

{"code":0,"comment":"","info":{"status":false,"descr":"Ошибка hashId"}}


4. Тестирование

Проводиться самостоятельно при помощи тестового приложения: https://retail.el-plat.ru/files/elplat-debug.apk

Для входа в тестовое приложение необходимо:

  1. ввести свой номер телефона в тестовом приложении и перейти на страницу ввода кода из СМС.
  2. Написать письмо на ru@el-plat.ru, указать Вашу организацию и введенный номер
  3. В обратную Вы получите код из СМС.

После получения КОДа:

  1. войти в приложение
  2. заполнить профиль: ФИО, дату рождения, паспорт, дата выдачи паспорта, снилс
  3. Получать Именной ЭСП не требуется.
  4. На счету будет 100р. Расходуйте так, чтоб хватило на весь этап тестирования.

Порядок проведения тестирования:

  1. Создать QR динамический с суммой и назначением платежа.

Рекомендованная сумма до 1 рубля.

  1. Осуществить успешную оплату при помощи тестового приложения.
  2. Проверить после оплаты ВИЗУАЛИЗАЦИЮ НА ВАШЕЙ СИСТЕМЕ статус оплаты. Должна быть зеленая галочка или иная визуальная картинка, говорящая о успехе оплаты.

  1. Произвести возврат денег обратно клиенту.
  2. Написать письмо в банк о успешности прохождения тестирования, указать организацию приложить ссылку на скачивание Видео-тестирования (видео должно быть аналогичное тому, как приведено в разделе 6 данного руководства).


5. Требования к оформлению страницы оплаты

Минимальные размеры QR по высоте и ширине: 200px

Рекомендуемые размеры QR 300px на 300px

В центре QR на белом непрозрачном фоне или рядом с ним должна быть иконка СБП.

Ссылка для скачивания Иконки СБП: http://vret.el-plat.ru/img/logo_sbp.png

Для того чтобы визуально отобразить QR на вашей странице оплаты, Вы можете воспользоваться следующими бесплатным библиотеками:

Для java: https://www.journaldev.com/470/java-qr-code-generator-zxing-example

Для php: http://phpqrcode.sourceforge.net/

Для javascript: https://github.com/azay-ru/qrcodejs

Или любой иной на Ваш выбор.

На странице оплаты по СБП, должно быть указано:

Внимание!

Если клиент заходит с мобильного телефона (рекомендуем ориентироваться на разрешение экрана), дополнительно, необходимо отобразить КНОПКУ, внешний вид для примера, ниже:

Пример кода кнопки:

<button type="button" class="btn btn-secondary btn-icon" onclick="window.open('https://qr.nspk.ru/AD1000138PJGGR4I83P8GA5DEE3CNKAU?type=02&amp;bank=100000000086&amp;sum=1&amp;cur=RUB&amp;crc=FDAF','_blank');"><span class="icon"><img src=САЙТ height="35px;"></span> Оплатить</button>

в гиперссылку вставить данные из qrData

в сайт вставить url расположения иконки СБП на Вашем портале.

После оплаты должна появиться зеленая галочка, или иной признак успешности оплаты.

Для этого можно воспользоваться технологией push или server events https://developer.mozilla.org/ru/docs/Web/API/Server-sent_events 


6. Примеры реализаций

Продажи в магазине https://disk.yandex.ru/i/fglqW4vrn9HRrQ

Продажи в мобильном приложении https://disk.yandex.ru/i/-bXC7CaDHLmRTg

Продажи на сайте https://disk.yandex.ru/i/966Vlg_4nLmj2w


7. Список изменений

 

Версия 1.0.0

21/04/2020

Создан документ

Версия 1.0.1

06/05/2020

Раздел Callback уточнён.

Версия 1.0.2

13/05/2020

  1. Уточнен алгоритм повторов сообщений
  2. Добавлен параметр в ответе ebl27
  3. п.3.1 Добавлен необязательный параметр elplatPhone.

Версия 1.0.3

28/07/2020

  1. Переработан документ
  2. Перенесен на google docs.

Версия 1.0.4

29.07.2020

  1. Добавлен метод qetQrDynPay
  2. Доработан алгоритм работы

Версия 1.0.5

10.08.2020

Добавлен метод deleteQR

Версия 1.0.6

24.09.2020

  1. Алгоритм работы дополнен
  2. Требования к оформлению дополнены

Версия 1.0.7

15.10.2020

  1. Добавлен п.3.6 Метод Возврат.

Версия 1.0.8

29.10.2020

  1. В методе createQr добавлен параметр qrcId
  2. В метод Возврат добавлен параметр msgId

Версия 1.0.9

27.01.2021

В callback добавлен параметр allAmount, уточнён amount.

Версия 1.0.10

12.02.2021

В метод createQr добавлен дополнительный необязательный параметр vTerminal

Версия 1.0.11

09.03.2021

  1. Добавлена пример для возврата с использованием vTerminal
  2. При формировании QR добавлен необязательный параметр qrTtl - время жизни динамического QR кода в минутах.
  1. Параметр vTerminal упраздняется, при создании QR, он автоматически присваивается логину от авторизации.

Версия 1.0.12

29.03.2021

В callback добавлен параметр payPhone (телефон плательщика)

Версия 1.0.13

18.05.2021

Уточнена информация о проведении возврата.

Версия 1.0.14

17.06.2021

Уточнены

1) раздел тестирования,

2) раздел Требование к оформлению страницы оплаты

Версия 1.0.15

28.07.2021

В метод createQr добавлен параметр email (необходим для направления фискального чека)

Версия 1.0.16

09.09.2021

  1. Добавлен еще один алгоритм работы.
  2. Добавлен раздел 3.7 Подготовка кассовой платежной ссылки.
  3. Добавлен раздел 3.8 Активация кассовой платежной ссылки.
  4. Добавлен раздел 3.9 Деактивация кассовой платежной ссылки.