API pentru programatori
În acest compartiment am colectat toată informația necesară pentru integrarea tehnică a sistemului de plată
www.bpay.md cu proiectul D-voastră.
Module existente:
API:
Formarea facturilor din magazinul online
Procesul de interacțiune descris pe această pagină, vă ofera posibilitatea de a forma utilizatorului o factură de plată pentru o sumă stabilită, după care utilizatorul va fi redirecționat pe pagina sistemului de plată, unde va efectua plata prin metoda dorita. La fel puteți primi linkul la factura creată după care personal o transmiteți utilizatorului prin intermediul email sau QR-cod.
Crearea formei:
Pe site-ul d-voastră trebuie să plasați o formă care va conține două cîmpuri: cîmpul ‘data’, care va conține un xml cu informația necesară și cîmpul ‘key’, care va conține semnătura digitală a acestei informații.
<form method="POST" action="https://www.bpay.md/user-api/payment1">
<input type="hidden" fname="data" value="">
<input type="hidden" name="key" value="">
<input type="submit" value="Transfer">
</form>
Cîmpul ‘data’ trebuie să conțină următorul xml, codat după algoritmul base64 (Funcția base64_encode în php, sau encode_base64 în perl):
<payment>
<type>1.2</type>
<merchantid>MERCHANT_ID</merchantid>
<amount>AMOUNT_VALUE</amount>
<description> style="color: black" PAYMENT_DESCRIPTION</description>
<method>bpay</method>
<order_id>USER_ACCOUNT</order_id>
<success_url>SUCCESS_URL</success_url>
<fail_url>FAIL_URL</fail_url>
<callback_url>CALLBACK_URL</callback_url>
<lang></lang>
<advanced1></advanced1>
<advanced2></advanced2>
<istest>ISTEST</istest>
<getUrl>GET_URL</getUrl>
</payment>
Descrierea cîmpurilor:
- type – acest cîmp determină versiunea protocolului. La momentul actual se setează 1.2
- merchantid – MerchantID a internet magazinului, primit la înregistrare în sistemul nostru în calitate de Merchant.
- amount – suma pe care clientul trebuie s-o plătească în favoarea internet magazinului. Este indicată în valuta în care este deschis contul în sistemul de plată.
- description – descrierea plății, care va fi afișată în cîmpul corespunzător din factura afișată clientului.
- method – metoda de plată care va fi activată pentru utilizator implicit. Metodele care pot fi: bpay (cont bpay), card_omd (carduri bancare autohtoni), card_eur (carduri bancare straini), card_usd (carduri bancare straini), webmoneycat (webmoney WMZ), wmrcat (webmoney WMR), yandexmoney (Bani Yandex), payeer si etc. Lista deplină a metodelor de plată o puteți afla de la menagerul care vă supervizează .
- order_id – Cîmpul prin care d-voastră (internet magazinul), veți putea identifica plata sau plătitorul după finisarea tranzacției. De exemplu: numărul de telefon, numărul comenzii, numarul contului. Valoarea acestui cîmp poate fi diferită pentru orice plată ca de exemplu: numărul de telefon, email etc.
- success_url (neobligatoriu) – adresa paginii la care utilizatorul va fi redirecționat după finisarea cu succes a plății. Cîmp neobligatoriu. În cazul în care cîmpul lipsește valoarea va fi luată din setările merchantului d-voastră.
- fail_url (neobligatoriu) – adresa paginii la care utilizatorul va fi redirecționat antunci cînd utilizatorul refuză achitarea pe pagina de plată a sistemului. Cîmp neobligatoriu. În cazul în care cîmpul lipsește valoarea va fi luată din setările merchantului d-voastră.
- callback_url (neobligatoriu) – adresa paginii, la care va veni notificarea despre efectuarea plății cu succes. După această notificare merchantul poate efectua trimiterea produsului sau efectuarea serviciului pentru care sa achitat. Cîmp neobligatoriu. În cazul în care cîmpul lipsește valoarea va fi luată din setările merchantului d-voastră.
- lang (neobligatoriu) — limba în care se va afișa forma de plată. Poate conține una din următoarele valori: ru, ro, en. Cîmp neobligatoriu. Este utilizat numai dacă valoarea cîmpului ‘getUrl’ este setată în 0, sau nu e setată deloc.
- advanced1, advanced2 (neobligatorii) – Cîmpuri adăugătoare care sunt îndeplinite cu date adăugătoare. Aceste date vor fi returnate internet magazinului după finisarea plații. Pot conține diferite date necesare internet magazinului.
- istest 0 — plată reală, 1 — plată de test. În cazul plății de test este activă numai metoda de plată bpay. În cazul plății de test banii din contul utilizatorului nu sunt sustrași iar internet magazinul primește notificare de plată. Cîmp neobligatoriu. Implicit este setat în 1.
- getUrl (neobligatoriu) — dacă e setat ‘0’, atunci sistema automat redirecționează utilizatorul pe pagina de plată. Dacă e setat ‘1’ — va întoarce internet magazinului un xml, care va conține adresa url la contul de plată. Această adresă poate fi transmisă utilizatorului prin email sau printată ca QR-cod. Cîmp neobligatoriu. Implicit este setat în 0, are loc redirecționarea la pagina de plată.
Atenție! Obligatoriu ecranați url, incluse în xml, fiindcă url de tipul: http://testshop.com/succes?abc=1&bcd=2 va da eroare la trasarea xml. Caracterele speciale trebuie să fie convertite în HTML-entități. În php utilizați funcția htmlspecialchars.
Formarea semnăturii digitale: Semnătura se formează prin intermediul concatinării șirurilor md5 hash de la xml creat și hash la Signature, primit la înregistrarea merchantului MD5(MD5(xmldata) + MD5(Signature)): Exemplu în PHP: md5(md5($xmldata). md5($signature)). Funcția md5 întoarce hash a șirului în hexazecimal registrul de jos. Exemplu: a4df226f5dca6c772c2686c81162c302. La sfîrșit semnătura primită se include în cîmpul key a formei.
Exemplu de cod în PHP
<?php
$signature="123456";
// подпись, полученная при регистрации мерчанта
// xml данные:
$xmldata="<payment>
<type>1.2</type>
<merchantid>myeshop</merchantid>
<amount>10.00</amount>
<description>оплата за рога и копыта</description>
<method>default</method>
<order_id>kesha@xxx.yyy</order_id>
<success_url>" .htmlspecialchars("http://myeshop.com/success.html")."</success_url>
<fail_url>".htmlspecialchars("http://myeshop.com/pay_error.html")."</fail_url>
<callback_url>". htmlspecialchars ("http://myeshop.com/callback.html" )."</callback_url>
<lang>ru</lang>
<advanced1>12, Lenina street ap. 46</advanced1>
<advanced2></advanced2>
</payment>";
// шифрум данные и подписываем их
$data = base64_encode($xmldata);
$sign = md5 (md5($xmldata) .md5 ($signature) );
?>
<form method="POST" action="https://www.bpay.md/user-api/payment1" >
<input type="hidden"name="data" value="<? echo$data ;?>">
<input type="hidden" name="key" value=" <? echo $sign; ?>" >
<input type="submit" value="Transfer" >
</form >
După click pe butonul transfer utilizatorul este redirecționat pe platforma de plată bpay.md, unde efectuează plata corespunzătoare. După finisarea plății utilizatorul va fi redirecționat pe pagina siteului d-voatră indicat în success_url. În decurs de 15 secunde,conform metodei indicate platforma de plată transmite notificare despre plata primită.
Prelucrarea automată a mesajelor de încasare a plăţilor(CALLBACK)
După ce utilizatorul a finisat plata expusă de d-voastră, sistemul de plată bpay.md poate automat să notifice internet magazinul depre plata efectuată. Pentru a primi notificarea automat, la înregistrarea merchantului trebuie să indicați parametrul ‘CALLBACK_URL’ — adresa scriptului care va fi efectuat după finisarea plății. La acest script vor fi transmise date prin metoda POST. Datele vor fi alcătuite din 2 cîmpuri : data și key. Cîmpul ‘data’ va conține xml cu datele de plată, codificat în BASE64, iar cîmpul ‘key’ va conține semnătura acestor date. Prin intermediul comparării acestei semnături, vă veți putea convinge că datele au fost transmise anume de sistemul de plată bpay.md.
Decodarea cîmpului data se face cu ajutorul funcției base64_decode în php sau decode_base64 în perl. În primul rînd trebuies să verificați corectitudinea semnăturii datelor primite ca să vă convingeți că ele au fost trimise anume de sitemul bpay.md. Pentru aceasta trebuie din nou să formați semnătura și s-o comparați cu cea venită în cîmpul ‘key’. Crearea semnăturii se face după următorul algoritm: MD5(MD5(XMLDATA) + MD5(SIGNATURE)). SIGNATURE — cîmpul indicat de d-voastră la înregistrarea merchantului.
Exemplu în PHP: $ourkey=md5(md5($xmldata) . md5($signature)), funcția md5 întoarce hash sirului în hexazecimal registrul de jos. Exemplu: a4df226f5dca6c772c2686c81162c302.
Dacă semnătura creată de d-voastră coincide cu cea transmisă în cîmpul ‘key’ puteți trece la procesul de înscriere a plății. După decodarea cîmpului ‘data’, el va conține următorul xml:
<payment>
<type>1.2</type>
<order_id>USER_ACCOUNT</order_id>
<amount>AMOUNT_VALUE</amount>
<valute>498</valute>
<comand>pay</comand>
<advanced1></advanced1>
<advanced2></advanced2>
<transid>105</transid>
<receipt>108757114530315</receipt>
<time>20111007 134928</time>
<test>0</test>
</payment>
- type – acest cîmp determină versiunea protocolului. La momentul actual se setează 1.2.
- order_id – întoarce valoarea cîmpului order_id, transmis de d-voastră la formarea facturii.
- amount – suma pe care clientul a achitat-o.
- valute – codul valutei în care e indicată suma plății. 498 — lei moldovenești
comand — dacă plata a fost efectuată — e indicat pay, dacă numai a fost făcuta verificarea existenței order_id indicat în internet magazin, va conține check. - advanced1, advanced2 – cîmpurile transmise de d-voastră la crearea facturii.
- transid – identificatorul unic a plății în sistemul bpay.md
- receipt – numărul unic pentru chitanță atribuit de sistemul bpay.md. Știind acest număr, orice persoană poate verifica existența plății în sistemul bpay.md prin această formă: https://www.bpay.md/check
- time – timpul cînd sa efectuat plata (după timpul sistemului bpay) In format YYYYMMDD Hms
- test – acest parametru are valoarea 1 — dacă este o plată de test; 0, sau gol dacă este o plată reală.
Răspunsul sistemului bpay.md
După procesarea plății, trebuie să anunțați sistemul de plată despre succesul sau insuccesul acestui proces. Pentru aceasta trebuie să întoarceți un xml de forma:
<?xml version='1.0' encoding="utf8"?>
<result>
<code>100</code>
<text>success</text>
</result>
code – codul răspunsului. 100 — dacă tranzacția a fost cu succes, 30 — a apărut erori în procesul tranzacției. Sistemul bpay.md va repeta procesul peste un interval de timp.
text — informație de tip text, care pe scurt descrie statutul procesului.
În cazul formării greșite a răspunsului XML , notificarea la fel se va repete peste un interval de timp. Vă rugăm insistent sa verificați cîmpul ‘transid’, ca să nu procesăm repetat aceeași plată.
Exemplu de cod în PHP:
<?php
$signature = "123456"; // строка, для подписи, указанная при регистрации мерчанта
$data = $_POST['data'];
$key = $_POST['key'];
$xmldata = base64_decode($data);
$vrfsign = md5(md5($xmldata) . md5($signature));
if ($key == $vrfsign)
{
$xml = simplexml_load_string ($xmldata);
if ((string)$xml->comand == "check")
{
// проверка существования указанного order_id
// 100 - номер существует, 50 - номер не существует
echo "<?xml version='1.0' encoding=\"utf8\"?>";
echo "<result>";
echo "<code>50</code>";
echo "<text>not exist</text>";
echo "</result>";
}
elseif ((string)$xml->comand=="pay")
{
// здесь осуществляем обработку данного платежа
echo "<?xml version='1.0' encoding=\"utf8\"?>";
echo "<result>";
echo "<code>100</code>";
echo "<text>success</text>";
echo "</result>";
}
else
{
echo "<?xml version='1.0' encoding=\"utf8\"?>";
echo "<result>";
echo "<code>30</code>";
echo "<text>unknown method</text>";
echo "</result>";
}
}
else
{
echo "<?xml version='1.0' encoding=\"utf8\"?>";
echo "<result>";
echo "<code>30</code>";
echo "<text>incorrect signature</text>";
echo "</result>";
}
?>
Efectuarea platilor din contul personal bpay.md
Această interfață este destinață pentru efectuarea automat a plăților din contul personal bpay.md în contul altor utilizatori bpay.md. Atenție! Pentru a putea utiliza acest serviciu, trebuie să vă adresați la noi cu o scrisoare în care să indicați IP adresa de pe care se vor face tranzacții și scopul acestora. Cîmpul key folosit la semnarea interogărilor de plată la fel este oferit de compania noastră.
Cererea se transmite prin POST la adresa: https://newartem.bpay.md/user-api/transfer și trebuie să conțină următorul xml:
<request>
<auth type=\"1\">
<login>YOUR_LOGIN</login>
<password>YOUR_PASSWORD</password>
</auth>
<transfer>
<time>TIME</time>
<payer_account>YOUR_ACCOUNT</payer_account>
<account>RECIPIENT_ACCOUNT</account>
<amount>AMOUNT</amount>
<description>TRANSACTION_DESCRIPTION</description>
<txnid>TXNID</txnid>
<test>IS_TEST</test>
</transfer>
<sign>SIGNATURE</sign>
</request>
Descrierea cîmpurilor:
login – numeloe de utilizator a contului d-voastră.
password – parola contului d-voastră.
time – timpul actual în format YYYYMMDD hhmmss, Exemplu: 20131225 135601.
payer_account – numărul contului d-voastră, de pe care se efectuează plata.
account – numărul contului beneficiarului.
amount – suma pe care doriți să o transferați.
description — descrierea plății.
txnid — un număr unic mai mare ca 0 generat de d-voastră. Să efectuați o plată cu același identificator ‘txnid’ nu este posibil.
test — 0 — tranzacție reală, 1 — tranzacție de test. La plata de test banii din contul utilizatorului nu se scad. Cîmp neobligatoriu. Implicit este setat 0.
sign — semnătura cererii, formată prin generarea hash md5 de la concatinarea tuturor valorilor din tagul transfer (în aceeași ordine cum e descris în XML) și cheia key. MD5( TIME + YOUR_ACCOUNT + RECIPIENT_ACCOUNT + AMOUNT + TRANSACTION_DESCRIPTION + TXNID + IS_TEST + key )
În răspuns vine un xml ce conține:
<result>
<code>100</code>
<text>ok</text>
<params>
<transid>1001</transid>
<receipt>123456789012345</receipt>
</params>
</result>
Codurile răspunsului:
100 — efectuat cu succes.
-10 — tranzacția este interzisă pentru IP d-voastră.
-20 — eroare la autorizare.
-21 — semnătura e formată greșit.
-85 — eroare la trasare xml.
Exemplu de cod în PHP
<?php
$time = date('Ymd His');
$payer_account = '11777777';
$account = '11999999';
$amount = 10;
$description='test payment';
$txnid = 101;
$test=0;
$key = '111111';
$sign = md5($time.$payer_account.$account.$amount.$description.$txnid.$test.$key);
$xml="
<request>
<auth type=\"1\">
<login>testuser</login>
<password>testpassword</password>
</auth>
<transfer>
<time>{$time}</time>
<payer_account>{$payer_account}</payer_account>
<account>{$account}</account>
<amount>{$amount}</amount>
<description>{$description}</description>
<txnid>{$txnid}</txnid>
<test>{$test}</test>
</transfer>
<sign>{$sign}</sign>
</request>
";
$resp=request($xml);
echo $resp;
function request($xmlrequest)
{
$curl = curl_init();
curl_setopt($curl,CURLOPT_CUSTOMREQUEST,"POST");
curl_setopt($curl,CURLOPT_POST, 1);
curl_setopt($curl,CURLOPT_URL,"https://www.bpay.md/user-api/transfer");
curl_setopt($curl,CURLOPT_USERAGENT,"User-Agent=Mozilla/5.0 Firefox/1.0.7");
curl_setopt($curl,CURLOPT_RETURNTRANSFER,1);
curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,false);
curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,false);
curl_setopt($curl,CURLOPT_POSTFIELDS, $xmlrequest);
$_PROVIDER_ANSWER = curl_exec($curl);
return $_PROVIDER_ANSWER;
}
?>
Obținerea informaţiei aferente tranzacţiei
Această cerere este destinată pentru primirea informației aferente plății după numarul transid sau receipt indicat.
Cererea se transmite în format XML la adresa https://www.bpay.md/user-api/checkstate1
XML transmis:
<request>
<auth type="1">
<login>your_login</login>
<password>your_password</password>
</auth>
<transid>1</transid>
</request>
login — numele de utilizator folosit la autorizare în sistemul bpay.md.
password — parola folosita la autorizare în sistem.
transid — id tranzacției, pentru care se cere informația. În locul acestui cîmp poate fi utilzat cîmpul receipt.
receipt — numărul chitanței, pentru care se cere informația. Se folosește în locul câmpului transid.
Exemplu de cod în PHP:
<?php
$xml = "
<request>
<auth type=\"1\">
<login>myusername</login>
<password>mypassword</password>
</auth>
<transid>124</transid>
</request>";echo $resp;
{
$curl = curl_init();
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_URL, $address);
curl_setopt($curl, CURLOPT_USERAGENT, “User-Agent=Mozilla/5.0 Firefox/1.0.7”);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl, CURLOPT_POSTFIELDS, $xmlrequest);
$_PROVIDER_ANSWER = curl_exec($curl);
return $_PROVIDER_ANSWER;
}
Ca răspuns primiți următorul XML:
<?xml version='1.0' encoding="utf8"?>
<result>
<code>100</code>
<text>transaction exist</text>
<params>
<field name="Recipient">bpay</field>
<field name="RcpAccount">11999999</field>
<field name="SndAmount">10.00</field>
<field name="SndValute">498</field>
<field name="RcptAmount">10.00</field>
<field name="RcptValute">498</field>
<field name="Description"></field>
<field name="State">100</field>
<field name="StateDescription">ok</field>
<field name="Receipt">1234567890123</field>
</params>
</result>
code — statutul cererii. 100 — plata există și este vizualizată, -35 — plata nu există, 40 — plată respinsă
text — descrierea statutului cererii
params/Recipient — id-ul serviciului beneficiar
params/RcpAccount — order_id sau identificatorul plătitorului în sistemul serviciului beneficiar
params/SndAmount — suma plătită (incluzînd și comisionul)
params/SndValute — valuta în care e indicată suma plătită
params/RcptAmount — suma primită de beneficiar
params/RcptValute — valuta sumei primită de beneficiar
params/Description — descrierea plății
params/State — statutul notificării. 100 — beneficiarul a primit notificare despre plată, 30 — beneficiarul nu a primit notificare de plată, 40 — plata este respinsă
params/StateDescription — descrierea statutului de notificare
params/Receipt — numărul cecului în sistemul de plată Bpay
Extras din cont
Această solicitare este necesară pentru a obține extrasul contului specificat account.
Cererea se transmite în format XML la adresa https://www.bpay.md/user-api/getpaymentshistory
XML transmis:
<request>
<auth type="1">
<login>your_login</login>
<password>your_password</password>
</auth>
<account>1</account>
<date_start>1</date_start>
<date_end>1</date_end>
<state>1</state>
<service>1</service>
<date_type>1</date_type>
</request>
login — loghinul, ales la înregistrare în sistemul de plăți bpay.md și utilizat pentru a intra în contul bpay.
password — parola , aleasă la înregistrarea în sistemul de plăți bpay.md și utilizată pentru a intra în contul bpay.
account — numărul contului bpay
date_start — din data
date_end — până pe data
state — statutul plăților. 100-finalizate, 70-în procesare, 40-anulate, 30-respinse. În absența uneia dintre valori, vor fi primite toate plățile disponibile
service — identificatorul serviciului în favoarea căruia a fost efectuată plata. Dacă câmpul este gol, atunci ca raspuns vor fi primite toate plățile disponibile
date_type — În cazul în care câmpul este gol, ca răspuns vor fi primite plățile dupa timpul crearii (addtime), iar dacă specificați 1, vor fi primite platile dupa statutul final (statetime)
Exemplu de cod în PHP:
<?php
$xml="
<request>
<auth type=\"1\">
<login>myusername</login>
<password>mypassword</password>
</auth>
<account>11212640</account>
<date_start>2016-11-23 13:12:00</date_start>
<date_end>2016-11-25 23:59:59</date_end>
</request>";
$resp=request($xml, 'https://www.bpay.md/user-api/getpaymentshistory');
echo $resp;
function request($xmlrequest, $address)
{
$curl = curl_init();
curl_setopt($curl,CURLOPT_CUSTOMREQUEST,"POST");
curl_setopt($curl,CURLOPT_POST, 1);
curl_setopt($curl,CURLOPT_URL, $address);
curl_setopt($curl,CURLOPT_USERAGENT,"User-Agent=Mozilla/5.0 Firefox/1.0.7");
curl_setopt($curl,CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl,CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($curl,CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl,CURLOPT_POSTFIELDS, $xmlrequest);
$_PROVIDER_ANSWER = curl_exec($curl);
return $_PROVIDER_ANSWER;
}
?>
Ca răspuns primiți următorul XML:
<?xml version='1.0' encoding="utf8"?>
<result>
<code>100</code>
<text>Success</text>
<payments>
<payment
trid="111111"
addtime="2016-11-23 13:09:10"
service=" Infocom"
serviceaccount=" 1123548895"
amount=" -1.00"
description=" achitarea serviciilor Infocom"
receipt=" 101496327083089"
balance=" 497.98">
guid="3214b276-b965-11e7-b414-525400464f7d">
</payment>
<payment
trid="1115669"
addtime="2016-11-25 20:09:10"
service=" bpay"
serviceaccount=" 1113333555"
amount=" -100.00"
description=" achitarea serviciilor bpay"
receipt=" 201496327083089"
balance=" 500.98">
guid="3214b273-b965-11e7-b414-525400464f7d">
</payment>
</payments>
<total>
<total_sum>-101</total_sum>
<total_payments>2</total_payments>
</total>
</result>
code — statutul cererii. 100 — solicitare reușită, -10 — solicitarea pentru a obține extrasul de cont specificat este interzisă, -20 — autorizare eronată, -26 — nu este posibilă afișarea plăților cu termenul mai mare de 40 zile, -80 — eroare în bază de date, -85 — error in xml parsing
text — descrie text a statutului
payment/trid — codul unic de identificare al operațiunii de plată
payment/addtime — data și ora efectuării operațiunii de plată
payment/service — denumirea serviciului achitat
payment/serviceaccount — numărul contului/facturii indicat de plătitor
payment/amount — suma operațiunii de plată
payment/description — descrierea operațiunii de plată
payment/receipt — numărul cecului
payment/balance — soldul contului bpay dupa efectuarea operațiunii de plată
payment/guid — (Globally Unique Identifier) — este un identificator statistic unic pe 128 de biți
total/total_sum — suma totală a plăților pentru perioada selectată
total/total_payments — numărul de plăți pentru perioada selectată
Integrarea soluției de plată BPAY.QR
Descrierea generală
Pe fiecare precursor al plății care este emis către client, este imprimat un cod QR care conține informații despre comerciant, identificatorul intern al cecului și suma de plată.Un client care dorește să achite o factură folosind Bpay scanează un QR în aplicația BPAY (sau orice program cu un scaner QR) și plătește în mod independent prin BPAY, informând chelnerul despre plata efectuată prin BPAY. Chelnerul din software încearcă să închidă contul folosind metoda de plată BPAY. În același timp, software-ul restaurantului comunică prin internet cu serverul BPAY și verifică plata. Dacă serverul BPAY confirmă plata, contul se închide ca “BPAY plătită” și bonul de casă este tipărit, care este emis către client. În caz contrar, ospătarul primește o notificare privind plata reușită.Ca o confirmare suplimentară, un mesaj SMS cu informații de plată este trimis către telefonul biroului mobil al restaurantului: numărul comenzii, suma. Informații privind integrarea care trebuie emise de administratorul BPAY: MERCHANTID pentru fiecare sucursală a restaurantului, LOGIN, PASSWORD
Descrierea codului QR:
Codul QR conține următorul URL: https://bpay.md/r?p=MERCHANTID;AMOUNT;INVOICEID
- MERCHANTID – identificator sucursală restaurant, emis de administratorul sistemului de plată
- AMOUNT – suma în Bani
- INVOICEID – Identificarea facturii în cadrul sucursalei restaurantului. Dezvoltatorul de software al restaurantului selectează acest identificator la discreția sa. În viitor, verificarea plății acestei facturi se va face de către acest identificator.
Пример: https://bpay.md/r?p=retailtest;3000;123456
Cod QR pentru plata facturii cu identificator 123456 на 30.00 MDL
Cerere de verificare a plății facturii
URL pentru solicitări: https://www.bpay.md/user_api/checkOrderState
Cererea este transmisă prin “POST”.
Conținutul solicitării:
<request>
<auth type="1">
<login>***</login>
<password>***</password>
</auth>
<params>
<orderid>***</orderid>
<amount>***</amount>
<period>10</period> /* număr întreg (perioadă în ore). Folosit pentru căutarea plăților pentru perioada: data și ora curente minus numărul specificat de ore. */
</params>
</request>
Login, password emis de administratorul sistemului de plată “BPAY”.
Exemplu de răspuns cu succes la solicitare:
<result>
<code>100</code>
<text>Success</text>
<payment>
<trid>3442553</trid> // identificator unic de plată în sistemul bpay
<addtime>2018-02-01 16:22:33</addtime> // timp de creare a plăților
<orderid>dev@bpay.md</orderid> // orderid a plății
<amount>1.01</amount> // suma
<state>100</state> // starea plății
<statetime>2018-02-01 16:22:33</statetime> // timpul stării de plată
</payment>
</result>
!!! Este obligatoriu să verificați dacă suma de plată restituită ca răspuns la această solicitare corespunde cu cantitatea precursorului de plată din software-ul restaurantului. Pentru ca plata să poată fi considerată efectuată de sistemul BPAY, Statul de plată trebuie să aparțină uneia dintre următoarele valori: [30, 70-79, 100]
Exemplu de răspuns la o solicitare dacă plata nu a fost găsită:
<result>
<code>-35<//code>
<text>payment with orderid=*** and sum=*** was not found</text>
</result>
Exemplu de solicitare folosind PHP:
$xml="
<request>
<auth type=\"1\">
<login></login>
<password></password>
</auth>
<params>
<orderid>123456</orderid>
<amount>30.00</amount>
<period>24</period>
</params>
</request>";
$resp = request($xml, 'https://www.bpay.md/user-api/checkOrderState');
echo $resp;
function request($xmlrequest, $address)
{
$curl = curl_init();
curl_setopt($curl,CURLOPT_CUSTOMREQUEST,"POST");
curl_setopt($curl,CURLOPT_POST, 1);
curl_setopt($curl,CURLOPT_URL, $address);
curl_setopt($curl,CURLOPT_USERAGENT,"User-Agent=Mozilla/5.0 Firefox/1.0.7");
curl_setopt($curl,CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl,CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($curl,CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl,CURLOPT_POSTFIELDS, $xmlrequest);
$_PROVIDER_ANSWER = curl_exec($curl);
return $_PROVIDER_ANSWER;
}
API JSON:
Formarea facturilor din magazinul online
Pentru a iniția o plată printr-un singur formular de plată, trebuie doar să direcționați utilizatorul către o adresă URL specială și, de asemenea, să transmiteți o serie de parametri necesari pentru plată
Exemplu cod PHP
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 |
$json = [ 'merchantid' => 'test_merchant' 'amount' => 10, 'order_id' => 9876, 'description' => 'user api v2', 'lang' => 'ru', 'method' => 'bpay', 'success_url' => 'https://bpay.md/success', 'fail_url' => 'https://bpay.md/fail', 'callback_url' => 'https://bpay.md/callback', 'valute' => 498, 'dtime' => '2020-04-22 16:13:10', 'getUrl' => '1', 'params' => [ 'type_of_payer' => 'main', 'info' => 'test information', 'invoice' => [ [ 'id' => 156, 'name' => 'mobile phone', 'model' => 'iphone 8+', 'sum' => 800 ], [ 'id' => 556, 'name' => 'TV Philips', 'model' => 'K223AA2200', 'sum' => 300 ] ] ] ]; $data = base64_encode(json_encode($json)); $signature = 'your signature'; $key = hash('sha256', $json . $signature); <form method="POST" action="http://bpay.md/user-api-v2/payment"> <input type="hidden" name="data" value="<?php echo $data; ?>"> <input type="hidden" name="key" value="<?php echo $key; ?>"> <input type="submit" name="button" value="Submit"> </form> |
Parametri
| Tipul | Descriere | Prioritate | |
|---|---|---|---|
| merchantid | text | MerchantID a internet magazinului, primit la înregistrare în sistemul nostru în calitate de Merchant. | Obligator |
| amount | număr | suma pe care clientul trebuie s-o plătească în favoarea internet magazinului. Este indicată în valuta în care este deschis contul în sistemul de plată | Obligator |
| order_id | număr | Câmpul prin care dvs. (magazinul online) veți putea identifica în mod unic utilizatorul sau achitarea efectuată de utilizator, după finisarea acesteia. De exemplu: număr de telefon, număr de comandă, număr de cont. Valoarea acestui câmp poate să nu fie unică pentru fiecare plată, cum ar fi: numărul de telefon, e-mailul etc. | Obligator |
| description | text | descrierea plății, care va fi afișată în câmpul corespunzător la achitare. | Suplimentar |
| lang | text | limba formei de plată. Poate conține valori: ru, ro, en. Câmp opțional Folosit doar dacă getUrl este setat ca 0 sau nu este deloc setat. | Suplimentar |
| method | text | Tipul de plată care va fi activat implicit pentru utilizator. Tipuri posibile: bpay (cont bpay), card_omd (carduri bancare moldovenești), card_eur (carduri bancare străine), card_usd (carduri bancare străine), webmoneycat (webmoney WMZ), wmrcat (webmoney WMR) yandexmoney (Yandex Money), payeer etc. .D. Lista actuală a metodelor de plată se află de la managerul dumneavoastră oferit de BPay. | Obligator |
| valute | număr | Cod valutar valabil pentru suma de plată indicată. O listă de coduri pentru valute poate fi vizualizată în tabelul de mai jos. | Obligator |
| dtime | text | Timpul în care a fost formată plata | Obligator |
| getUrl | număr | Dacă este 0, sistemul va redirecționa automat utilizatorul către pagina de achitare. Dacă 1 – va returna json către comerciant (magazinul online), care va conține un link url către cont. Acest link poate fi ulterior transmis utilizatorului prin e-mail, mesagerie text sau tipărit ca un cod QR. Câmp opțional. În mod implicit, redirecționează către pagina sistemului de plată. | Suplimentar |
Revenirea la site-ul comerciantului
După inițializarea plății, utilizatorul merge la pagina de verificare unde se urmărește starea plății. După primirea unui statut de succes sau eronat, utilizatorul este redirecționat către site-ul partenerului (câmpuri URL eșuate / URL de succes din setările contului personal) sau către cele indicate în timpul formării json:
| Tipul | Descriere | Prioritate | |
|---|---|---|---|
| success_url | text | adresa paginii la care utilizatorul va fi redirecționat după achitarea finisată cu succes. Câmp opțional. Dacă nu există, valoarea implicită va fi preluată din setările comerciantului. | Suplimentar |
| fail_url | text | adresa paginii la care va fi redirecționat utilizatorul în cazul în care acesta refuză să plătească pe pagina sistemului de plată. Câmp opțional Dacă nu există, valoarea implicită va fi preluată din setările comerciantului. | Suplimentar |
| callback_url | text | adresa comerciantului (magazin online) către care va fi trimisă o notificare de plată cu succes. După această notificare, comerciantul poate trimite mărfuri sau furniza servicii. Câmp opțional. Dacă nu există, valoarea implicită va fi preluată din setările comerciantului. | Suplimentar |
Valută acceptabilă
Plata are loc în valuta indicată în json sau altfel valuta va fi setată implicit MDL. Lista valutei disponibile este indicată în tabel:
| Cod | Valuta | Denumirea |
|---|---|---|
| 498 | MDL | Leu Moldovenesc |
| 643 | RUB | Rublă Rusească |
| 840 | USD | Dolar |
| 946 | RON | Leu Românesc |
| 978 | EUR | Euro |
Parametri suplimentari
| Tipul | Descriere | Prioritatea | |
|---|---|---|---|
| params | text | Câmpurile suplimentare care sunt completate cu date arbitrare. Aceste date vor fi returnate magazinului online după efectuarea plătii. Poate conține date diferite (la solicitarea magazinului online). | Suplimentar |
Formarea semnăturii
Pentru securitatea suplimentară a plăților dvs., efectuăm o verificare obligatorie a semnăturii digitale la crearea unei plăți. Prezența unei semnături garantează protecția împotriva înlocuirii valorilor transmise (de exemplu, o modificare a sumei de plată sau a numărului comenzii).
Semnătura este formată prin combinarea datelor json cu o semnătură care este emisă la înregistrarea magazinului. În continuare, trebuie să creați un hash în algoritmul sha256 (metoda hashing)
Exemplu cod PHP
|
1 2 3 4 5 6 7 |
$signature = 'signature'; // Формирование hash // hash - Генерирует хеш-код // Первый параметр это алгоритм шифрования // Второй параметр это json // Третий параметр это сигнатура $key = hash('sha256', $json . $signature) |
Generarea JSON
Pe baza exemplului de mai sus, variabila $ json după tipul de date este un tablou, trebuie să convertiți matricea în format json și să codificați datele în format MIME base64
Exemplu cod PHP
|
1 2 3 4 5 |
$signature = 'your signature'; // $json de tip array care trebuie convertit în json // json_encode - JSON - codificare // base64_encode - Codifică datele cu baza MIME64 $data = base64_encode(json_encode($json)); |
Butonul „Achitară” și redirecționarea spre achitare
Pentru această etapă, semnătura și JSON-ul deja ar trebui să fie create. După aceea, trebuie să creați un formular cu opțiunea “method” de tip “POST” și să treceți datele în input de tip hidden
|
1 2 3 4 5 |
<form method="POST" action="http://bpay.md/user-api-v2/payment"> <input type="hidden" name="data" value="<?php echo $data; ?>"> <input type="hidden" name="key" value="<?php echo $key; ?>"> <input type="submit" name="button" value="Submit"> </form> |
După un click pe butonul “submit”, utilizatorul va fi direcționat la formularul de plată a sistemului bpay.md, unde se efectuează achitarea. După finisare, utilizatorul va fi redirecționat pe pagina site-ului dvs. indicată în success_url. În termen de 15 secunde, serviciul de plată va trimite o notificare a plății primite, așa cum a fost specificată
Prelucrarea automată a mesajelor de încasare a plăţilor(CALLBACK)
După ce utilizatorul a achitat factura care a fost emisă, sistemul de plată bpay.md poate notifica automat sistemul de informații al magazinului online cu privire la plata primită. Pentru a activa notificarea automată, trebuie să specificați CALLBACK_URL – adresa scriptului care va fi apelat de sistemul de plată, după ce aceasta va fi efectuată cu suces de utilizator, la înregistrarea comerciantului. Când se numește acest script, datele vor fi transferate folosind metoda POST. Datele vor consta din 2 câmpuri – câmp date și câmp cheie.
Câmpul de data va conține json criptat în baza 64 cu date despre plată, iar câmpul key va conține semnătura acestor date. Verificând această semnătură, vă puteți asigura că datele au fost trimise de serviciul de plată bpay.md.
Câmpul de date este decriptat folosind metodele base64_decode. Inițial, este necesar să verificați corectitudinea semnăturii datelor primite pentru a vă asigura că acestea au fost trimise de serviciul bpay. Pentru a face acest lucru, trebuie să regenerați semnătura și să o verificați cu cea care a fost transferată în câmpul cheie. Semnătura este generată după următorul algoritm: hash(‘sha256’, $_POST[‘data’] + SIGNATURE) unde SIGNATURE — cîmpul specificat de dvs. la înregistrarea comerciantului.
Exemplu de generare a semnăturii:
|
1 2 3 4 5 |
// строка, для подписи, указанная при регистрации мерчанта $signature = "123456"; $data = $_POST['data']; $jsondata = base64_decode($data); $vrfsign = hash('sha256',$jsondata.$signature); |
În cazul în care semnătura pe care ați generat-o se potrivește cu cea furnizată în câmpul cheie, puteți continua procesul de creditare a plății.
Exemplu de rezultat:
După decriptarea câmpului de date, acesta va conține următorul json:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
{ "merchantid":"12312", "order_id' ":"232", "amount' ":"40", "valute' ":"498", "comand' ":"pay", "transid' ":"1232", "receipt' ":"1231231231", "time' ":"2020-02-04 22:22:22", "params ":{ "param1":{ "data":1 }, "param2":{ "data":2 } } } |
Descrierea parametrilor:
| Descriere | |
|---|---|
| merchantid | MerchantID magazinului online care a fost primit la înregistrare ca comerciant |
| order_id | Returnează valoarea order_id, indicată de dvs., la formarea contului |
| amount | suma pe care a plătit-o clientul. |
| valute | cod valutar în care este indicată suma de plată. 498 – lei moldovenești |
| comand | dacă s-a efectuat o plată – este indicată – pay, dacă se verifică doar existența order_id specificate în sistemul magazinului online, aceasta va conține check |
| transid | număr unic de plată în sistemul bpay.md |
| receipt | numărul unic de cec atribuit de bpay.md. Cunoscând acest număr, oricine poate verifica existența unei plăți prin intermediul acestui formular: https://www.bpay.md/check |
| time | Timpul de plată |
| params | Câmpuri suplimentare furnizate la formarea cererii. |
Răspunsul sistemului de plată:
După procesarea plății, trebuie să informați sistemul de plată despre succesul sau eșecul acestui proces. Pentru a face acest lucru, trebuie să returnați json din următorul exemplu:
|
1 2 3 4 |
{ 'code' => 100, 'text' => "success" } |
| Descriere | |
|---|---|
| code | Codul răspunsului. 100 — în caz că acțiunea a fost tinisată cu succes, 30 — au fost careva în timpul procesării cererii. Sistemul bpay.md va repeta operațiunea după un interval de timp. |
| text | Informații textuale care descriu succint starea. |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 |
<?php //semnătură, indicat la înregistrarea comerciantului $signature = "123456"; $data = $_POST['data']; $key = $_POST['key']; $jsondata = base64_decode($data); $vrfsign = hash('sha256',$jsondata.$signature); if ($key == $vrfsign) { if ((string)$jsondata->comand == "check") { // проверка существования указанного order_id // 100 - номер существует, 50 - номер не существует $json_answer = [ 'code' => 50, 'text' => 'not exist' ]; echo json_encode($json_answer); } else if ((string)$jsondata->comand == "pay") { // здесь осуществляем обработку данного платежа $json_answer = [ 'code' => 100, 'text' => 'success' ]; echo json_encode($json_answer); } else { $json_answer = [ 'code' => 30, 'text' => 'unknown method' ]; echo json_encode($json_answer); } $json_answer = [ 'code' => 30, 'text' => 'unknown method' ]; echo json_encode($json_answer); } |
Efectuarea platilor din contul personal bpay.md
Această interfață este destinată plăților automate din contul bpay către conturile altor utilizatori Atenție! Pentru a putea folosi acest serviciu, trebuie să ne contactați scriind o scrisoare care indică adresa IP de la care va fi făcut accesul și scopul pentru care va fi utilizată această interfață. Parametrul key folosit pentru semnarea cererilor de plată este furnizat de angajații companiei noastre.
URL для запросов: https://www.bpay.md/user-api-v2/transfer
Запрос передаётся методом POST.
Exemplu cod PHP
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 |
/** * Class UserApi */ class UserApi{ private $login = 'your login'; private $password = 'your assword'; private $apiURL = 'http://bpay.md/user-api-v2/'; private $key = 'your key'; /** * @param array $rdata * @return bool|string */ public function transfer(array $rdata){ $time = date('Ymd His'); $json = [ 'auth' => [ 'login' => $this->login, 'password' => $this->password, ], 'transfer' => [ 'payer_account' => $rdata['payer_account'], 'recipient_account' => $rdata['recipient_account'], 'amount' => $rdata['amount'], 'description' => $rdata['description'], 'txnid' => $rdata['txnid'], 'params' => [ 'param1' => 'value', 'param2' => 'value' ] ], 'dtime' => date('Ymd H:i:s') ]; $json['sign'] = $this->makeSignature($json); $url = $this->apiURL.'transfer'; return $this->request($url, $json); } /** * @param array $rdata * @return string */ private function makeSignature(array $rdata){ $str_to_sign = ''; foreach ($rdata['transfer'] as $val) { if(is_array($val)){ foreach ($val as $val2) { $str_to_sign .= $val2; } }else{ $str_to_sign .= $val; } } $sign = hash('sha256',$str_to_sign.$this->key); return $sign; } /** * @param string $url * @param array $json * @return bool|string */ private function request(string $url, array $json){ $jsonrequest = json_encode($json); $curl = curl_init(); curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "POST"); curl_setopt($curl, CURLOPT_POST, 1); curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_USERAGENT, "User-Agent=Mozilla/5.0 Firefox/1.0.7"); curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1); curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, false); curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false); curl_setopt($curl, CURLOPT_POSTFIELDS, $jsonrequest); $_PROVIDER_ANSWER = curl_exec($curl); return $_PROVIDER_ANSWER; } } $ApiClient = new UserApi(); echo $ApiClient->transfer( [ 'payer_account' => '11287227', 'recipient_account' => '11600653', 'amount' => 10, 'description' => 'P2P transfer', 'txnid' => date('YmdHis') ] ); |
Формирование сигнатуры:
Подпись запроса, образованная путем генерации sha256 хэша от конкатенации всех значений в ключе transfer и ключа key. HASH(‘sha256’, DTIME + YOUR_ACCOUNT + RECIPIENT_ACCOUNT + AMOUNT + TRANSACTION_DESCRIPTION + TXNID + key )
Формирование JSON запроса:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
$json = [ 'auth' => [ 'login' => 'your login', 'password' => 'your password', ], 'transfer' => [ 'payer_account' => 'your account', 'recipient_account' => 'send id account', 'amount' => 'your amount', 'description' => 'your desc', 'txnid' => 'your txnid', 'params' => [ 'param1' => 'value', 'param2' => 'value' ] ], 'dtime' => date('Ymd H:i:s'), 'sign' => 'signature' ]; |
После формирования данных, идет передача в метод request данных, данные приводятся в json формат и отправляются на сервер POST запросом
Descrierea cîmpurilor:
| Descriere | |
|---|---|
| auth | Объединяет в себе параметр login и password |
| login | логин, указанный при регистрации в системе bpay.md и используемый для входа |
| password | пароль, указанный при регистрации в системе bpay.md и используемый для входа |
| transfer | Объединяет в себе данные: dtime, payer_account, account, amount, description, txnid, |
| dtime | Текущее время в формате Ymd H:i:s |
| payer_account | Ваш номер счета, с которого осуществляется оплата |
| account | Номер счета получателя средств |
| amount | Сумма, в валюте Вашего счета, которую Вы хотите перевести. |
| description | Descrierea plății |
| txnid | Уникальный циферный идентификатор платежа больше нуля, генерируемый на стороне отправителя. Осуществить оплату с тем же идентификатором повторно не возможно. |
| sign | подпись запроса, образованная путем генерации sha256 хэша от конкатенации всех значений в ключе transfer и ключа key. HASH( ‘sha256’, DTIME + YOUR_ACCOUNT + RECIPIENT_ACCOUNT + AMOUNT + TRANSACTION_DESCRIPTION + TXNID + key ) |
| params | Дополнительные параметры платежа |
Пример успешного ответа на запрос:
|
1 2 3 4 5 6 7 8 9 10 |
{ "code":"100", "transid":"5701361", "receipt":"107371012882676", "KeyWord":"w_pay_success", "paketuniqid":"5951530d622d4b5f31fd182c649ea732", "text":"Payment successfully accepted for processing" } |
Codurile răspunsurilor:
| Descriere | |
|---|---|
| 100 | trimis cu succes |
| -10 | operațiunea nu este permisă pentru IP dvs. |
| -20 | eroare de autorizare |
| -21 | semnătură incorectă |
Obținerea informaţiei aferente tranzacţiei
Această solicitare este utilizată pentru a obține informații de plată utilizînd numărul de tranzacție specificat transid sau numărul bonului receipt.
Exemplu de solicitare:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 |
/** * Class UserApi */ class UserApi{ private $login = 'your login'; private $password = 'your password'; private $apiURL = 'http://bpay.md/user-api-v2/'; /** * @param null $trid * @param null $receipt * @return bool|string */ public function checkState($trid=null,$receipt=null){echo 'test'; $json = [ 'auth' => [ 'login' => $this->login, 'password' => $this->password, ], 'receipt' => $trid, 'transid' => $receipt ]; $url = $this->apiURL.'checkstate'; return $this->request($url, $json); } /** * @param string $url * @param array $json * @return bool|string */ private function request(string $url, array $json){ $jsonrequest = json_encode($json); $curl = curl_init(); curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "POST"); curl_setopt($curl, CURLOPT_POST, 1); curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_USERAGENT, "User-Agent=Mozilla/5.0 Firefox/1.0.7"); curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1); curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, false); curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false); curl_setopt($curl, CURLOPT_POSTFIELDS, $jsonrequest); $_PROVIDER_ANSWER = curl_exec($curl); return $_PROVIDER_ANSWER; } } $ApiClient = new UserApi(); echo $ApiClient->checkState(5701072,105478146723917); |
JSON Запрос на проверку оплаты счета:
URL для запросов: http://bpay.md/user-api-v2/checkstate
Запрос передаётся методом POST.
|
1 2 3 4 5 6 7 8 9 |
{ "auth":{ "login":"myLogin", "password":"myPassword" }, "receipt":"11412197", "transid":"10" } |
| Descriere | |
|---|---|
| auth | Conține așa parametri ca login și password |
| login | логин, указанный при регистрации в системе bpay.md и используемый для входа |
| password | пароль, указанный при регистрации в системе bpay.md и используемый для входа |
| orderid | id транзакции, по которой запрашивается информация. Вместо данного поля, может использоваться поле receipt |
| transid | номер чека, по которому необходимо получить информацию о платеже. Используется вместо тэга transid |
Пример успешного ответа на запрос:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
{ "Provider":"wiremd", "ToAcc":"11861932", "FromAmount":"408.00", "FromValute":"MDL", "ToAmount":"400.00", "ToValute":"MDL", "Description":"description", "State":"100", "StateDescription":" done ", "Receipt":"105478146723917" } |
| Descriere | |
|---|---|
| Provider | Идиентификатор услуги |
| ToAcc | аккаунт получателя |
| FromAmount | сумма списанная у плательщика |
| FromValute | валюта плательщика |
| ToAmount | сумма получателя |
| ToValute | валюта получателя |
| Description | Descrierea plății |
| State | статус платежа |
| StateDescription | Descrie starea plății |
| Receipt | Numărul bonului |
Extras din cont
Această solicitare este utilizată pentru a primi un extras de cont pentru contul specificat (account).
Exemplu cod PHP
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 |
/** * Class UserApi */ class UserApi{ private $login = 'your login'; private $password = 'your password'; private $apiURL = 'http://bpay.md/user-api-v2/'; /** * @param array $rdata * @return bool|string */ public function getPaymentsHistory(array $rdata){ $json = [ 'auth' => [ 'login' => $this->login, 'password' => $this->password, ], 'account' => $rdata['account'], 'date_start' => $rdata['date_start'], 'date_end' => $rdata['date_end'] ]; $json = array_merge($json,$rdata['aditional']); $url = $this->apiURL.'getPaymentsHistory'; return $this->request($url,$json); } /** * @param string $url * @param array $json * @return bool|string */ private function request(string $url, array $json){ $jsonrequest = json_encode($json); $curl = curl_init(); curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "POST"); curl_setopt($curl, CURLOPT_POST, 1); curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_USERAGENT, "User-Agent=Mozilla/5.0 Firefox/1.0.7"); curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1); curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, false); curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false); curl_setopt($curl, CURLOPT_POSTFIELDS, $jsonrequest); $_PROVIDER_ANSWER = curl_exec($curl); return $_PROVIDER_ANSWER; } $ApiClient = new UserApi(); echo $ApiClient->getPaymentsHistory([ 'account' => '11656558', 'date_end' => '2019-04-24', 'date_start' => '2019-04-24', 'aditional' => [ 'service' => 'bpay', 'date_type' => 1, 'state' => 100, ] ]); } |
Параметры
| Значение | Descriere | Prioritate | |
|---|---|---|---|
| auth | text | Объединяет в себе параметр login и password | Obligator |
| login | text | указанный при регистрации в системе bpay.md и используемый для входа | Obligator |
| password | text | пароль, указанный при регистрации в системе bpay.md и используемый для входа | Obligator |
| account | text | номер bpay кошелька | Obligator |
| date_start | text | дата с | Obligator |
| date_end | text | дата по | Obligator |
| state | număr | статус платежей. При отсутствии какого-либо значения будут получены все имеющиеся платежи. Коды можно просмотреть ниже в таблице. | Suplimentar |
| service | număr | идентификатор услуги в пользу которой осуществлен платеж. Если поле пустое, то в ответе будут получены все имеющиеся платежи | Suplimentar |
| date_type | text | если поле пустое , то в ответе будут получены платежи по времени создания(addtime), если указана 1 ,то будут получены платежи по времени финального статуса(statetime) | Suplimentar |
Ответ на запрос
После верного формирования запроса, вы получите ответ с данными в JSON формате.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 |
{ "code":100, "text":"OK", "payments":[ { "TrID":"5701299", "AddTime":"2020-04-21 09:04:03", "Service":"bpay", "ServiceAccount":"123", "ToAmount":"10.00", "Description":"Descrierea produsului", "Receipt":"104557702648042", "FromAcc":"4", "ToAcc":"11042704", "State":"100", "Context":null, "RestFrom":"9990.00", "RestTo":"12022.58", "Guid":"0c74780d-83af-11ea-bf30-0200c0a87304", "StateTime":"2020-04-21 11:09:16" }, { "TrID":"5701321", "AddTime":"2020-04-21 20:07:42", "Service":"bpay", "ServiceAccount":"11600653", "ToAmount":"10.00", "Description":"Descrierea produsului", "Receipt":"105901732459573", "FromAcc":"4", "ToAcc":"11042704", "State":"100", "Context":"{"rettrid": 5701322}", "RestFrom":"9957.59", "RestTo":"11916.82", "Guid":"c2574c76-840b-11ea-bf30-0200c0a87304", "StateTime":"2020-04-21 20:41:43" } ], "total":[ { "TotalToAmount":"39.09", "CountPayments":"4" } ] } |
Descrierea parametrilor primiți
| Parametri | Valoarea |
|---|---|
| code | Статус запроса. Все статусы можно просмотреть ниже в таблице. |
| text | descrierea succintă a codului |
| trid | numărul unic a plății |
| addtime | Data și timpul plății |
| statetime | дата и время финального статуса |
| service | название оплаченной услуги |
| serviceaccount | номер счета/фактуры указанный плательщиком при платеже |
| amount | сумма платежа |
| description | Descrierea plății |
| receipt | номер чека |
| balance | баланс bpay кошелька после проведенной транзакции |
| guid | (Globally Unique Identifier) — статистически уникальный 128-битный идентификатор |
| total_sum | общая сумма платежей за выбранный период |
| total_payments | количество платежей за выбранный период |
Статусы запроса
| Код | Descriere |
|---|---|
| 100 | Cerere de succes |
| -10 | запрос на выписку по счета для указанного аккаунта запрещен |
| -20 | ошибка авторизации |
| -26 | <не представляется возможным извлечь платежи старше 40 дней/td> |
| -80 | ошибка базы данных |
| -85 | error in json parsing |
Integrarea soluției de plată BPAY.QR
Pe fiecare precursor al plății care este emis către client, este imprimat un cod QR în care conține informații despre comerciant, identificatorul intern al bonului și suma de plată.Un client care dorește să plătească o factură folosind Bpay scanează un QR în aplicația BPAY (sau orice program cu un scaner QR) și achită independent prin BPAY, informând chelnerul despre plata efectuată prin BPAY.
Chelnerul din software încearcă să închidă contul folosind metoda de plată BPAY. În același timp, software-ul restaurantului comunică prin Internet cu serverul BPAY și verifică faptul de a fost achitat. Dacă serverul BPAY confirmă plata – comanda este închisă, așa cum a fost achitată folosind BPAY și se imprimă chitanța de numerar, care este emisă clientului. În caz contrar, ospătarul primește o notificare cu mesajul respectiv.
Ca o confirmare suplimentară, un mesaj SMS cu informații de plată este trimis către telefonul biroului mobil al restaurantulu: numărul comenzii, suma. Informații privind integrarea care trebuie emise de administratorul BPAY: MERCHANTID pentru fiecare sucursală a restaurantului, LOGIN, PASSWORD
Descrierea formatului codului QR:
В QR код на чеке зашивается следующий URL: https://bpay.md/r?p=MERCHANTID;AMOUNT;INVOICEID
| Descriere | |
|---|---|
| MERCHANTID | Identificatorul comerciantului atribuid de sistemul de plată |
| AMOUNT | Suma în BANI |
| INVOICEID | идентификатор инвойса в рамках филиала ресторана. Разработчик ресторанного ПО выбирает данный идентификатор по своему усмотрению. В дальнейшем, проверка оплаты данного инвойса будет происходить по данному идентификатору. |
Пример: https://bpay.md/r?p=retailtest;3000;123456
QR код на оплату счёта с идентификатором 123456 на 30.00 MDL
Exemplu de solicitare:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 |
/** * Class UserApi */ class UserApi{ private $login = 'your login'; private $password = 'your password'; private $apiURL = 'http://bpay.md/user-api-v2/'; /** * @param array $rdata * @return bool|string */ public function checkOrderState(array $rdata){ $json = [ 'auth' => [ 'login' => $this->login, 'password' => $this->password, ], 'orderid' => $rdata['orderid'], 'amount' => $rdata['amount'] ]; $url = $this->apiURL.'checkOrderState'; return $this->request($url, $json); } /** * @param string $url * @param array $json * @return bool|string */ private function request(string $url, array $json){ $jsonrequest = json_encode($json); $curl = curl_init(); curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "POST"); curl_setopt($curl, CURLOPT_POST, 1); curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_USERAGENT, "User-Agent=Mozilla/5.0 Firefox/1.0.7"); curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1); curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, false); curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false); curl_setopt($curl, CURLOPT_POSTFIELDS, $jsonrequest); $_PROVIDER_ANSWER = curl_exec($curl); return $_PROVIDER_ANSWER; } } $ApiClient = new UserApi(); $ApiClient->checkOrderState([ 'orderid' => 11412197 , 'amount' => 10 ]); |
JSON Запрос на проверку оплаты счета:
URL для запросов: http://bpay.md/user-api-v2/checkOrderState
Запрос передаётся методом POST.
|
1 2 3 4 5 6 7 8 9 |
{ "auth":{ "login":"myLogin", "password":"myPassword" }, "orderid":"11412197", "amount":"10" } |
| Descriere | |
|---|---|
| auth | Объединяет в себе параметр login и password |
| login | логин, указанный при регистрации в системе bpay.md и используемый для входа |
| password | пароль, указанный при регистрации в системе bpay.md и используемый для входа |
| orderid | orderid платежа |
| amount | сумма в банах |
соответствует сумме предчека в ПО ресторана. Что бы платёж считаляся осуществлённым системой BPAY,
State платежа должен иметь одно из следующих значений: [30, 70-79, 100]
Пример успешного ответа на запрос:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
{ "code": "100", "text": "Success", "payment": { "trid": "3442553", "addtime": "2018-02-01 16:22:33", "orderid": "dev@bpay.md", "amount": "1.01", "state": "100", "statetime": "2018-02-01 16:22:33" } } |
| Descriere | |
|---|---|
| trid | уникальный идентификатор платежа в системе bpay |
| addtime | Timpul de creare |
| orderid | orderid платежа |
| amount | сумма |
| state | статус платежа |
| statetime | время статуса платежа |
Пример ответа на запрос, в случае если платёж не был найден:
|
1 2 3 4 5 6 |
{ "code": "-35", "text": "payment with orderid=*** and sum=*** was not found" } |
