Leanpay

Kontekst

Leanpay omogućuje obročno plaćanje za online trgovce. Za WooCommerce i OpenCart trgovine integracija mora pratiti životni ciklus checkouta i narudžbe, jasno prikazivati cijene na rate u storefrontu i ostati operativno sigurna pri asinkronim ishodima (redirect tokovi + serverski callbackovi).

Problem

Obročno plaćanje donosi više izazova nego jednostavan redirect:

• Trgovac treba ažurne planove otplate (po tržištu i financijskom proizvodu/grupi).
• Checkout mora kupca preusmjeriti u Leanpay tok i sigurno ga vratiti natrag.
• Zaključivanje narudžbe mora se temeljiti na verificiranom serverskom callbacku (ne na parametrima return URL-a).
• Administracija treba operativnu preglednost (status, logovi/metapodatci) i akcije (npr. potvrda dostave).

Ciljevi projekta

• Leanpay kao prvoklasna metoda plaćanja u WooCommerceu i OpenCartu.
• Prikaz cijena na rate i UI kalkulator na stranicama kataloga/proizvoda/checkouta.
• Automatska i ručna sinkronizacija planova otplate.
• Zaključivanje narudžbi preko verificiranih status callbackova i pohrana Leanpay metapodataka.
• Podrška za više tržišta/okruženja i tipičan skup značajki platforme.

Ograničenja i izazovi

• Callback putanja mora biti autoritativna (bez “status by redirect URL”).
• Spriječiti neusklađenosti pri zaokruživanju/valutama i uvesti min/max limite specifične za tržište.
• Zadržati postavke preglednima (WooCommerce settings; OpenCart multi-store settings).
• Widgeti moraju ispravno reagirati na ukupnu vrijednost košarice i varijacije, bez utjecaja na stabilnost checkouta.

Pregled rješenja

Razvili smo Leanpay module za dvije platforme sa zajedničkim ciljem: sigurno obročno plaćanje i dosljedan UX prikaza cijena na rate.

• WooCommerce: gateway + widgeti + planirana sinkronizacija planova + admin meta box akcije.
• OpenCart: payment extension + widgeti bazirani na Events + lokalna pohrana transakcija/planova + admin konfiguracija + OCMOD stupac statusa u listi narudžbi.

Arhitektura i tehnički pristup

WooCommerce modul

Konfiguracija (wp-admin)

• API key + secret, environment (production/sandbox), market endpoint (`si`, `hr`, `ro`, `hu`).
• Callback URL je prikazan kao read-only “API Vendor URL” za kopiranje u Leanpay vendor postavke.
• Min/max order total + opcijski IP allowlist u sandbox načinu rada.
• Title/description + order statusi za success/failure i opcijske prilagođene redirect stranice.

Sinkronizacija planova otplate + pohrana

• Pri aktivaciji stvara WP DB tablicu (`wp_leanpay_cene_tmp_2022`).
• Dohvaća `vendor/installment-plans` po tržištu i lokalno pohranjuje grupe/planove za brzo renderiranje.
• Podržava dnevno planirano ažuriranje i ručni “Update product prices” u postavkama.

Storefront widgeti

• Katalog: oznaka “od X / mjesec” u product loopu.
• Proizvod: kalkulator tooltip s jQuery UI sliderom; varijacije se osvježavaju preko AJAX-a.
• Checkout: prikaz opcija na rate i opcijsko “dinamično” obogaćivanje naziva metode plaćanja.
• Shortcode: `[leanpay_catalog]`, `[leanpay_product_page]`.

Inicializacija plaćanja (token → checkout)

• `process_payment()` preusmjerava na internu confirmation skriptu.
• Token request na `https://{env}.leanpay.{market}/vendor/token` i submit na `https://{env}.leanpay.{market}/vendor/checkout`.
• Payload uključuje vendor transaction id, iznos, billing podatke, jezik i stavke košarice.

