WebPay Direct API

— Kategorije: 3-D secure, Dokumentacija, WebPay

Dokumentacija za WebPay Direct integraciju.

Uvod

Ovaj dokument namjenjen je svim stranama zainteresiranim za integraciju WebPay Direct 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
posjedovanje SSL certifikata
razvojni tim koji poznaje neku od serverskih tehnologija (PHP, Python, Ruby...)
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 Direct servis?

WebPay Direct servis koristi klijent-server arhitekturu. Korisnička aplikacija (klijent) šalje zahtjev servisu (server) za autorizaciju određene sume u poruci koja predstavlja narudžbu robe i/ili usluge i čeka odgovor servisa. Komunikacija je sinkrona, tj. razmjena informacija između korisničke aplikacije i servisa događa se u jednom request/response ciklusu. Za razliku od Webpay Form varijante vaša aplikacija mora poslati i kartične podatke servisu i stoga je stranice na kojima se ti podaci prikupljaju nužno zaštititi SSL sigurnosnim protokolom.

Nakon što su prikupljeni i provjereni svi potrebni podaci poslani servisu, WebPay će pokušati narudžbu autorizirati u banci zaprimatelju. Odgovor servisa je u XML ili YAML formatu i potrebno ga je na odgovarajući način obraditi i iz njega izdvojiti informacije koje određuju ishod transakcije.

Postoje dvije vrste odgovora servisa, jedan je kada su poslani neispravni podaci i drugi je kada su poslani ispravni podaci.

Korisnička aplikacije šalje ispravne podatke servisu

Korisnička aplikacija mora prikupiti podatke koji određuju narudžbu i podatke koji su nužni WebPay Direct 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. Podatake 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 odbijati zahtjeve za autorizaciju s porukom o greškama.

NAPOMENA: Odziv servisa sa greškama nemojte koristiti za validaciju podataka na vašoj strani, koristite vlastite validatore!

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 triju varijabli 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.

Nakon što su podaci provjereni akciju slanja podataka započinje kupac pritiskom na gumb forme koja sadrži ispravne podatke. Servis tada obradi zahtjev i pošalje banci zahtjev za autorizaciju ako su svi poslani podaci ispravni. Servis procesira odziv banke i generira odziv vašoj aplikaciji u XML ili YAML formatu. Primjer takvog odziva u XML formatu pogledajte ovdje. Ovakav odziv potrebno je obraditi i pomoću jedinstvenog broja narudžbe order_number ažurirati narudžbu na vašoj strani. Podatak u tom XML dokumentu koji određuje ishod transakcije je response_code i ovdje je dana tablica sa svim vrijednostima tog parametra i njihova značenja:

