Leanpay

Kontekst

Leanpay omogoča obročno plačevanje za spletne trgovce. Za WooCommerce in OpenCart trgovine mora integracija slediti checkout/order lifecycleu, jasno komunicirati obročne cene skozi storefront in ostati operativno varna pri asinhronih izidih (redirect tokovi + server callbacki).

Problem

Obročna plačila prinesejo več izzivov kot preprost redirect:

• Trgovec potrebuje ažurne obročne plane (po trgu in finančnem produktu/skupini).
• Checkout mora kupca preusmeriti v Leanpay flow in ga varno vrniti nazaj.
• Zaključek naročila mora temeljiti na verificiranem server callbacku (ne na parametrih return URL).
• Administracija potrebuje operativno preglednost (status, logi/metapodatki) in akcije (npr. potrditev dostave).

Cilji projekta

• Leanpay kot prvovrstna plačilna metoda v WooCommerce in OpenCart.
• Prikaz obročnih cen in kalkulator UI na catalog/product/checkout straneh.
• Samodejna in ročna sinhronizacija obročnih planov.
• Zaključevanje naročil prek verificiranih status callbackov in shranjevanje Leanpay metapodatkov.
• Podpora več trgom/okoljem ter tipičnim platformnim feature setom.

Omejitve in izzivi

• Callback pot mora biti avtoritativna (brez “status by redirect URL”).
• Preprečiti neskladja pri zaokroževanju/valutah in uveljaviti market-specific min/max limite.
• Ohraniti nastavitve pregledne (WooCommerce settings; OpenCart multi-store settings).
• Widgeti morajo pravilno reagirati na cart total in variacije, brez vpliva na checkout stabilnost.

Pregled rešitve

Razvili smo Leanpay module za dve platformi s skupnim ciljem: varno obročno plačevanje + konsistenten UX prikaza obročnih cen.

• WooCommerce: gateway + widgeti + scheduled sync planov + admin meta box akcije.
• OpenCart: payment extension + events-based widgeti + lokalno shranjevanje transakcij/planov + admin konfiguracija + OCMOD stolpec statusa v order listu.

Arhitektura in tehnični pristop

WooCommerce modul

Konfiguracija (wp-admin)

• API key + secret, environment (production/sandbox), market endpoint (`si`, `hr`, `ro`, `hu`).
• Callback URL je prikazan kot read-only “API Vendor URL” za kopiranje v Leanpay vendor nastavitve.
• Min/max order total + opcijski IP allowlist v sandbox načinu.
• Title/description + order statusi za success/failure in opcijske custom redirect strani.

Sinhronizacija obročnih planov + shranjevanje

• Ob aktivaciji ustvari WP DB tabelo (`wp_leanpay_cene_tmp_2022`).
• Fetch `vendor/installment-plans` po trgu in lokalno hrani skupine/plane za hitro renderiranje.
• Podpira daily scheduled update in ročni “Update product prices” v nastavitvah.

Storefront widgeti

• Catalog: oznaka “od X / mesec” v product loopu.
• Product: kalkulator tooltip z jQuery UI sliderjem; variacije se osvežujejo prek AJAX.
• Checkout: prikaz obročnih opcij in opcijska “dinamična” obogatitev naslova plačilne metode.
• Shortcode: `[leanpay_catalog]`, `[leanpay_product_page]`.

Inicializacija plačila (token → checkout)

• `process_payment()` preusmeri na interno confirmation skripto.
• Token request na `https://{env}.leanpay.{market}/vendor/token` in submit na `https://{env}.leanpay.{market}/vendor/checkout`.
• Payload vključuje vendor transaction id, amount, billing podatke, jezik in cart items.

Verifikacija status callbacka

• Callback endpoint parsira JSON in poišče order iz `vendorTransactionId`.
• Validira `md5Signature` z `API_secret` in deterministično posodobi order status.
• Na order shrani diagnostične metapodatke (npr. `leanpay_vendor_transaction_id`, `leanpay_order_status`).

Admin operacije

• Meta box (HPOS-safe screen id) prikazuje Leanpay status in omogoča operativne akcije.
• AJAX akcija za potrditev dostave (`/vendor/transaction/delivery`).
• AJAX akcija za status verifikacijskega dokumenta (`/api/verification-document/get`) in zapis v order meta.

WooCommerce Blocks + HPOS kompatibilnost

• Deklarira kompatibilnost z `custom_order_tables` (HPOS) in `cart_checkout_blocks`.
• Registrira Blocks payment method integracijo (`assets/js/checkout.js`).

OpenCart modul

Plačilni tok

• Validira base currency in min/max totale (market-specific privzete vrednosti; RO se razlikuje).
• Generira UUID `vendorTransactionId` in ga shrani v `mojakoda_leanpay_transactions`.
• Pridobi token prek Leanpay in preusmeri na `vendor/checkout?token=...`.

Verificiran callback + mapiranje statusov

• Status endpoint: `index.php?route=extension/payment/leanpay/status`.
• Validira JSON shemo in preveri MD5 podpis z nastavljeno “secret word”.
• `SUCCESS` mapira na konfiguriran “paid” status (z audit komentarjem) in status zapiše v transakcijsko tabelo.

Sinhronizacija planov + lokalno shranjevanje

• Skupine in `loanAmounts` JSON shrani v `mojakoda_leanpay_installments` po državi.
• V adminu se izbere instalment group za prikaz v storefrontu.

Storefront widgeti (Events)

• Vstavi instalment UI na product page (tooltip + slider), checkout in category listing.
• Naloži jQuery UI + `leanpay.css` za kalkulator UI.

Admin UX + operacije

• Multi-store nastavitve (opcijski “global settings”), geo-zone omejitev, sort order in debug logging.
• OCMOD doda stolpec “Leanpay Status” v admin order list (vir: transakcijska tabela).

Tehnološki sklad

• WordPress + WooCommerce (gateway + Blocks integracija)
• OpenCart (payment extension + Events + OCMOD)
• PHP (moduli, callback verifikacija, lokalna persistenca)
• JavaScript/CSS (widgeti, jQuery UI slider, admin settings UI)
• Leanpay vendor APIji (token, checkout, obročni plani, status callbacki)

Proces implementacije

1. Definiranje modela statusov naročil in določitev verificiranega callbacka kot vira resnice.
2. Implementacija konfiguracije gatewaya in environment/market logike po platformah.
3. Implementacija pridobivanja planov + lokalno shranjevanje + izbira skupine v adminu.
4. Dodajanje storefront widgetov (catalog/product/checkout) in cart/variation-aware osveževanja.
5. Implementacija verifikacije podpisov in determinističen zaključek naročil.
6. Admin tooling (WooCommerce meta box akcije; OpenCart status v order listu prek OCMOD).

Rezultati in učinek

• Leanpay obročna plačila delujejo v WooCommerce in OpenCart z predvidljivim zaključevanjem naročil.
• Kupec vidi obročne cene pravočasno in ima konsistenten kalkulator UX skozi checkout.
• Operativa ima preglednost in akcije v adminu (status metapodatki, delivery/verification tokovi, logi).
• Podatki o obročnih planih ostajajo ažurni z background updateom in ročnimi overridei.

Refleksija

Pri obročnih plačilih je stabilnost odvisna od tega, da je podpisan server callback edini vir resnice. Redirect/return tok je UX pot, ne signal za avtorizacijo. To prepreči lažne “paid” statuse in zmanjša support breme zaradi dvoumnih izidov.

Povzetek

Leanpay smo integrirali v WooCommerce in OpenCart kot varno obročno plačilo z lokalnim shranjevanjem planov, prikaznimi widgeti in verificiranimi status callbacki. OpenCart paket dodatno vključuje OCMOD izboljšavo, ki v admin order listu prikaže Leanpay status.