API pentru programatori

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.

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):

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

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ă.

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:

• 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>"; 
}
?>

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; 
} 
  
?>

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

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ă

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:

Login, password emis de administratorul sistemului de plată “BPAY”.

Exemplu de răspuns cu succes la solicitare:

!!! 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ă:

Exemplu de solicitare folosind PHP: