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