Интеграция платёжных агентов с BPay посредством Scenario Manager
Scenario Manager BPay позволяет партнёрам добавить оплату услуг в своих приложениях за считанные минуты, не беспокоясь об интеграциях с поставщиками услуг. С этим сервисом пользователи вашего приложения смогут оплатить любую услугу из каталога BPay не покидая его, а владелец приложения получит коммисионный процент от этих транзакций.
Интеграция нашего Scenario Manager особенно полезна платёжным агентам, которые оказывают платёжные услуги населению от имени BPay.
Scenario Manager представляет собой веб-приложение, которое можно встроить в любой сайт или мобильное приложение с помощью WebView.
Шаги интеграции:
1. Авторизация и получение токена доступа
Для авторизации в системе BPay необходимо выполнить два HTTP POST запроса:
- На получение доступа к системе;
- Для авторизации как пользователь системы.
От администратора BPay будут получены следующие данные, необходимые для взаимодействия с системой:
- OPID – идентификатор оператора;
- POINTID – идентификатор точки входа;
- PROJECT – идентификатор проекта (по умолчанию “scenariomaster”);
- PASSWORD – пароль;
- USER-AGENT – user-agent для выполнения запросов (по умолчанию “SCENARIOAPP”).
1.1. Для получения токена проекта используется следующий адрес:
https://bscm-xapi.bpay.md/Auth/AuthProject
Тело POST запроса выглядит следующим образом:
{
“project”:”PROJECT”
}
где PROJECT – полученный идентификатор проекта.
USER-AGENT должен быть добавлен как один из заголовков запроса.
Тело ответа:
{
“code”:100,
“token”:“TOKEN”,
“type”:”unauthorized”
}
Где TOKEN – значение токена доступа, которое приложение должно запомнить для дальнейшего использования.
1.2. Для авторизации используется следующий адрес:
https://bscm-xapi.bpay.md/Auth/Authorization
Тело POST запроса выглядит следующим образом:
{
“token”:”TOKEN”,
“project”:”PROJECT”,
“opid”: “OPID”,
“pointid”: “POINTID”,
“password”: “PASSWORD”,
“authtype”: “operator”
}
Где TOKEN – полученный в предыдущем запросе токен доступа, а PROJECT, OPID, POINTID и PASSWORD – значения, ранее полученные от администратора BPay и перечисленные выше.
Пример тела ответа выглядит так:
{
“code”: 100,
“text”: “authorized”,
“opid”: “1031”,
“userid”: “784”,
“pointType”: “3”,
“region”: “”,
“accesses”: {
“ChangeOperatorOnBpayout”: null,
“menu”: “[]”,
“AtmMonitoring”: “0”,
“AtmMonitoringMenu”: “[]”,
“AtmMonitoringOpList”: “”,
“PaymentsWithdrawalBpay”: “0”,
“PaymentsCreate”: “1”,
“PaymentsGetAll”: “0”,
“PaymentsCancel”: “0”,
“PaymentsFinish”: “0”,
“PaymentsSetSuspicious”: “0”,
“PaymentsStateNew”: “0”,
“PaymentsRefund”: “0”,
“PaymentsCreateFromUserAcc”: “0”,
“PaymentsEditCreatingDate”: “0”,
“PaymentsAllowProcess”: “0”,
“PaymentsEdit”: “0”,
“PaymentsStateChange”: “0”,
“FilesGetContracts”: “0”,
“AccountsEdit”: “0”,
“AccountsEditMaxCredit”: “0”,
“AccountsGetPrivateAccounts”: “0”,
“UsersSendmsg”: “0”,
“UsersGet”: “0”,
“UsersCreate”: “0”,
“UsersEdit”: “0”,
“UsersDelete”: “0”,
“UsersEditVerifiedType”: “0”,
“UsersEditState”: “0”,
“UsersRestore”: “0”,
“UsersSetAsChecked”: “0”,
“UsersEditComissGroup”: “0”,
“UsersEditIsPSP”: “0”,
“OperatorsGetAll”: “0”,
“OperatorsPointSet”: “0”,
“OperatorsPointEdit”: “0”,
“OperatorsPointDel”: “0”,
“OperatorsBallanceGetAll”: “1”
}
}
Полученный ранее токен будет использован во всех последующих запросах. Учётная запись, которая используется при авторизации, привязывается к токену. Таким образом сервис понимает, кто отправил запрос и как его правильно обрабатывать.
Признаком успешного запроса будет код 100. Любое отличное значение сообщает об ошибке, в этом случае также будет присутствовать поле text с описанием ошибки.
2. Запуск Scenario Manager
Для запуска Scenario Manager необходимо открыть в WebView адрес https://www.bpay.md/scenario-master/?base64=<base64 входных данных>
В среде .NET может быть использован элемент управления WebView2.
В приложении Android – Android WebView.
В приложении iOS – WKWebView.
Для React Native – React Native WebView.
Перед открытием необходимо сформировать пакет входных данных. Данные представляют собой json, конвертированный в строку формата base64.
Для встраивания сервиса в веб-приложение, нужно добавить тег <script src=”https://www.bpay.md/scenario-master/main.js”></script> перед закрывающим тегом </body>, а также блок <div id=”scenario” data-param=”<base64 входных данных>”></div> в том месте страницы, где вы хотите отобразить Scenario Manager.
Пример кода для встраивания в веб-приложение:
<div id=”scenario” data-
params=”ewogICAgImJhc2VBZGRyZXNzIjogImh0dHBzOi8vbS10eGFwaS5icGF5Lm1kIiwKICAgICJpbm5hbWUiOiAibW9sZGNlbGwiLAogICAgImxhbmci
OiAicnUiLAogICAgIm1vZGUiOiAicHJvdmlkZXJzIiwKICAgICJvcHRpb25zIjogewogICAgICAgICJ1c2VyQWdlbnQiOiAiQlBBWUFQUCBpUGhvbmUiCiAg
ICB9LAogICAgInByb2plY3QiOiAibW9iaWxlYXBwIiwKICAgICJwcm92aWRlciI6ICJtb2xkY2VsbCIsCiAgICAidG9rZW4iOiAiODJmYTM5MmVlNDRiNjNl
ZjhhZjQ1NTlhNjU0ZTg4Y2MiCn0=”></div>
<script src=”https://www.bpay.md/scenario-master/main.js”></script>
Структура входных данных:
{
“mode”: “other”,
“provider”: “catalog”,
“lang”: “ru”,
“token”: “67ce2c466961a3a49cdea68ca91d72ab”,
“enviroment”: “chromewebview”,
“baseAddress”: “https://bscm-xapi.bpay.md”,
“project”: “PROJECT”,
“authtype”: “operator”,
“initialStep”: “categories”,
“options”: {
“clearInvoicesBeforeCreate”: true,
“showInvoiceInfo”: true,
“catalogIgnoreVType”: true,
“externalOperPayment”: true,
“opid”: “OPID”,
“userAgent”: “USER-AGENT”
},
“globalStyle”: [
“https://www.bpay.md/scenario-master/scenario.css”,
“https://www.bpay.md/scenario-master/light.css”
]
}
Описание параметров:
- mode – категория сценариев, раздел providers является сценарием конкретных услуг.
- provider – идентификатор конкретного сценария.
- lang – используемый язык, присутствует поддержка русского и румынского языков.
- token – токен, полученный в разделе 1.
- enviroment – константа, указывающая на среду, где применяется Scenario Manager.
- baseAddress – адрес API, совпадает с разделом 1.
- project – константа, указанная в разделе 1.
- authtype – константа.
- options – набор опций,модифицирующих поведение сценариев.
- globalStyle – набор стилей для интерфейса.
В зависимости от входных параметров, сервис будет отображать соответствующие экраны. В приведенном выше примере откроется страница со списком категорий.
Агент может применить свой набор стилей интерфейса вместо используемого по умолчанию. Для этого необходимо передать ссылку на css файл с этими стилями в качестве параметра globalStyle.
Примеры открытия других страниц
Форма оплаты Moldcell
{
“mode”: “providers”,
“provider”: “moldcell”,
“lang”: “ru”,
“token”: “67ce2c466961a3a49cdea68ca91d72ab”,
“enviroment”: “chromewebview”,
“baseAddress”: “https://bscm-xapi.bpay.md”,
“project”: “PROJECT”,
“authtype”: “operator”,
“options”: {
“clearInvoicesBeforeCreate”: true,
“showInvoiceInfo”: true,
“catalogIgnoreVType”: true,
“externalOperPayment”: true,
“opid”: “OPID”,
“userAgent”: “USER-AGENT”
},
“globalStyle”: [
“https://www.bpay.md/scenario-master/scenario.css”,
“https://www.bpay.md/scenario-master/light.css”
]
}
Каталог услуг
{
“mode”: “other”,
“provider”: “catalog”,
“lang”: “ru”,
“token”: “67ce2c466961a3a49cdea68ca91d72ab”,
“enviroment”: “chromewebview”,
“baseAddress”: “https://bscm-xapi.bpay.md”,
“project”: “PROJECT”,
“authtype”: “operator”,
“options”: {
“clearInvoicesBeforeCreate”: true,
“showInvoiceInfo”: true,
“catalogIgnoreVType”: true,
“externalOperPayment”: true,
“opid”: “OPID”,
“userAgent”: “USER-AGENT”
},
“globalStyle”: [
“https://www.bpay.md/scenario-master/scenario.css”,
“https://www.bpay.md/scenario-master/light.css”
]
}
Страница со списком методов для вывода денежных средств
{
“mode”: “other”,
“provider”: “cashout”,
“lang”: “ru”,
“token”: “67ce2c466961a3a49cdea68ca91d72ab”,
“enviroment”: “chromewebview”,
“baseAddress”: “https://bscm-xapi.bpay.md”,
“project”: “PROJECT”,
“authtype”: “operator”,
“options”: {
“clearInvoicesBeforeCreate”: true,
“showInvoiceInfo”: true,
“catalogIgnoreVType”: true,
“externalOperPayment”: true,
“opid”: “OPID”,
“userAgent”: “USER-AGENT”
},
“globalStyle”: [
“https://www.bpay.md/scenario-master/scenario.css”,
“https://www.bpay.md/scenario-master/light.css”
]
}
Страница с формой Cashcode
{
“mode”: “cashout”,
“provider”: “bpay_cashcode”,
“lang”: “ru”,
“token”: “67ce2c466961a3a49cdea68ca91d72ab”,
“enviroment”: “chromewebview”,
“baseAddress”: “https://bscm-xapi.bpay.md”,
“project”: “PROJECT”,
“authtype”: “operator”,
“options”: {
“clearInvoicesBeforeCreate”: true,
“showInvoiceInfo”: true,
“catalogIgnoreVType”: true,
“externalOperPayment”: true,
“opid”: “OPID”,
“userAgent”: “USER-AGENT”
},
“globalStyle”: [
“https://www.bpay.md/scenario-master/scenario.css”,
“https://www.bpay.md/scenario-master/light.css”
]
}
3. Подписка на события и завершение сценария
Для обратной связи необходимо подписаться на хуки (события), вызываемые Scenario Manager. Для этого надо подписаться на событие WebMessageReceived компоненты WebView. В обработчике этого события от Scenario Manager будут приходить события в виде json строки со следующей структурой:
{
“invoke”: “<название события>”,
“data”: “<объект данных, связанных с событием>”
}
3.1. Событие tokenUpdate
В некоторых обстоятельствах токен доступа к API может меняться в ходе работы Scenario Manager.
Когда это происходит, Scenario Manager публикует событие tokenUpdate. Хост-приложение должно обновить у себя токен, поскольку предыдущий будет инвалидирован. Пример данных:
{
“invoke”: “tokenUpdate”,
“data”: {
“token”: “67ce2c466961a3a49cdea68ca91d72ab”,
}
}
3.2. Событие invalidToken
Событие invalidToken публикуется при получении негативного результата проверки токена. При обработке этого события необходимо повторить процесс получения токена и авторизации.
{
“invoke”: “invalidToken”,
“data”: {
}
}
3.3. Событие scenarioEnd
Событие публикуется при завершении сценария. В случае завершения услуги в качестве данных будет получен объект, содержащий информацию о созданном платеже.
Пример завершения услуги moldcell:
{
“PayMethod”: “pos”,
“FromAmount”: 12.1,
“FromValute”: “498”,
“FromValuteName”: “MDL”,
“Provider”: “moldcell”,
“ProvAccount”: “79789456”,
“ProviderName”: “Moldcell”,
“ProvAmount”: “10.00”,
“ProvValute”: “498”,
“ProvValuteName”: “MDL”,
“ProvFee”: null,
“Rate1”: null,
“Rate2”: null,
“Description”: “Оплата услуги Moldcell”,
“Receipt”: null,
“Params”: {
“params”: {
“MinSum”: “0.00”,
“MaxSum”: “1000000”,
“sumType”: “receive”,
“opaccount”: 79789456,
“opamount”: 10,
“sumType:Name”: “Сумма получателя”,
“settlementMsg”: “Оплата услуги Moldcell”
}
},
“senderCommision”: null,
“AllowPay”: “1”,
“InvID”: “908”,
“comiss_group”: “”,
“logoPath”: “https://st.bpay.md/mdar/services/logo/mobile/Moldcell.png”,
“categ”: null,
“TemplateAllowed”: true,
“TemplateAutoPayment”: null,
“TemplateDynamicAmount”: null,
“UserID”: “4”
}
Описание ключевых параметров :
FromAmount – сумма для списания с оператора
Provider – идентификатор услуги в системе Bpay
ProvAccount – счёт получателя
ProvAmount – сумма получателя
ProviderName – наименование услуги
InvID – идентификатор инвойса