Verifikacija status callbacka

• Callback endpoint parsira JSON i pronalazi narudžbu iz `vendorTransactionId`.
• Validira `md5Signature` s `API_secret` i deterministički ažurira status narudžbe.
• U narudžbu sprema dijagnostičke metapodatke (npr. `leanpay_vendor_transaction_id`, `leanpay_order_status`).

Admin operacije

• Meta box (HPOS-safe screen id) prikazuje Leanpay status i omogućuje operativne akcije.
• AJAX akcija za potvrdu dostave (`/vendor/transaction/delivery`).
• AJAX akcija za status verifikacijskog dokumenta (`/api/verification-document/get`) i upis u order meta.

WooCommerce Blocks + HPOS kompatibilnost

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

OpenCart modul

Tok plaćanja

• Validira osnovnu valutu i min/max iznose (zadane vrijednosti specifične za tržište; RO se razlikuje).
• Generira UUID `vendorTransactionId` i sprema ga u `mojakoda_leanpay_transactions`.
• Dohvaća token preko Leanpaya i preusmjerava na `vendor/checkout?token=...`.

Verificiran callback + mapiranje statusov

• Status endpoint: `index.php?route=extension/payment/leanpay/status`.
• Validira JSON shemu i provjerava MD5 potpis s postavljenom “secret word”.
• `SUCCESS` mapira na konfiguriran “paid” status (s audit komentarom) i status upisuje u transakcijsku tablicu.

Sinkronizacija planova + lokalna pohrana

• Skupine i `loanAmounts` JSON sprema u `mojakoda_leanpay_installments` po državi.
• U adminu se odabire instalment group za prikaz u storefrontu.

Storefront widgeti (Events)

• Umeće instalment UI na product page (tooltip + slider), checkout i category listing.
• Učitava jQuery UI + `leanpay.css` za kalkulator UI.

Admin UX + operacije

• Multi-store postavke (opcijski “global settings”), ograničenje geo-zona, sort order i debug logging.
• OCMOD dodaje stupac “Leanpay Status” u admin order list (izvor: transakcijska tablica).

Tehnološki stack

• 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 API-ji (token, checkout, planovi otplate, status callbacki)

Proces implementacije

1. Definiranje modela statusa narudžbi i određivanje verificiranog callbacka kao izvora istine.
2. Implementacija konfiguracije gatewaya i environment/market logike po platformama.
3. Implementacija dohvaćanja planova + lokalna pohrana + odabir grupe u adminu.
4. Dodavanje storefront widgeta (catalog/product/checkout) i cart/variation-aware osvježavanja.
5. Implementacija verifikacije potpisa i determinističko zaključivanje narudžbi.
6. Admin alati (WooCommerce meta box akcije; OpenCart status u order listi preko OCMOD-a).

Rezultati i učinak

• Leanpay plaćanja na rate rade u WooCommerceu i OpenCartu s predvidljivim zaključivanjem narudžbi.
• Kupac vidi cijene na rate na vrijeme i ima dosljedan kalkulator UX kroz checkout.
• Operativa ima preglednost i akcije u adminu (status metapodatci, delivery/verification tokovi, logovi).
• Podaci o planovima otplate ostaju ažurni uz pozadinska ažuriranja i ručne override-e.

Refleksija

Kod plaćanja na rate stabilnost ovisi o tome da je potpisani serverski callback jedini izvor istine. Redirect/return tok je UX put, a ne signal za autorizaciju. To sprječava lažne “paid” statuse i smanjuje opterećenje podrške zbog dvosmislenih ishoda.

Sažetak

Leanpay smo integrirali u WooCommerce i OpenCart kao sigurno obročno plaćanje s lokalnom pohranom planova, widgetima za prikaz i verificiranim status callbackovima. OpenCart paket dodatno uključuje OCMOD poboljšanje koje u listi narudžbi u adminu prikazuje Leanpay status.