WebPay Form API
Dokumentacija za integraciju WebPay Form servisa.
Uvod
Ovaj dokument namjenjen je svim stranama zainteresiranim za integraciju WebPay Form servisa. Osnovne funkcionalnosti servisa su opisane u dokumentu WebPay payment gateway.
Preduvjeti za integraciju su sljedeći:
- posjedovanje vlastite web aplikacije pomoću koje posjetitelji odabiru robu i/ili usluge koje žele kupiti
- razvojni tim koji poznaje neku od serverskih tehnologija (PHP, Python, Ruby...)
- sklopljeni ugovori između zainteresirane strane i Webteh-a, i između zainteresirane strane i banke
- ispravno postavljeno prodajno mjesto koristeći administracijsko sučelje WebPay servisa
Kako radi WebPay Form servis?
WebPay Form servis koristi klijent-server arhitekturu. Korisnička aplikacija (klijent) šalje zahtjev WebPay servisu (server) za autorizaciju određene sume u poruci koja predstavlja narudžbu robe i/ili usluge i čeka odgovor servisa. Ovakva komunikacija je asinkrona, tj. klijent nakon slanja zahtjeva ne dobiva trenutno odgovor već čeka odgovor od servisa. Razlog asinkrone komunikacije je u činjenici da je potrebno pričekati akcije kupca na strani servisa koje određuju konačni ishod transakcije.
Nakon uspješne autorizacije na strani banke WebPay servis (klijent) šalje poruku korisničkoj aplikaciji (server) koja sadrži podatke nužne za jednoznačno povezivanje entiteta na korisničkoj strani i strani servisa (narudžba i transakcija). Uloge servera i klijenta se zamjenjuju jer je komunikacija asinkrona. Za sinkronu komunikaciju između korisničke aplikacije i servisa koristite WebPay Direct varijantu.
Proces kupovine
Proces kupovine sastoji se od sljedećih koraka:
- kupac odabire robu i/ili usluge na strani korisničke aplikacije
- korisnička aplikacija šalje zahtjev za autorizaciju WebPay-u
- kupcu se prikazuje forma na strani webPay-a
- WebPay šalje zahtjev za autorizaciju banci
- WebPay šalje odgovor korisničkoj aplikaciji
Kupac odabire robu i/ili usluge na strani korisničke aplikacije
U ovom koraku korisnička aplikacija mora prikupiti podatke koji određuju narudžbu i podatke koji su nužni WebPay Form servisu za autorizaciju transakcije. Svaka narudžba mora imati svoj jedinstveni broj. Uobičajen način je korištenje baze podataka u koju se spremaju podaci o narudžbi prije slanja servisu. U tom slučaju auto increment polje osigurava jedinstvenost narudžbi. Podatke je potrebno provjeriti prije slanja servisu; poželjno je da ovaj uvjet uvijek bude ispunjen jer će u protivnom servis u produkcijskom režimu rada prikazati info stranicu.
Nakon što su podaci provjereni akciju slanja podataka započinje kupac pritiskom na gumb forme koja sadrži ispravne podatke.
Korisnička aplikacija šalje zahtjev za autorizaciju WebPay-u
Nakon što kupac odabere robu i/ili usluge i napravi narudžbu na strani korisničke aplikacije potrebno je HTTP POST metodom poslati podatke servisu u očekivanom formatu. Ovaj korak zahtjeva korištenje nekog programskog jezika jer treba osigurati jedinstveni broj za svaku narudžbu i provjeriti ispravnost podataka. Također treba izračunati SHA1 vrijednost koristeći vrijednosti iznosa, broja narudžbe i tajnog ključa.
Varijable koje je potrebno izračunati su sljedeće:
- order_number - jedinstveni broj narudžbe
- hash - SHA1(key+order_number+amount+currency)
NAPOMENA: argument sha1 funkcije je zbroj četiri varijable koje se zbrajaju kao stringovi.
Ostale nužne i opcionalne varijable, njihovi nazivi i dozvoljene vrijednosti koji se šalju servisu nalaze se u ovom dijelu dokumenta.
U cilju što lakše integracije postavili smo testni WebPay server i jednostavnu web dućan aplikaciju preko koje je moguće napraviti potpunu kupovinu s testnim brojevima kreditnih kartica. U svakom koraku kupnje vidljive su varijable koje izmjenjuju demo aplikacija i testni WebPay servis. Adresa web dućana je https://test.webpay.cc/shop, a postavke dućana su na https://test.webpay.cc/shop_admin. Prijava u administracijsko sučelje za demo prodajno mjesto je na adresi https://test.webpay.cc/login. Podaci za prijavu su sljedeći:
- korisničko ime: demo
- zaporka: webtehdemo
Testne brojeve kartica šaljemo na upit.
NAPOMENA: Testne kartice služe isključivo za izvršavanja plaćanja unutar prodajnih mjesta koja se nalaze na testnom Webtehovom serveru, a pristupa im se putem https://test.webpay.cc/login. Testne kartice nije moguće koristiti u produkcijskom načinu rada, tj. ako se prodajno mjesto nalazi na https://secure.webteh.hr/login.
Kupcu se prikazuje forma na strani WebPay-a
Kada su poslani podaci ispravni, kupcu se prikazuje forma na strani servisa. Kupac će pokrenuti postupak autorizacije ove narudžbe kada unese ispravne podatke sa svoje kreditne kartice, servis prije slanja zahtjeva za autorizaciju u banku provjerava podatke; ako bilo koji podatak nije ispravan ponovo se prikazuje forma i kupac može ispraviti naznačene pogreške.
NAPOMENA: Opcionalni podaci na strani servisa se mogu razlikovati u odnosu na one koje ste poslali jer ih kupac može promjeniti putem forme.
Izgled WebPay forme se može izmjeniti i prilagoditi vašim stranicama i kupac ne mora uopće vidjeti razliku između vaše aplikacije i servisa! Ukoliko želite izmjeniti izgled pročitajte ovaj dio.
Kupac u bilo kojem trenutku može odustati od kupnje pritiskom na gumb "Odustani" i vratiti se na stranu vaše aplikacije. Način i podaci koji se šalju korisničkoj aplikaciji za ovaj slučaj opisani su ovdje.
WebPay šalje zahtjev za autorizaciju banci
Nakon uspješne provjere unesenih podataka u formu servisa, WebPay šalje zahtjev banci za autorizaciju sume. Rezultat autorizacije (upit/odgovor između banke i servisa) čini jednu transakciju na strani servisa i sve transakcije su uvijek vidljive u administracijskom sučelju.
Autorizacija se uvijek događa u lipama neovisno o valuti koja je postavljena u dolaznoj poruci. Ishodi transakcija mogu biti dvojaki; može biti prihvaćena - autorizirana ili odbijena. Transakcija se odbija ako na kartici nema dovoljno sredstava, ako je kartica istekla itd. Svi ishodi transakcija predstavljeni su kodom i pripadajućim opisom koji je vidljiv u administracijskom sučelju. WebPay za ove ishode transakcija koristi koncept stanja - upravljanje transakcijama definirano je prelazima transakcija iz jednog stanja u drugo. Tablica svih kodova nalazi se ovdje.
WebPay šalje odgovor korisničkoj aplikaciji
Nakon procesiranja odgovora od banke servis šalje korisničkoj aplikaciji poruku o ishodu autorizacije. Ovaj korak se događa samo ako je uključena opcija postback u postavkama prodajnog mjesta i prije nego se kupcu prikaže stranica o uspješnoj autorizaciji. Način i podaci koji se šalju korisničkoj aplikaciji za ovaj slučaj opisani su ovdje.
WebPay servis nakon uspješne autorizacije prikazuje stranicu koja obavještava kupca o uspješnoj kupovini i za povratak na korisničku stranu kupac treba pritisnuti gumb "Natrag". Način i podaci koji se šalju korisničkoj aplikaciji za ovaj slučaj opisani su ovdje.
Podaci koje korisnička aplikacija šalje servisu
Tablice prikazuju nužne i opcionalne varijable koje se šalju servisu. Podaci se u testnoj fazi šalju na https://test.webpay.cc/, a u produkcijskoj na https://secure.webteh.hr/.
Nužne varijable
| varijabla | unaprijed određena vrijednost |
primjer | format | max. duljina |
opis |
|---|---|---|---|---|---|
| mode |
form | form |
string |
N/A | određuje mod rada servisa |
| store_id | N/A | 123 | integer | N/A | id prodajnog mjesta |
| order_number | N/A | order_123 | string | 30 | jedinstveni broj narudžbe |
| language | hr, en, it, de, fr, es, cz, hu, pl, ro, sk, sl, ru, se, nl | hr | string | N/A | jezik |
| currency |
AUD, CAD, CZK, DKK, HUF, JPY, NOK, SKK, SEK, CHF, GBP, USD, EUR, PLN, HRK | USD |
string | N/A | valuta iznosa narudžbe |
| amount | N/A | 123.54 | float |
N/A | iznos narudžbe s decimalnom točkom i dvije decimale |
| cart |
N/A | 2x SnowMaster 3000 |
string | 255 | opis narudžbe |
| hash | N/A | c9a53c3525e557da | string | 40 | sh1(key + order_number + amount + currency) |
Opcionalne varijable
| varijabla | unaprijed određena vrijednost | primjer |
format | max. duljina | opis |
|---|---|---|---|---|---|
| require_complete |
true/false |
true | string |
N/A | da li se narudžba predautorizira ili ne; zaobilazi postavku prodajnog mjesta |
| rewriteURL |
true | true | string |
N/A |
određuje format URL postavki |
| number_of_installments |
02,03,04...11,12 | 06 | string | N/A |
broj rata (samo za American Express i Diners) |
| recurring |
true/false | true | string | N/A | je li transakcija ponavljajuća ili ne |
| number_of_recurrings |
1, 2, 3, 4,...12 | 10 | string | N/A |
broj ponavljanja; default je 12 |
| cardholder_name |
N/A | Pero |
string | 20 | ime kupca |
| cardholder_surname |
N/A | Perić |
string | 20 | prezime kupca |
| cardholder_address | N/A | Ulica bb |
string |
40 | adresa kupca |
| cardholder_city | N/A | Zagreb |
string | 20 | grad kupca |
| cardholder_zip_code | N/A | 10000 |
string | 9 | poštanski broj kupca |
| cardholder_country | N/A | Hrvatska |
string | 30 | država kupca |
| cardholder_phone | N/A | 01/123-444 |
string | 30 | telefon kupca |
| cardholder_email | N/A | pero@pero.com |
string | 40 | email adresa kupca |
Podaci koje servis šalje korisničkoj aplikaciji nakon autorizacije
Ako u postavkama prodajnog mjesta uključite opciju postback i upišete postback_url vrijednost, servis će nakon uspješne autorizacije programski poslati HTTP POST zahtjev na taj URL sa slijedećim varijablama:
- order_number
- hash (SHA1(key+order_number))
- cc_type
- amount
- currency
- approval_code
Skripta ili koncept na tom URL-u može obraditi ovaj zahtjev i promjeniti stanje narudžbe koja je prethodno poslana na autorizaciju koristeći jedinstveni broj narudžbe order_number. Dozvoljeni timeout vašeg servera na kojem se događa ovaj proces je najviše 5 sekundi, nakon toga vremena servis prekida komunikaciju i u povijesti transakcije zapiše poruku o grešci - ERROR: postback URL timeout. Nakon što promjenite stanje narudžbe na vašoj strani uputno je odgovoriti na ovaj upit nekom jednostavnom porukom (čisti, sirovi tekst, bez html tagova) jer će ta poruka, tj. odziv na HTTP post zahtjev biti spremljen u povijest transakcije.
Nakon razmjene poruka između servisa i korisničke aplikacije o uspješnoj autorizaciji kupcu se prikazuje stranica koja sadrži detalje narudžbe i obavještava kupca o uspjeloj autorizaciji. Kupac sada može kliknuti na gumb "Natrag" i vratiti se natrag na vaše stranice. Ovo je opisano u sljedećem poglavlju.
Povratak kupca na stranu korisničke aplikacije nakon autorizacije
Nakon uspješne autorizacije kupac se preusmjerava (HTTP redirect) na adresu success url koja je određena u postavkama prodajnog mjesta sa GET parametrima:
- ako je opcija preusmjeri na success_url isključena: language, order_number
- ako je opcija preusmjeri na success_url uključena: order_number, hash, language, approval_code
PCI DSS dopušta korištenje samo standardnih portova što znači da success url ne smije sadržavati broj porta.
Primjer ispravne adrese na koju se kupac preusmjerava:
- http://www.domena.hr/success_order?language=en&order_number=12345.
Primjer neispravne adrese na koju se kupac preusmjerava:
- http://www.domena.hr:2200/success_order?language=en&order_number=12345.
Korištenjem ispravne success url adrese, kupca možete vratiti na dinamički generiranu stranicu koja npr. sadrži riječi zahvale i informacije o ostvarenoj narudžbi.
NAPOMENA: Ako se kod zahtjeva za autorizaciju koristi parametar rewriteURL=true URL izgleda http://www.domena.hr/success_order/en/12345. Potrebno je isključiti opciju preusmjeri na sucess_url kako bi parametar rewriteURL=true imao učinka.
Odustajanje kupca od autorizacije
Ako kupac ne želi autorizirati narudžbu može kliknuti na gumb "Odustani" na formi servisa. Tada se preusmjeravanjem vraća na stranu vaše aplikacije i to na adresu definiranu postavkom cancel url u postavkama prodajnog mjesta. Na taj URL se kupca preusmjerava sa slijedećim GET parametrima:
- language, order_number
Na ovaj način možete kupca pitati za razlog odustajanja i ponuditi mu mogućnost da ponovo pokrene proces autorizacije.
