WEB integracija

Leanpay je v spletni trgovini na voljo kot eden od načinov plačila — kupec ob nakupu izbere obročno odplačevanje namesto plačila v enem znesku. Za trgovca je integracija enkratno opravilo: ko je vzpostavljena, Leanpay deluje samodejno ob vsakem nakupu.

V osnovi sta potrebna dva klica. Prvi je Token Request: strežnik pošlje podatke o naročilu in prejme enkratni token, s katerim se kupca preusmeri na Leanpay, kjer izpolni vlogo in z Leanpayem sklene pogodbo. Drugi je Delivery: ko je naročilo odpremljeno, trgovec o tem obvesti Leanpay, s čimer transakcija preide v izplačilo.

Vse vmesne korake — preverjanje, podpis in odločitev o odobritvi — izvede Leanpay. Po zaključku transakcije Leanpay pošlje status callback, prek katerega se stanje naročila v sistemu trgovca posodobi samodejno.

Potek je razdeljen na dva dela. V checkout fazi kupec na blagajni zaključi nakup; ta del se odvije v nekaj minutah in se konča s status callbackom. Postcheckout faza sledi kasneje, ob pripravi naročila za odpremo, ko se preveri verifikacija kupca in potrdi dostava. Med fazama lahko mine tudi nekaj dni.

Potek plačila

Kupec ob zaključku nakupa izbere Leanpay. Strežnik trgovca pri Leanpayu pridobi token in z njim preusmeri kupca na Leanpayevo stran, kjer ta izpolni vlogo in z Leanpayem sklene pogodbo. Po odločitvi Leanpay obvesti sistem trgovca o izidu, kupca pa vrne nazaj v trgovino.

Token je osrednji element checkout faze. Pridobi se z izmenjavo med strežnikom trgovca in Leanpayem, ki se zgodi, preden kupec sploh pride na Leanpayevo stran.

Izmenjava tokena med strežnikom in Leanpayem — Izmenjava tokena med strežnikom trgovca in Leanpayem.

Checkout faza

Kupec izbere Leanpay

Kupec napolni košarico in pride do plačila. Med ponujenimi načini (kartice, PayPal, nakazilo) izbere Leanpay. Od tu naprej postopek vodi strežnik trgovca.

Token Request

POST/vendor/token

Strežnik pošlje Leanpayu podatke o naročilu, Leanpay jih preveri in vrne enkratni token. Kupčev brskalnik v tem koraku ni vključen — gre za klic med strežnikoma. API ključ potuje v request bodyju; Web integracija ne uporablja avtentikacijskih headerjev.

Kaj pošljemo — JSON body:

POST /vendor/token HTTP/1.1
Host: app.leanpay.si
Content-Type: application/json

{
  "vendorApiKey": "wk_live_xyz789...",
  "vendorTransactionId": "ORDER-2026-05-21-00813",
  "amount": 299.00,
  "language": "sl",
  "vendorFirstName": "Janez",
  "vendorLastName": "Novak",
  "vendorPhoneNumber": "38640123456",
  "successUrl": "https://trgovina.si/checkout/success?order=ORDER-2026-05-21-00813",
  "errorUrl": "https://trgovina.si/checkout/error?order=ORDER-2026-05-21-00813",
  "CartItems": {
    "name": "Pralni stroj X200",
    "sku": "SKU-001",
    "price": 299.00,
    "qty": 1
  }
}

Podatki o kupcu (vendorPhoneNumber, ime) niso obvezni, a koristijo: če Leanpay po telefonski številki prepozna že verificiranega kupca, ga na svoji strani vodi po hitrejši poti. URL za status callback ni del tega klica — nastavi se enkrat v Vendor profilu. Nanj Leanpay pošlje končni status, zato mora biti dosegljiv prek HTTPS in z Leanpayevih IP-jev.

Kaj Leanpay vrne — token:

{
  "token": "375e39ad91434c019e2b6ef0ce17b221"
}

ℹToken je enkraten in se razlikuje od vendorTransactionId. vendorTransactionId je oznaka naročila na strani trgovca in se uporablja v vseh nadaljnjih klicih (callback, dostava, spor).

Preusmeritev na Leanpay

Z dobljenim tokenom se kupca preusmeri na Leanpay — z odgovorom HTTP 302 ali prek window.location. Token se posreduje kot parameter.

https://app.leanpay.si/vendor/checkout?token=375e39ad91434c019e2b6ef0ce17b221

Kupec na Leanpayevi strani

Nadaljnji potek je odvisen od tega, ali Leanpay kupca že pozna (po telefonski številki iz prejšnjega koraka).

Verificiran kupec (hitra pot)

Leanpay kupca prepozna in že ima njegove podatke. Pogodba je predizpolnjena, kupec le potrdi obročni načrt in podpiše — običajno v manj kot minuti. Izid je SUCCESS, ob zavrnitvi FAILED, ob preklicu CANCELED.

Neverificiran kupec

Kadar Leanpay kupca še ne pozna ali nima vseh podatkov, jih kupec vnese sam (osebni in dokumentni podatki). To vzame nekaj minut. Možni so trije izidi:

SUCCESS takoj, če Leanpay vlogo odobri.
Leanpay lahko zahteva dodatna dokazila (na primer dokazilo o dohodku). Kupec ima zanje do 72 ur, transakcija medtem čaka. Po kupčevem odgovoru je izid SUCCESS ali FAILED.
FAILED takoj, če je kupec zavrnjen.

⚠Če kupec stran zapusti (zapre zavihek ali pusti napravo), transakcija po približno eni uri preide v EXPIRED. To ni napaka — kupec lahko postopek znova začne iz košarice.

Status callback

Ko transakcija doseže končno stanje, Leanpay pošlje POST callback na notificationUrl iz Vendor profila. Ta callback je edini zanesljiv vir resnice — preusmeritev brskalnika nazaj v trgovino je zgolj informativna in se nanjo pri izpolnjevanju naročil ne gre zanašati.

Kaj Leanpay pošlje — JSON body, podpisan z md5Signature:

{
  "leanPayTransactionId": "LP-987654321",
  "vendorTransactionId": "ORDER-2026-05-21-00813",
  "amount": 299.00,
  "status": "SUCCESS",
  "md5Signature": "a1b2c3d4e5f6..."
}

Status	Pomen	Ukrep
`SUCCESS`	Kupec je dokončal in podpisal; vloga je potrjena. Ali je s tem tudi dokončno odobrena, je odvisno od verifikacije (glej postcheckout fazo).	Nadaljuj v postcheckout fazo.
`CANCELED`	Kupec je aktivno preklical pred dokončanjem.	Naročila ne izpolni.
`EXPIRED`	Kupec je opustil; potekel je časovni rok.	Naročila ne izpolni.
`FAILED`	Vloga ni bila uspešna (zavrnitev ali napaka).	Naročila ne izpolni.

Handler naj opravi štiri naloge: preveri md5Signature, preden zaupa podatkom; posodobi status naročila; hitro vrne HTTP 200; in deluje idempotentno, saj lahko isti callback prispe večkrat.

⚠SUCCESS pomeni, da je vloga potrjena — ne nujno, da je kredit dokončno odobren. Če je kupec verificiran, je vloga dokončno potrjena. Če ni verificiran, je vloga potrjena le na podlagi podatkov, ki jih je podal, in dokler verifikacija ni opravljena, dokončen izid ni zagotovljen. Zato samo SUCCESS še ni zadosten pogoj za odpremo — najprej preveri status verifikacije v postcheckout fazi. Če Leanpay ne prejme odgovora HTTP 200, callback ponovi do desetkrat, zato mora biti handler idempotenten.

Kako preveriti md5Signature

md5Signature je 128-bitni MD5 povzetek, izražen kot 32 šestnajstiških znakov z malimi črkami. Za preverjanje se rekonstruira niz, ki ga je Leanpay podpisal, izračuna MD5 in primerja z vrednostjo iz callbacka. Niz je spoj petih vrednosti v točno tem vrstnem redu:

leanPayTransactionId — kot v callbacku
vendorTransactionId — kot v callbacku
MD5 secret besede — ne sama beseda, ampak MD5 hex njenih ASCII bajtov
amount — z natanko dvema decimalkama (na primer 299.00)
status — kot v callbacku (na primer SUCCESS)

Primer v Javi (Spring DigestUtils):

StringBuilder sb = new StringBuilder();
sb.append(leanPayTransactionId);                          // 1
sb.append(vendorTransactionId);                           // 2
sb.append(DigestUtils.md5DigestAsHex(secret.getBytes())); // 3 — MD5 secret besede
sb.append(new DecimalFormat("0.00").format(amount));   // 4 — dve decimalki
sb.append(status);                                        // 5
return DigestUtils.md5DigestAsHex(sb.toString().getBytes());

Testni primer: leanPayTransactionId="123456789", vendorTransactionId="987654321", secret="secret", amount=100, status="SUCCESS" → rezultat 403d15c591f9b6db781936b003acb25e. Za statuse, ki niso SUCCESS, se za leanPayTransactionId pri izračunu uporabi vrednost null.

Postcheckout faza

Po zaključku transakcije sistem trgovca pozna njen status. Pred odpremo blaga je treba ugotoviti, ali je kupec že v celoti verificiran ali pa ga je treba preveriti šele ob dostavi.

Status verifikacije

GET/api/verification-document/get

Pred odpremo se pri Leanpayu preveri, ali je kupec verificiran. Od odgovora je odvisno, ali se blago pošlje takoj ali ga je treba preveriti ob dostavi. Klic poteka prek query parametrov vendorApiKey in vendorTransactionId.

Odgovor (200):

{
  "vendorTransactionId": "ORDER-2026-05-21-00813",
  "verificationStatus": "VERIFIED"
}

Status	Pomen
`VERIFIED`	Kupec je v celoti verificiran. Transakcija velja kot plačana — blago se lahko pošlje neposredno.
`CREATED`	Vloga je potrjena na podlagi podatkov, ki jih je kupec podal, a verifikacija še ni opravljena. Dokončno se potrdi ob dostavi (kurir ali osebje trgovine).

ℹSam SUCCESS callback še ne pomeni, da je plačano. SUCCESS skupaj z VERIFIED pomeni plačano in blago se lahko sprosti. SUCCESS skupaj s CREATED pomeni, da je vloga oddana in čaka na verifikacijo ob dostavi.

Ukrepanje glede na status

Pri statusu VERIFIED dodatno preverjanje ni potrebno — blago se pošlje in velja za plačano, dostavna služba pa izroči brez preverjanja dokumentov. Pri statusu CREATED je kupca treba preveriti ob prevzemu, kar se izvede po enem od dveh scenarijev.

Scenarij A — dostava s kurirjem

Kurir prinese paket skupaj s podatki kupca, ki jih posreduje Leanpay. Kupec pokaže osebni dokument, kurir preveri ujemanje. Ob ujemanju izroči blago in dostava je potrjena. Ob neujemanju gre primer v dodatno preverjanje — kupec se obrne na Leanpay podporo, ki ga bodisi odobri (izročitev) bodisi zavrne (dostava odpade, transakcija FAILED).

Scenarij B — prevzem v poslovalnici (Click & Collect)

Kupec pride po naročilo v trgovino. Zaposleni v Leanpay aplikaciji preveri njegov osebni dokument proti Leanpay podatkom. Ob ujemanju izroči blago, sicer je transakcija FAILED.

Potrditev dostave

POST/vendor/transaction/delivery

Ko kupec prestane preverjanje (ali je bil že VERIFIED), trgovec Leanpayu potrdi dostavo. S tem transakcija postane upravičena do izplačila in se uvrsti v naslednji tedenski cikel. Odgovor je HTTP 200 s praznim telesom; status ostane SUCCESS (ločenega statusa za dostavo ni).

Kaj pošljemo — request body:

POST /vendor/transaction/delivery HTTP/1.1
Host: app.leanpay.si
Content-Type: application/json

{
  "vendorApiKey": "wk_live_xyz789...",
  "vendorTransactionId": "ORDER-2026-05-21-00813"
}

Napake se vrnejo prek X-LeanPayCoreApp-Error headerja (na primer TRANSACTION_NOT_FOUND, TRANSACTION_DELIVERY_FORBIDDEN, VENDOR_API_VENDOR_TRANSACTION_ID_UNKNOWN).

Delna dostava

Kadar dela naročila ni mogoče poslati (artikel ni na zalogi, postavka preklicana pred odpremo), se dostava lahko potrdi za nižji znesek od prvotnega. Nova ponudba in ponovni podpis nista potrebna — Leanpay samodejno prilagodi znesek kredita na obstoječi pogodbi. Pošlje se isti endpoint z dodatnim poljem amount:

{
  "vendorApiKey": "wk_live_xyz789...",
  "vendorTransactionId": "ORDER-2026-05-21-00813",
  "amount": 189.00
}

Dostavljeni znesek mora biti strogo nižji od prvotnega. Za polno dostavo se klic pošlje brez polja amount.