response_code	značenje (en)	značenje (hr)	poruka kupcu
0	approved/accepted	odobreno	uspješna kupovina - prikazati kupcu approval_code
12	error invalid transaction	nepostojeća transakcija	neuspješna kupovina
30	error format error	pogrešan format podataka	neuspješna kupovina
31	bank not supported by switch	banka nema podršku switcha	neuspješna kupovina
41	lost card	kartica je izgubljena	neuspješna kupovina - kartica je prijavljena kao izgubljena
43	stolen card	ukradena kartica	neuspješna kupovina
51	not sufficient funds	na kartici nema dovoljno sredstava	neuspješna kupovina - na kartici nema dovoljno sredstava
54	expired card	kartica je istekla	neuspješna kupovina - kartica je istekla
56	invalid expiration date	netočan datum isteka kartice	neuspješna kupovina - provjeriti datum isteka kartice
57	do not honor	kartica nije prihvaćena	neuspješna kupovina - kartica nije prihvaćena
58	invalid transaction	nije moguće izvršiti transakciju	nemoguća kupovina - nije moguće izvršiti transakciju
79	declined cvv2	odbijen cvv2	neuspješna kupovina
89	bad terminal id	pogrešan terminal id	neuspješna kupovina
91	issuer or switch not inoperative	neoperabilnost sa davateljem usluge ili switchom	neuspješna kupovina
94	duplicate transmission	višestruko slanje istih podataka	neuspješna kupovina
96	sistem malfunction	neispravnost u radu sustava	neuspješna kupovina
100	declined	odbijeno	neuspješna kupovina - kartica je odbijena
101	expired card	kartica je istekla	neuspješna kupovina - kartica je istekla
109	invalid service establishment	nepostojeće prodajno mjesto	neuspješna kupovina
111	card not on file	nepostojeći broj kartice	neuspješna kupovina
121	limit exceeded	prekoračen limit	neuspješna kupovina - prekoračen limit
909	technical errorr / unable to process request	greška u sustavu	neuspješna kupovina - ponoviti transakciju kroz par minuta
912	host link down	izdavatelj kartice nedostupan	neuspješna kupovina - ponoviti transakciju kroz par minuta
1001	card expired	odbijeno	neuspješna kupovina
1002	card suspicious	odbijeno	neuspješna kupovina
1003	card suspended	odbijeno	neuspješna kupovina
1004	card stolen - pickup	odbijeno	neuspješna kupovina
1005	card lost	odbijeno	neuspješna kupovina
1011	card not found	odbijeno	neuspješna kupovina
1012	cardholder not found	odbijeno	neuspješna kupovina
1014	account not found	odbijeno	neuspješna kupovina
1015	invalid request	odbijeno	neuspješna kupovina
1016	not sufficient funds	odbijeno	neuspješna kupovina
1017	previously reversed	odbijeno	neuspješna kupovina
1018	previously reversed	odbijeno	neuspješna kupovina
1019	further activity prevents reversal	odbijeno	neuspješna kupovina
1020	further activity prevents void	odbijeno	neuspješna kupovina
1021	original transaction has been voided	odbijeno	neuspješna kupovina
1023	only 3D full authenticated transactions are allowed with empty CVV	odbijeno	neuspješna kupovina
1050	declined	odbijeno	neuspješna kupovina
2000	internal error	greška u sustavu	neuspješna kupovina - ponoviti transakciju kroz par minuta
2001	internal error	greška u sustavu	neuspješna kupovina - ponoviti transakciju kroz par minuta
2002	internal error	greška u sustavu kod upravljanja transakcijama	neuspješna kupovina - ponoviti transakciju kroz par minuta
2010	3d secure error, not authenticated	3d secure pogreška, identitet nije potvrđen	neuspješna kupovina - 3D secure provjera identiteta nije uspjela. Potvrdite svoj identitet ili koristite drugu karticu.
2011	3d secure error, time expired	3d secure pogreška, vrijeme za provjeru je isteklo	neuspješna kupovina - vrijeme za 3D secure provjeru je isteklo. Pokrenite proces ponovo potvrdite identitet unutar 15 minuta.
2012	3d secure error, store policy	3d secure pogreška, prodajno mjesto ne prima kartice bez 3D secure podrške	neuspješna kupovina - kartica nije u 3D secure programu i zato je odbijena. Aktivirajte 3D secure podršku za svoju karticu ili koristite drugu.
2100	declined - risk alert	odbijeno	neuspješna kupovina - broj ponavljanja je prekoračen
2101	declined - risk alert	odbijeno	neuspješna kupovina - iznos narudžbe je veći od ograničenja
2102	declined - risk alert	odbijeno	neuspješna kupovina - iznos narudžbe je manji od ograničenja
2200	declined - fraud alert	odbijeno	neuspješna kupovina - transakcija je obustavljena
2201	declined - fraud error	odbijeno	neuspješna kupovina
5001	RISK: Number of repeats per PAN	odbijeno	neuspješna kupovina
5003	RISK: Number of repeats per BIN	odbijeno	neuspješna kupovina
5005	RISK: Percentage of declined transactions	odbijeno	neuspješna kupovina
5006	RISK: Number of refunded transactions	odbijeno	neuspješna kupovina
5007	RISK: Percentage increment of sum on amount of refunded transactions	odbijeno	neuspješna kupovina
5009	RISK: Number of chargebacks	odbijeno	neuspješna kupovina
5010	RISK: Sum on amount of chargebacks	odbijeno	neuspješna kupovina
5011	RISK: Number of retrieval requests	odbijeno	neuspješna kupovina
5012	RISK: Sum on amount of retrieval requests	odbijeno	neuspješna kupovina
5013	RISK: Average amount per transaction	odbijeno	neuspješna kupovina
5014	RISK: Percentage increment of average amount per transaction	odbijeno	neuspješna kupovina
5015	RISK: Percentage increment of number of transactions	odbijeno	neuspješna kupovina
5016	RISK: Total sum on amount	odbijeno	neuspješna kupovina
5017	RISK: Percentage increment of total sum on amount	odbijeno	neuspješna kupovina
5018	RISK: Minimum amount per transaction	odbijeno	neuspješna kupovina
5019	RISK: Maximum amount per transaction	odbijeno	neuspješna kupovina
5020	RISK: Number of approved transactions per PAN	odbijeno	neuspješna kupovina
5021	RISK: Sum on amount of approved transactions per PAN	odbijeno	neuspješna kupovina
5022	RISK: Sum on amount of approved transactions per BIN	odbijeno	neuspješna kupovina
5023	RISK: Number of approved transactions per PAN and MCC on amount	odbijeno	neuspješna kupovina
5050	RISK: Number of repeats per IP	odbijeno	neuspješna kupovina
5051	RISK: Number of repeats per cardholder name	odbijeno	neuspješna kupovina
5052	RISK: Number of repeats per cardholder e-mail	odbijeno	neuspješna kupovina

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

