Plačilni prehod API: vodnik za implementacijo in testiranje
October 6, 2026
Plačilni prehod API je programski vmesnik, ki vašo aplikacijo ali spletno trgovino neposredno poveže s kartičnimi shemami in bankami, brez ročnega preklapljanja med sistemi. Z njim avtomatizirate inicializacijo plačila, potrditev in poročanje, hkrati pa zmanjšate površino za napake pri ravnanju s podatki o kartici. V nadaljevanju razložimo tehnični potek, varnostne zahteve iz PSD2 in konkreten primer, kako to v praksi izvede UJP e-plačila.
Na kratko:
- Za integracijo plačilnega prehoda je najprimernejši hostani model, če želite hitro in enostavno rešitev brez večjih razvojnih vložkov.
- Uporaba API ključa, nonce in časovnega žiga je nujna za varno avtentikacijo, preverjati jo je treba s SHA256 podpisom.
- Pri podpiranih izvedbah je najbolje začeti s testnim okoljem, preveriti vse endpointov in simulirati tudi neuspešne transakcije.
- PSD2 zahteva vključitev močne avtentikacije, zato je pomembno upoštevati smernice glede redirection, embedded ali decoupled pristopov.
- Cena za uporabo API-jev je odvisna od izbrane rešitve, pri PosSlo pa so provizije konkurenčne in vključujejo brezplačno evropsko SIM kartico.
Vsaka plačilna transakcija prek API-ja sledi podobnemu vzorcu, ne glede na to, ali gre za spletno trgovino, naročniško storitev ali plačilo javne storitve. Trgovčeva aplikacija pokliče prehod, prehod komunicira z izdajateljem kartice ali banko, rezultat pa se vrne nazaj v obliki statusa in, pogosto, asinhronega webhooka.
/transaction/init) in pošlje znesek, valuto ter identifikator naročila./transaction/status), da preveri trenutno stanje ali uskladi knjigovodstvo.Pri hostanih rešitvah uporabnika preusmerite na stran prehoda, kjer vnese podatke o kartici, kar pomeni, da se tokenizacija zgodi zunaj vašega strežnika. Tokenizacija zamenja dejansko številko kartice z enkratnim ali ponovno uporabljivim žetonom, zato se podatki o kartici nikoli ne shranijo na vaši infrastrukturi. To neposredno zmanjša obseg zahtev standarda PCI DSS, ki jih mora vaše podjetje izpolniti, saj se odgovornost za varovanje surovih podatkov prenese na prehod ali banko.
Razlika med sinhronim odgovorom API klica in asinhronim webhookom je ena najpogostejših točk zmede pri razvoju. Sinhroni odgovor pove le, da je bila zahteva sprejeta, medtem ko webhook prinese dokončen status, zato implementacija, ki se zanaša samo na prvi odgovor, lahko spregleda pozneje zavrnjena plačila.
Izbira integracijskega modela je ena najpomembnejših odločitev pri uvajanju plačilnega prehoda API, saj neposredno vpliva na razvojni čas, varnostno odgovornost in uporabniško izkušnjo.
Za podjetja z omejenimi razvojnimi viri je hostani model praviloma najhitrejša pot do delujoče rešitve, saj zahteva le preusmeritev in obdelavo povratnega klica. Podjetja z lastno razvojno ekipo in zahtevo po popolnoma brezšivnem nakupnem toku pogosteje izberejo vgrajena polja ali neposredno povezavo, še posebej če prodajajo na več trgih in potrebujejo prilagojene plačilne metode glede na državo kupca. Naročniški modeli skoraj vedno zahtevajo tokenizacijo, ne glede na to, kateri od zgornjih pristopov uporabljate za prvo transakcijo.
Evropska direktiva PSD2 je uvedla zahtevo po močni ventilacijskih (avtentikacijskih) kupca (SCA) za večino spletnih kartičnih plačil, kar neposredno vpliva na to, kako oblikujete tok plačila v API-ju. Smernice Evropskega bančnega organa.pdf) pojasnjujejo, da ne obstaja ena sama pravilna oblika implementacije, saj se redirection, embedded in decoupled pristopi razlikujejo po tehnični izvedljivosti in uporabniški izkušnji, izbira pa mora upoštevati tudi zahteve skladnosti. Novejše pojasnilo EBA dodatno razčlenjuje, kako redirection pristop vpliva na zahteve SCA in kdaj je dovoljena ponovna uporaba istih avtentikacijskih faktorjev pri kombiniranih storitvah dostopa do računa in inficiranja plačil.
Dinamično povezovanje (Danami linking) zahteva, da je avtentikacijska koda vezana na točen znesek in prejemnika posamezne transakcije, kar pomeni, da generičen enkratni PIN ni dovolj, API pa mora znesek posredovati v avtentikacijski korak.
Pri praktični implementaciji priporočamo naslednje ukrepe:
Uporaba hostanih polj in ionizacije ostaja eden od najbolj zanesljivih načinov za zmanjšanje obsega PCI DSS, saj surovi podatki o kartici nikoli ne dosežejo vašega strežnika, kot izpostavlja tudi primerjava plačilnih rešitev na slovenskem trgu.
Večina plačilnih prehodov API uporablja podoben nabor endpointov in avtentikacijskih vzorcev, zato je smiselno poznati tipično strukturo, preden se lotite izbire konkretnega ponudnika. Referenčna dokumentacija Qualpay na primer prikazuje standarden nabor operacij: avtorizacijo, zajem sredstev (capture), vračilo, tokenizacijo in upravljanje paketnih obdelav (batch).
Osnovni gradniki, ki jih boste potrebovali pri skoraj vsaki integraciji, so:
Spodnja tabela povzema tipične elemente, na katere naletite pri integraciji plačilnega prehoda API, na primeru vzorca, kakršnega uporablja UJP e-plačila.
| Element | Opis | Primer uporabe |
|---|---|---|
| Inicializacijski endpoint | POST zahteva za začetek plačila | /api/v1/{apiKey}/transaction/init |
| Statusni endpoint | GET zahteva za preverjanje stanja | /transaction/status/{transactionId} |
| Avtentikacija | Uporabniško ime sestavljeno iz apiKey, nonce in timestamp | geslo kot SHA256 zgoščena vrednost |
| Testno okolje | Ločena domena za preizkušanje pred produkcijo | testeplacila.ujp.gov.si |
| Specifikacija | OpenAPI dokument za samodejno generiranje klienta | datoteka swagger.json |
Preden integracijo postavite v produkcijo, uvozite ponujeno OpenAPI specifikacijo (swagger.json) v orodje, kot je Postman ali Swagger UI, saj to pospeši testiranje in zmanjša napake pri ročnem sestavljanju zahtev. Pri webhookih vedno preverite, da prejeti URL ustreza pričakovani domeni in da je vsebina JSON skladna s shemo, ki jo prehod dokumentira, sicer tvegate sprejemanje ponarejenih obvestil.
Preden integracijo preklopite v produkcijsko okolje, velja preveriti nekaj ključnih točk, ki v praksi najpogosteje povzročijo težave šele po zagonu.
Sinhronizacija nonce in časovnega žiga ter pravilna sestava podpisa zahteve ostajata med najpogostejšimi viri napak pri integraciji, zato je smiselno v testno rutino vključiti tudi simulacijo zakasnjenih in podvojenih zahtevkov.
Strokovni nasvet: preden integracijo objavite, nastavite spremljanje neuspešnih webhookov z opozorili po posti ali v nadzorni plošči, da neuspele transakcije ne ostanejo neopažene.
Za monitoring priporočamo beleženje vsake zavrnjene ali nedokončane transakcije v ločeno čakalno vrsto za ponovno obdelavo, saj to prepreči izgubo naročil zaradi začasnih omrežnih težav. Testno fazo smiselno razdelite na teden dni funkcionalnega testiranja in dodaten teden spremljanja v nizko tveganem produkcijskem okolju, preden integracijo v celoti zaženete.
Dober konkreten primer državnega plačilnega prehoda API je UJP e-plačila, ki omogoča plačevanje javnih storitev prek enotnega vmesnika. Inicializacija transakcije poteka prek klica POST na https://eplacila.ujp.gov.si/api/v1/{apiKey}/transaction/init, ki ob uspehu vrne identifikator transakcije in URL za preusmeritev uporabnika na plačilno stran. Stanje transakcije nato preverite prek klica GET na /transaction/status/{transactionId}, pri čemer je struktura odgovora enaka strukturi, ki jo UJP pošlje v asinhronem Webhook.
Avtentikacijska shema je dober primer vzorca, ki ga pogosto srečate tudi pri drugih prehodih: uporabniško ime je sestavljeno kot {apiKey}.{nonce}.{timestamp}, geslo pa je hex-enkodirana SHA256 zgoščena vrednost niza, ki vključuje skupno skrivnost in naslov zahtevanega URL-ja. Ta pristop zahteva natančno sinhronizacijo časa med vašim strežnikom in strežnikom prehoda, sicer zahteve zavrne.
UJP nudi ločeni okolji, produkcijsko na
eplacila.ujp.gov.siin testno natesteplacila.ujp.gov.si, skupaj s priloženo specifikacijo OpenAPI (swagger.json) za samodejno generiranje odjemalca.
Za podjetja, ki sprejemajo plačila javnih storitev ali sodelujejo z javnim sektorjem, je vključitev v sistem UJP pogosto administrativni korak, ki zahteva predhodno registracijo in dodelitev API ključa, zato je smiselno ta proces začeti dovolj zgodaj pred načrtovanim zagonom storitve. Primer UJP dobro ponazarja, zakaj je branje priložene tehnične dokumentacije in testiranje v ločenem okolju nujno, preden se lotite produkcijske uvedbe katerega koli plačilnega prehoda API.
Podjetja z lastno razvojno ekipo in jasno opredeljenim produktom pogosto upravičeno izberejo neposredno integracijo, saj si s tem zagotovijo popoln nadzor nad uporabniško izkušnjo. Manjša podjetja brez stalne razvojne podpore si po naših izkušnjah bolje pomagajo s hostanim modelom ali z gotovo rešitvijo, saj se tako izognejo tveganju, da varnostna plat integracije ostane nedokončana. Pri izbiri modela velja realno oceniti, koliko časa lahko razvojna ekipa nameni vzdrževanju avtentikacijske logike in spremljanju webhookov, ne le začetni postavitvi.
Pri spletnih plačilnih rešitvah, ki so na voljo na trgu, pogosto najdemo instantna izplačila, brez mesečnih stroškov in konkurenčne tarife, kar podjetjem z omejenim proračunom olajša odločitev med lastnim razvojem in gotovo rešitvijo. Pri POS terminalih je pogosto vključena sim kartica za prenos podatkov, kar je uporabno za podjetja, ki delujejo na več lokacijah ali sezonsko prodajajo zunaj matične trgovine.
— PosSlo
Ko se odločate med razvojem lastne integracije in gotovo rešitvijo, cenovna preglednost pogosto odloči hitreje kot tehnične podrobnosti. Pri PosSlo ponujamo nabor rešitev, ki pokrijejo tako spletno kot fizično prodajno mesto, brez mesečnih stroškov in z instantnimi izplačili na vaš račun.
Za podjetja, ki iščejo konkretno rešitev, ponujamo:
Vsi terminali vključujejo brezplačno evropsko SIM kartico, provizije pa ostajajo konkurenčne ne glede na obseg prodaje. Oglejte si ponudbo na Posslo in nas kontaktirajte za konkretno ponudbo, prilagojeno vašemu poslovanju.
Plačilni prehod API je programski vmesnik, ki aplikaciji ali spletni trgovini omogoči neposredno pošiljanje in prejemanje podatkov o plačilih brez ročnega vnosa. Uporablja se za avtorizacijo, potrditev in sledenje statusu transakcij med trgovcem, banko in kartično shemo.
Večina prehodov zahteva kombinacijo API ključa, enkratnega nonce in časovnega žiga, zahteve pa podpiše s kriptografskim zgoščevanjem, ki vključuje skupno skrivnost. Primer takega vzorca uporablja UJP e-plačila, kjer je uporabniško ime sestavljeno iz apiKey, nonce in timestamp, geslo pa SHA256 zgoščena vrednost.
Pri hosted modelu uporabnika preusmerite na stran prehoda, kar skrajša razvojni čas in zmanjša obseg zahtev PCI DSS. Pri embedded modelu je obrazec vizualno vdelan v vašo stran, kar izboljša uporabniško izkušnjo, a zahteva nekoliko večjo tehnično odgovornost.
Direktiva PSD2 zahteva močno ventilacijo kupca za večino spletnih kartičnih plačil, kar morate vgraditi v tok plačila že pri zasnovi API-ja. Smernice Evropskega bančnega organa pojasnjujejo, da izbira med redirection, embedded in decoupled pristopi vpliva na to, kako zahtevo izpolnite.
Cena je odvisna od izbrane rešitve, zato konkretno ponudbo za spletna plačila ali provizije kartičnih plačil pridobite na podlagi povpraševanja. Ponujamo brez mesečnih stroškov in z instantnimi izplačili ne glede na izbrano rešitev.