Dodatni API

POSTRazdeljene cene (widget) — /vendor/installment-plans

Za dani znesek vrne možne obročne načrte (število mesecev in okvirni mesečni obrok). Uporablja se za prikaz “že od X €/mesec” na strani izdelka, v košarici ali na blagajni. Zneski so informativni. Obvezna sta vendorApiKey in amount v request bodyju.

Odgovor (200):

{
  "groups": [
    {
      "groupId": "7208f613-f346-42be-a334-cef66ff4e44b",
      "groupName": "SPLET - REDNA PONUDBA",
      "currencyCode": "EUR",
      "loanAmounts": [
        { "loanAmount": 50.00, "possibleInstallments": [ { "numberOfMonths": 3, "installmentAmout": 16.67 } ] }
      ]
    }
  ]
}

⚠Polje se v odgovoru imenuje installmentAmout (brez črke “n”) — ujemanje je treba uskladiti točno tako. Isti loanAmount z različnimi roki je razdeljen na ločene vnose.

POSTSpori — /vendor/transaction/dispute

Spor (dispute) se odpre, kadar je treba kredit preklicati po dostavi — najpogosteje ob vračilu izdelka ali napačnem naročilu. Endpointi za spore so vezani na transakcijo.

Akcija	Metoda	Endpoint
Odpri spor	POST	`/vendor/transaction/dispute`
Preveri status spora	POST	`/vendor/transaction/dispute/status`

Request body ob odprtju spora (vsa polja obvezna):

{
  "vendorApiKey": "wk_live_xyz789...",
  "vendorTransactionId": "ORDER-2026-05-21-00813",
  "message": "Kupec je vrnil izdelek"
}

Status	Pomen
`NEW`	Spor je odprt in čaka na pregled.
`IN_REVIEW`	Leanpay pregleduje spor.
`APPROVED`	Spor je potrjen, kredit preklican.
`REJECTED`	Spor je zavrnjen, kredit ostane aktiven.
`CLOSED`	Spor je rešen in zaprt.

ℹNasvet iz prakse: kadar dela naročila ni mogoče dostaviti, je namesto spora primernejša delna dostava (korak 8). Spor je namenjen preklicu kredita po dostavi, ne prilagajanju zneska pred njo.

Tehnične osnove

Predpogoji, okolja in avtentikacija

Predpogoji

✓
Aktiven Leanpay vendor račun
✓
API Key in Secret Word (Vendor aplikacija, razdelek Podjetje > Development)
✓
API URL za sprejemanje callbacka (HTTPS endpoint, dosegljiv z Leanpayevih IP-jev)

Okolja

Okolje	Host
Stage (testno)	`https://stage-app.leanpay.si`
Produkcija	`https://app.leanpay.si`

Avtentikacija

Web integracija ne uporablja avtentikacijskih headerjev. Vsak zahtevek nosi vendorApiKey v JSON bodyju. Statusni callbacki so podpisani s poljem md5Signature v telesu, ki ga je treba preveriti pred zaupanjem (glej “Kako preveriti md5Signature” v checkout fazi).

Odhodni IP-ji (callbacki)

Leanpay pošilja callbacke z naslovov 34.118.48.57 in 34.116.211.213. Če je sistem trgovca za požarnim zidom, je treba oba uvrstiti na beli seznam, sicer bodo callbacki zavrženi. Callbacki se ob ne-2xx odgovoru ponovijo do 10×; handler mora biti idempotenten.

Next to In-Store integracija

Boosting conversion

Integration

Domov

POSPEŠEVANJE PRODAJE

PLATFORMNA INTEGRACIJA

API INTEGRACIJA

TESTIRANJE INTEGRACIJE

NAVODILA

Integration with Leanpay

PLUGINS

Magento

Opencart

Prestashop

WooCommerce

API integration

TESTING INTEGRATION

BOOST YOUR SALES

INSTRUCTIONS

Integration with Leanpay

PLUGINS

API integration

TESTING INTEGRATION

Integration with Leanpay

PLUGINS

Magento

Opencart

Prestashop

WooCommerce

API integration

TESTING INTEGRATION

BOOST YOUR SALES

WEB integracija

Potek plačila

Checkout faza

Postcheckout faza

Dodatni API

Tehnične osnove

Predpogoji

Okolja

Avtentikacija

Odhodni IP-ji (callbacki)