Интеграция платёжных агентов с 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 – идентификатор инвойса