
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 de pe magazinul online
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" name="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>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; } ?>
Interogarea 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>"; $resp = request($xml, 'https://www.bpay.md/user-api/checkstate1'); 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>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ă