Integrarea agenților de plată cu BPay prin Scenario Manager

 

Scenario Manager BPay permite partenerilor să adauge achitarea serviciilor în aplicațiile lor în câteva minute, fără a-și face griji cu privire la integrările cu furnizorii de servicii. Cu acest serviciu, utilizatorii aplicației dumneavoastră vor putea plăti pentru orice serviciu din catalogul BPay fără a-l părăsi, iar proprietarul aplicației va primi un procent de comision din aceste tranzacții.

Integrarea Scenario Manager-ului nostru este utilă în special pentru agenții de plăți care furnizează servicii de plată publicului din numele BPay.

Scenario Manager este o aplicație web care poate fi încorporată în orice site web sau aplicație mobilă folosind WebView.

 

Etape de integrare:

 

1. Autorizarea și obținerea unui token de acces

 

Pentru a autoriza în sistemul BPay, trebuie să efectuați două cereri HTTP POST:

• Pentru a avea acces la sistem;
• Pentru autorizarea ca utilizator al sistemului.

 

Următoarele date, care sunt necesare pentru interacțiunea cu sistemul, vor fi primite de la administratorul BPay:

• OPID – identificatoruloperatorului;
• POINTID – identificatorul punctului de intrare;
• PROJECT –identificatorul proiectului (implicit „scenariomaster”);
• PASSWORD – parola;
• USER-AGENT – user-agent pentru efectuarea cererilor (implicit este „SCENARIOAPP”).

 

1.1. Pentru a primi un token de proiect, se folosește următoarea adresă:

 

https://bscm-xapi.bpay.md/Auth/AuthProject

 

Corpul cererii POST arată astfel:

{

   “project”:”PROJECT”

}

 

unde PROJECT – ID-ul proiectului primit.

USER-AGENT trebuie adăugat ca unul dintre antetele cererii.

 

Corpul de răspuns:

{

   “code”:100,

   “token”:“TOKEN”,

   “type”:”unauthorized”

}

 

Unde TOKEN – valoarea tokenului de acces pe care aplicația trebuie să o rețină pentru utilizarea ulterioară.

 

1.2. Pentru autorizare este utilizată următoarea adresă:

 

https://bscm-xapi.bpay.md/Auth/Authorization

 

Corpul cererii POST arată astfel:

{

    “token”:”TOKEN”,

    “project”:”PROJECT”,

    “opid”: “OPID”,

    “pointid”: “POINTID”,

    “password”: “PASSWORD”,

    “authtype”: “operator”

}

 

Unde TOKEN este tokenul de acces primit în cererea anterioară, iar PROJECT, OPID, POINTID și PASSWORD sunt valorile primite anterior de la administratorul BPay și enumerate mai sus.

Un exemplu de corp de răspuns arată astfel:

{

    “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”

    }

}

 

Tokenul primit anterior va fi folosit în toate cererile ulterioare. Contul folosit pentru autorizare este legat de token. Astfel, serviciul înțelege cine a trimis cererea și cum să o proceseze corect.

Codul 100 va fi un semn al unei cereri reușite. Orice valoare diferită raportează o eroare, în acest caz va exista și un câmp de text cu o descriere a erorii.

 

2. Lansarea Scenario Manager-ului

 

Pentru a lansa Scenario Manager, trebuie să deschideți în WebView adresa https://www.bpay.md/scenario-master/?base64=<base64 date de intrare>

Într-un mediu .NET, poate fi utilizat elementul controlului WebView2.

În aplicația Android – Android WebView.

În aplicația iOS – WKWebView.

Pentru React Native – React Native WebView.

Înainte de deschidere este necesar să se formeze un pachet de date de intrare. Datele sunt json convertite într-un șir base64.

Pentru a încorpora serviciul într-o aplicație web, trebuie să adăugați tag-ul <script src=”https://www.bpay.md/scenario-master/main.js”></script> înainte de tag-ul de închidere </body>, precum și blocul <div id=”scenario” data-param=”<base64 date de intrare>”></div> în acel loc pe pagina  unde doriți să apară Scenario Manager.

 

Exemplu de cod pentru încorporare într-o aplicație web:

<div id=”scenario” data-

