API za upravljanje transakcijama
Dokumentacija za upravljanje transakcijama.
Uvod
Razmjena poruka servisa i korisničke aplikacije rezultira stvaranjem transakcije na strani servisa i narudžbe na strani korisničke aplikacije. Ova dva entiteta jednoznačno su povezana parametrom order_number i koristeći API servise moguće je tako stvorenom transakcijom upravljati iz vaše aplikacije. Upravljanje transakcijama podrazumjeva mjenjanja njihova stanja što u konačnici određuje da li je kupcu narudžba naplaćena ili otkazana. Postoje sljedeća stanja transakcije:
- autorizirana - trgovac je prebacio sredstva s kartice na svoj račun
- predautorizirana - trgovac je rezervirao sredstva na kartici, transakciju treba kompletirati ili otkazati
- kompletirana - predautorizirana transakcija je kompletirana i sredstva su prebačena na račun trgovca
- otkazana - predautorizirana transakcija je poništena i trgovac nije naplatio narudžbu
Prelazi iz ovih stanja određeni su akcijama koje je moguće napraviti putem administracijskog sučelja ili programski koristeći API servise. Akcije je moguće izvesti programski preko API-ja. Svaka akcija ima svoj URL na strani servisa na koji se šalje HTTP POST zahtjev za izvršenje željene akcije. Servis na taj zahtjev odgovara XML porukom iz koje je porebno izdvojiti parametar response_code koji određuje ishod transakcije. Lista svih kodova i njihova značenja prikazani su u tablici:
| response_code | značenje (en) |
značenje (hr) |
|---|---|---|
| 0 |
approved/accepted | odobreno |
| 100 |
declined |
odbijeno |
| 109 |
invalid service establishment |
nepostojeće prodajno mjesto |
| 400 | refund accepted |
odobren povrat |
| 909 |
technical errorr / unable to process request | greška u sustavu |
| 912 |
host link down |
izdavatelj kartice nedostupan |
| 930 |
transaction not found |
transakcija nije pronađena |
| 931 |
transaction voided/refunded | transakcija je poništena |
| 2000 |
internal error |
greška u sustavu |
Parametri koji se šalju u POST polju su sljedeći:
- store_id - jedinstveni broj prodajnog mjesta
- order_number - jedinstveni broj narudžbe
- hash -SHA1(key+order_number+store_id)
Primjer XML odgovora na ispravno poslani zahtjev pogledajte ovdje.
Poništenje transakcije
Ukoliko je transakcija autorizirana i želi se izvršiti povrat sredstava, potrebno je na adresu https://secure.webteh.hr/refund poslati HTTP POST zahtjev s pripadajućim parametrima.
Ako je transakcija predautorizirana i želi se poništiti potrebno je na adresu https://secure.webteh.hr/cancel poslati HTTP POST zahtjev s pripadajućim parametrima.
Poništenje na manji iznos
Ukoliko je transakcija autorizirana i želi se kupcu vratiti određeni dio sredstava potrebno je na adresu https://secure.webteh.hr/partial_refund poslati HTTP POST zahtjev s pripadajućim parametrima. Uz standardne parametre potrebno je poslati i varijablu new_amount koja određuje novi iznos u originalnoj valuti.
Potvrda transakcije
Ukoliko je transakcija predautorizirana i želi se potvrditi, tj. sredstva s kartice se žele prebaciti na račun trgovca potrebno je na adresu https://secure.webteh.hr/complete poslati HTTP POST zahtjev s pripadajućim parametrima.
Potvrda na manji iznos
Ukoliko je transakcija predautorizirana i želi se autorizirati samo djelomičan iznos potrebno je na adresu https://secure.webteh.hr/partial_complete poslati HTTP POST zahtjev s pripadajućim parametrima. Uz standardne parametre potrebno je poslati i varijablu new_amount koja određuje novi iznos u originalnoj valuti.
NAPOMENA: Predautoriziranu transakciju koja se nalazi se u stanju čekanja (potvrde ili poništenja) duže od 28 dana, nije moguće potvrditi ili poništiti, te se ona automatski poništava. Nakon isteka 28 dana od trenutka predautorizacije transakcije, trgovac se ne može naplatiti. Primjer XML odgovora na poslani zahtjev za potvrdom ili poništenjem takve transakcije pogledajte ovdje.
