Efectuarea plăților pe site
Facturare
Mecanismul de interacțiune descris în această pagină vă va oferi posibilitatea de a emite o factură către utilizator pentru plata cu suma pe care o specificați. Utilizatorul fie va fi redirecționat către pagina de servicii de plată, unde vpoate achita factura într-un mod convenabil, fie veți primi un link (URL) al acestei facturi care o puteți transmite utilizatorului prin e-mail sau să generați un cod QR.
Pentru a iniția o plata printr-o formă de plată unică, trebuie doar să trimiteți utilizatorul la o adresă URL specială, precum și să indicați un șir de parametri obligatorii
Pe site-ul dvs., trebuie să plasați forma care va conține două câmpuri. Câmpul data conține xml sau json (în funcție de formatul pe care îl utilizați) cu informații și câmpul key care va conține semnătura acestor date.
» Formatul: XML
POST
https://www.bpay.md/user-api/payment1
<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="Submit" > </form>
» Formatul: JSON
POST
https://www.bpay.md/user-api-v2/payment
<form method="POST" action="https://www.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>
Click pe butonul Submit va redirecționa utilizatorul la formularul de plată a sistemultui BPay.md. După efectuarea plății, utilizatorul va fi returnat la pagina site-ului dvs. specificată în success_url. În 15 secunde, serviciul de plată va trimite o notificare cu privire la plata primită în modul specificat de dvs.
În formular, câmpul de date trebuie să conțină următorul xml, codat în base64:
<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>
» Formatul: JSON
Este necesar să formați o matrice codificață în JSON care la rîndul să este codificate în base64.
$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' => date('Ymd H:i:s'), '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));
Pentru o securitate suplimentară a plăților dvs., efectuăm verificarea obligatorie a semnăturii digitale la crearea unei plăți. Prezența unei semnături garantează protecția împotriva înlocuirii valorilor transmise (de exemplu, modificarea sumei plății sau a numărului comenzii).
» Formatul: XML
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)). La sfîrșit semnătura primită se include în cîmpul key a formei.
md5(md5($xmldata) . md5($signature))
» Formatul: JSON
Semnătura este formată prin combinarea datelor JSON cu semnătura care este emisă în timpul înregistrării magazinului. Apoi, trebuie să generați un hash, utilizînd algoritmul sha256
$signature = 'signature'; $key = hash('sha256', base64_encode(json_encode($json)) . $signature)
Cheia | Valoarea | Tipul | Format | Descriere |
---|---|---|---|---|
type | Obligator | String | XML | Câmpul definește versiunea protocolului. În prezent este instalat 1.1 |
merchantid | Obligator | String | XML | JSON | Identificatorul unic al comerciantului, obținut la înregistrare în sistemul BPay.md în calitate de comerciant |
amount | Obligator | Number | XML | JSON | Suma pe care plătitorul trebuie să achite în favoarea magazinului online. Suma se indică în valuta contului comerciantului |
dtime | Obligator | date | JSON | Data cînd plata a fost formată. |
description | Obligator | String | XML | JSON | Descrierea plății. Este afișată plătitorului în momentul achitării. |
method | Obligator | String | XML | JSON | Metoda de plată care va fi activat în mod implicit pentru utilizator. Valori 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), plătitor etc. .d. Lista completă și actuală se poate afla de la managerul care se ocupă cu integrarea comerciantului dvs. |
order_id | Obligator | Number | XML | JSON | Trebuie să conțină o valoare indicată de comerciant, prin care se poate identifica cu precizie plătitorul. Exemplu: e-mail, id, username etc. |
success_url | Opțional | String | XML | JSON | Adresa URL unde plătitorul va fi redirecționat după o achitarea produsului/serviciului. Implicit se utilizează adresa indicata la înregistrarea comerciantului dvs. |
fail_url | Opțional | String | XML | JSON | Adresa URL unde plătitorul va fi redirecționat în caz că achitarea a eșuat. (Plătitorul a refuzat să achite sau a avut loc o eroare tehnică). Implicit se utilizează adresa indicata la înregistrarea comerciantului dvs. |
callback_url | Opțional | String | XML | JSON | Adresa URL a comerciantului (magazin online), care va primi notificare după plata finisată cu succes. Această notificare indică faptul că comerciantul poate trimite bunuri sau poate furniza servicii. Dacă lipsește, valoarea implicită va fi preluată din setările comerciantului dvs. |
lang | Opțional | String | XML | JSON | Limba formularului de plată. Poate conține valori: ru, ro, en. Se utilizează numai dacă getUrl este setat la 0 sau nu este deloc setat. |
advanced1, advanced2 | Opțional | String | XML | Câmpuri suplimentare care conțin date arbitrare. Aceste date vor fi returnate magazinului online după ce plata fost finisată cu succes. Acestea pot conține orice date la discreția magazinului online. |
params | Opțional | String | JSON | Câmpuri suplimentare care conțin date arbitrare. Aceste date vor fi returnate magazinului online după ce plata fost finisată cu succes. Acestea pot conține orice date la discreția magazinului online. |
istest | Opțional | String | XML | JSON | 0 – plată reală, 1 – plată de testare. În cazul plății de testare, este disponibilă doar metoda de plată bpay. În acest caz, banii nu sunt retrași din contul plătitorului dar comerciantul primește o notificare a plății. În mod implicit, valoarea este 1. |
getUrl | Opțional | String | XML | JSON | 0 – sistemul va redirecționa automat plătitorul către pagina de plată. 1 – acesta va returna XML-ul către comerciant (magazin online), care va conține linkul url către cont. Acest link poate fi apoi trimis utilizatorului prin e-mail, mesaje text sau tipărit ca un cod QR. În mod implicit, sunteți redirecționat către pagina sistemului de plăți. |
<?php $signature="123456"; // semnătura primită la înregistrare // 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>
Click pe butonul Submit va redirecționa plătitorul la forma de plată a sistemului BPay.md. După plata finisează cu succes, utilizatorul va fi returnat la pagina site-ului dvs. specificată în success_url. În de 15 secunde, comerciantul (magazinul online) va primi o notificare cu privire la plata primită (în modul specificat de dvs.).
<?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>
Click pe butonul Submit va redirecționa plătitorul la forma de plată a sistemului BPay.md. După plata finisează cu succes, utilizatorul va fi returnat la pagina site-ului dvs. specificată în success_url. În de 15 secunde, comerciantul (magazinul online) va primi o notificare cu privire la plata primită (în modul specificat de dvs.).
ISO | Cod | Denumirea |
---|---|---|
498 | MDL | Leu moldovenesc |
643 | RUB | Rubla rusească |
840 | USD | US Dolar |
946 | RON | Leu românesc |
978 | EUR | Euro |
Verificare plății (callback)
După ce utilizatorul a achitat factura emisă de dvs., sistemul de plată electronice BPay.md poate notifica automat sistemul de informații al magazinului online despre plata primită. Pentru a activa notificarea automată, trebuie să specificați CALLBACK_URL la înregistrarea unui comerciant – adresa scriptului care va fi apelat de sistemul de plăți după ce utilizatorul efectuează o plată. Datele vor fi recepționate prin metoda POST.
Datele sunt prelucrate ca fiind codificate în base64. Inițial, este necesar să verificați corectitudinea semnăturii datelor primite pentru a vă asigura că acestea au fost trimise exact de către serviciul BPay.md. Pentru a face acest lucru, trebuie să verificați semnătura, comparînd-o cu cea care a post primită în timpul apelului callback.
Cîmpul date va conține un json codificat în base64 cu datele despre plata efectuată 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 exact de către serviciul de plăți electronice BPay.md
» Formatul: XML
Semnătura este generată conform următorului algoritm: MD5 (MD5 (XMLDATA) + MD5 (SEMNATURĂ)). SEMNATURĂ – un câmp specificat de dvs. la înregistrarea comerciantului în sistemul BPay.md
<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>
» Formatul: JSON
Semnătura este generată conform următorului algoritm (Exemplu de cod PHP): hash (‘sha256’, hash(‘sha256’, $_POST[‘data’])+hash(‘sha256’, SIGNATURE)). SEMNATURĂ – un câmp specificat de dvs. la înregistrarea comerciantului în sistemul BPay.md.
{ "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 } } }
Dacă semnătura pe care ați generat-o corespunde celei care este trecută în câmpul key, puteți continua procesul de prelucrare a plății. După decriptarea câmpului de date, acesta va conține următorul xml:
Cheia | Descriere |
---|---|
type | Definește versiunea protocolului. În prezent este instalat 1.2 |
order_id | Returnează valoarea order_id transmisă de dvs. atunci când generați o factură |
amount | Suma plătită de utilizator. |
valute | Codul valutei în care este indicată suma plății. 498 – lei moldovenești |
comand | Dacă s-a efectuat plata — este indicat pay, dacă se face doar o verificare a existenței comenzii conform order_id specificat în sistemul magazinului online, aceasta va avea valoarea check |
advanced1, advanced2 | Cîmpuri completate la discreția comerciantului |
transid | Identificatorul unic al plății în sistemul BPay.md |
receipt | Identidficatorul unic al cecului, atribuit de sistemul BPay.md. Cunoscând acest număr, oricine poate verifica existența unei plăți pe site-ul sistemului de plăți electronice BPay.md |
time | timpul de plată (până la momentul serverului de plăți bpay) în format yyyymmdd hhmmss |
test | 1 (unu) în cazul plății pentru test și 0 (zero) în cazul unei plăți obișnuite |
După procesarea plății, trebuie să anunțați sistemul de plăți cu privire la succesul sau eșecul acestui proces. Pentru a face acest lucru, trebuie să returnați XML sau JSON cu următorul conținut:
» Formatul: XML
<?xml version='1.0' encoding="utf8"?> <result> <code>100</code> <text>success</text> </result>
» Formatul: JSON
{ 'code' => 100, 'text' => "success" }
Cod | Descriere |
---|---|
100 | Finisat cu succes |
30 | A apărut o problemă la transferarea fondurilor. Sistemul BPay.md va încerca din nou după o perioadă de timp. |
Puteți verifica corectitudinea datelor, generînd o semnătură:
» Formatul: XML
$ourkey=md5(md5($xmldata) . md5($signature))
» Formatul: JSON
$signature = "123456"; $data = $_POST['data']; $jsondata = base64_decode($data); $vrfsign = hash('sha256',hash('sha256',$data).hash('sha256',$signature));
Dacă semnătura pe care ați generat-o corespunde celei care este trecută în câmpul key, puteți continua procesul de creditare a plății.
<?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") { 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>"; } ?>
<?php $signature = "123456"; $data = $_POST['data']; $key = $_POST['key']; $jsondata = base64_decode($data); $vrfsign = hash('sha256',hash('sha256',$data).hash('sha256',$signature)); if ($key == $vrfsign) { if ((string)$jsondata->comand == "check") { $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); }