params=”ewogICAgImJhc2VBZGRyZXNzIjogImh0dHBzOi8vbS10eGFwaS5icGF5Lm1kIiwKICAgICJpbm5hbWUiOiAibW9sZGNlbGwiLAogICAgImxhbmciOiAicnUiLAogICAgIm1vZGUi
OiAicHJvdmlkZXJzIiwKICAgICJvcHRpb25zIjogewogICAgICAgICJ1c2VyQWdlbnQiOiAiQlBBWUFQUCBpUGhvbmUiCiAgICB9LAogICAgInByb2plY3QiOiAibW9iaWxlYXBwIiwKICAg
ICJwcm92aWRlciI6ICJtb2xkY2VsbCIsCiAgICAidG9rZW4iOiAiODJmYTM5MmVlNDRiNjNlZjhhZjQ1NTlhNjU0ZTg4Y2MiCn0=”></div>

<script src=”https://www.bpay.md/scenario-master/main.js”></script>

 

Structura datelor de intrare:

{

    “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”

    ]

}

 

Descrierea parametrilor:

• mode – o categorie de scenarii, secțiunea providerseste un scenariu pentru servicii specifice.
• provider – un identificatorpentru un anumit scenariu.
• lang – limba folosită, există suport pentru limbile rusă și română.
• token – tokenul, obținut în capitolul 1.
• enviroment – constanta, care indicămediul în care este folosit Scenario Manager.
• baseAddress – adresa API, la fel ca în capitolul
• project – constantaspecificată în capitolul
• authtype – constanta.
• options – un set de opțiuni care modifică comportamentul scenariilor.
• globalStyle – un set de stiluri pentru interfață.

În funcție de parametrii de intrare, serviciul va afișa ecranele corespunzătoare. Exemplul de mai sus va deschide o pagină cu o listă de categorii.

Agentul poate aplica propriul set de stiluri de interfață în locul celui implicit. Pentru a face acest lucru, trebuie să transmiteți un link către fișierul css cu aceste stiluri ca parametru globalStyle.

 

Exemple de deschidere a altor pagini

 

Formular de plată 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”

    ]

}

 

Catalog de servicii

{

    “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”

    ]

}

 

Pagina cu o listă de metode de retragere a numerarului

{

    “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”

    ]

}

 

Pagina cu formularul 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. Abonarea la evenimente și finalizarea unui scenariu

 

Pentru feedback, trebuie să vă abonați la hook (evenimente) apelate de Scenario Manager. Pentru a face acest lucru, trebuie să vă abonați la evenimentul WebMessageReceived al componentei WebView. În handlerul acestui eveniment,  de la Scenario Manager vor fi primite evenimentele sub forma unui șir json cu următoarea structură:

{

    “invoke”: “<numele evenimentului>”,

    “data”: “<obiectul de date asociat evenimentului>”

}

 

3.1. Evenimentul tokenUpdate

 

În unele circumstanțe, tokenul de acces API se poate modifica în timpul funcționării Scenario Manager-ului.

Când se întâmplă acest lucru, Scenario Manager publică un eveniment tokenUpdate. Aplicația gazdă trebuie să își actualizeze token, deoarece cel anterior va fi invalidat. Exemplu de date:

{

“invoke”: “tokenUpdate”,

“data”: {

“token”: “67ce2c466961a3a49cdea68ca91d72ab”,

}

}

 

3.2. Evenimentul invalidToken

 

Evenimentul invalidToken este postat atunci când validarea unui token eșuează. La gestionarea a acestui eveniment, trebuie să repetați procesul de obținere a unui token și a autorizației.

{

“invoke”: “invalidToken”,

“data”: {

}

}

 

3.3. Evenimentul scenarioEnd

 

Evenimentul este publicat când se termină scenariul. La finalizarea serviciului, va fi creat un obiect care conține informații despre plata.

Un exemplu de finalizare a serviciului 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”

}

Descrierea parametrilor cheie:

FromAmount – suma care trebuie percepută de la operator

Provider – identificator de serviciu în sistemul Bpay

ProvAccount – contul destinatarului

ProvAmount – suma destinatarului

ProviderName – numele serviciului

InvID – identificatorul facturii