Korisnička aplikacije šalje neispravne podatke servisu

U ovom slučaju servis odgovara vašoj aplikaciji porukom čiji sadržaj prikazuje pogreške nakon procesiranja zahtjeva za autorizaciju. Upit prema banci se u ovom slučaju nije dogodio. Primjer takvog odgovora pogledajte ovdje.

NAPOMENA: Odziv servisa sa greškama nemojte koristiti za validaciju podataka na vašoj strani, koristite vlastite validatore!

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	post	post	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	>= 1.00	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)
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
ip	N/A	127.0.0.2	string	N/A	IP adresa vlasnika kartice
card_details*	N/A	377512345678	string	16	broj kreditne kartice
card_verification_data**	N/A	4378	string	3-4	sigurnosni kod koji se nalazi na poleđini kreditne kartice
cc_year ***	N/A	11	string	2	godina do koje kartica vrijedi, šalje se u obliku 12 za 2012 godinu, kako je ispisan na kartici
cc_month ***	N/A	05	string	2	mjesec do kojeg vrijedi kartica, šalje se u obliku 09,10,11...

* Broj kreditne kartice potrebno je provjeriti Luhnovim algoritmom. Prodajno mjesto dužno je provjeriti upisanu duljinu broja kartice.

** Card Security Code - CVV/CVC2. Prodajno mjesto dužno je provjeriti upisanu duljnu za CVV/CVC2. Maestro kartice mogu i ne moraju imati CVV. Ako Maestro kartica ima CVV onda se taj podatak unosi prilikom plaćanja, a ako ga nema, onda se CVV ostavlja prazan.

*** Datum isteka kartice ne smije biti u prošlosti.

NAPOMENA: prodajno mjesto koje koristi WebPay Direct dužno je provjeravati ispravnost poslanih vrijednosti prema gornjoj tablici.

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
number_of_installments	02,03,04...11,12	06	string	N/A	broj rata (samo za American Express i Diners kartice)
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

Sekcije