Leanpay

Context

Leanpay maakt “betalen in termijnen” mogelijk voor e-commerceverkopers. Voor WooCommerce- en OpenCart-shops moet de integratie passen in de checkout-/orderlifecycle van elk platform, termijnprijzen duidelijk communiceren op de storefront en operationeel veilig blijven bij asynchrone uitkomsten (redirect flows + server callbacks).

Probleem

Termijnbetalingen voegen complexiteit toe bovenop een simpele redirect:

• Verkopers hebben actuele termijnplannen nodig (per markt en financieel product/groep).
• Checkout moet naar Leanpay’s flow redirecten en de klant veilig terugbrengen.
• Ordercompletion moet worden aangestuurd door een geverifieerde servercallback om gespoofte “success”-states te voorkomen.
• Admins hebben operationeel inzicht nodig (status, logs/metadata) en acties (bijv. leveringsbevestiging).

Projectdoelen

• Leanpay aanbieden als volwaardige betaalmethode in zowel WooCommerce als OpenCart.
• Termijnprijzen en een calculator-UI tonen op catalogus-/product-/checkoutpagina’s.
• Termijnplannen automatisch en on-demand gesynchroniseerd houden.
• Orders finaliseren via geverifieerde statuscallbacks en Leanpay-metadata opslaan op orders/transacties.
• Meerdere Leanpay-markten/omgevingen en gangbare platformfeatures ondersteunen.

Beperkingen & Uitdagingen

• Callback-pad autoritatief houden (nooit “status via redirect-URL”).
• Afrondings-/valutamismatches voorkomen en markt-specifieke min/max-limieten afdwingen.
• Adminconfiguratie verkoper-vriendelijk houden (WooCommerce settings; OpenCart multi-store settings).
• Zorgen dat storefront-widgets reageren op cart totals en productvariaties zonder checkout-UX te breken.

Oplossingsoverzicht

We hebben Leanpay-modules gebouwd voor twee platformen met één doel: veilige termijncheckout + consistente termijnprijs-UX.

• WooCommerce: gateway + termijnwidgets + geplande plansync + admin order metabox-acties.
• OpenCart: payment extension + events-based termijnwidgets + lokale transactie-/planopslag + adminconfiguratie + OCMOD-verbetering voor orderlijststatus.

Architectuur & Technische aanpak

WooCommerce module

Gatewayconfiguratie (wp-admin)

• API key + secret, environment (productie/sandbox), market endpoint (`si`, `hr`, `ro`, `hu`).
• Callback-URL getoond als read-only “API Vendor URL” om te kopiëren naar de Leanpay vendor-configuratie.
• Min/max ordertotalen voor beschikbaarheid en optionele IP allowlist in sandbox.
• Betalingstitel/omschrijving + orderstatussen voor success/failure en optionele custom redirect pages.

Synchronisatie en opslag van termijnplannen

• Maakt bij activatie een custom WP DB-tabel (`wp_leanpay_cene_tmp_2022`) aan.
• Haalt `vendor/installment-plans` per markt op en slaat plangroepen en prijzen lokaal op.
• Ondersteunt dagelijkse geplande updates en een handmatige actie “Productprijzen bijwerken” in de instellingen.

Storefront-widgets

• Catalogus: label “vanaf X / maand” geïnjecteerd in productlijsten.
• Product: calculator-tooltip met jQuery UI-slider; variatieprijzen worden via AJAX bijgewerkt.
• Checkout: termijnweergave en optionele dynamische verrijking van de gatewaytitel.
• Shortcodes: `[leanpay_catalog]`, `[leanpay_product_page]`.

Start van betaling (token → checkout)

• `process_payment()` redirect naar een intern bevestigingsscript.
• Token-aanvraag naar `https://{env}.leanpay.{market}/vendor/token` en formulier-submit naar `https://{env}.leanpay.{market}/vendor/checkout`.
• Payload bevat `vendorTransactionId`, bedrag, factuurgegevens, taal en winkelwagen-items.

Verificatie van statuscallback

• Callback-endpoint parseert JSON en bepaalt de order op basis van `vendorTransactionId`.
• Valideert `md5Signature` met `API_secret` en werkt orderstatus deterministisch bij.
• Slaat diagnostische ordermetadata op (bijv. `leanpay_vendor_transaction_id`, `leanpay_order_status`).

Admin-orderoperaties

• Order metabox (HPOS-safe screen ids) toont Leanpay-status en biedt operationele acties.
• AJAX-actie voor leveringsbevestiging (`/vendor/transaction/delivery`).
• AJAX-actie voor status van verificatiedocument (`/api/verification-document/get`), opgeslagen in order meta.

Compatibiliteit met WooCommerce Blocks + HPOS

• Declareert compatibiliteit met `custom_order_tables` (HPOS) en `cart_checkout_blocks`.
• Registreert een Blocks payment method integration script (`assets/js/checkout.js`).

OpenCart module

Gateway-flow

• Valideert base currency en min/max totalen (markt-specifieke defaults; bijv. RO wijkt af).
• Maakt een UUID `vendorTransactionId` aan en slaat het op in `mojakoda_leanpay_transactions`.
• Vraagt een token op via Leanpay en redirect naar `vendor/checkout?token=...`.

Geverifieerde callback + mapping van orderstatus

• Status endpoint: `index.php?route=extension/payment/leanpay/status`.
• Valideert JSON-schema en verifieert de MD5-signature met de geconfigureerde “secret word”.
• Mapt `SUCCESS` naar de geconfigureerde “paid”-status (met audit note) en slaat de status op in de transactietabel.

Synchronisatie van termijnplannen + lokale opslag

• Slaat groepen en `loanAmounts` JSON op in `mojakoda_leanpay_installments` per land.
• Admin kiest welke termijngroep voor storefront rendering wordt gebruikt.

Storefront-termijnwidgets (Events)

• Injecteert termijn-UI op productpagina’s (tooltip + slider), checkout en categorieoverzichten.
• Laadt jQuery UI + `leanpay.css` voor de calculator-UI.

Admin UX + operations

• Multi-store aware instellingen (optioneel “global settings”), geo-zone-restrictie, sort order en debug logging.
• OCMOD voegt een kolom “Leanpay Status” toe aan de admin orderlijst, gevoed vanuit de transactietabel.

Technologiestack

• WordPress + WooCommerce (gateway + Blocks integration)
• OpenCart (payment extension + Events + OCMOD)
• PHP (platform modules, callback verification, local persistence)
• JavaScript/CSS (widgets, jQuery UI slider, admin settings UI)
• Leanpay vendor APIs (token, checkout, instalment plans, status callbacks)

Implementatieproces

1. Het order statemodel definiëren en de geverifieerde callback autoritatief maken.
2. Gateway-instellingen UX en omgeving/markt-afhandeling per platform implementeren.
3. Ophalen van termijnplannen + lokale opslag + adminselectie implementeren.
4. Storefront-widgets (catalogus/product/checkout) toevoegen en variation/cart-aware updates.
5. Callback signature-validatie implementeren en orders deterministisch finaliseren.
6. Admin operations tooling toevoegen (WooCommerce metabox-acties; OpenCart orderlijststatus via OCMOD).

Resultaten en impact

• Verkopers kunnen Leanpay-termijnbetalingen aanbieden op WooCommerce en OpenCart met voorspelbare orderfinalisatie.
• Klanten zien termijnprijzen vroeg en krijgen een consistente calculator-UX doorheen checkout.
• Operations krijgt inzicht en acties in admin (orderstatusmetadata, delivery/verification flows, logs).
• Termijnplandata blijft actueel via background updates met handmatige overrides.

Reflectie

Bij termijnbetalingen komt stabiliteit voort uit het behandelen van de gesigneerde servercallback als enige bron van waarheid. De redirect/return flow is een UX-pad, geen autorisatiesignaal. Dat voorkomt gespoofte “paid”-states en vermindert de support load door dubbelzinnige uitkomsten.

Samenvatting

Leanpay is geïntegreerd in WooCommerce en OpenCart als een veilige termijnbetaaloplossing met lokale planopslag, storefront prijswidgets en geverifieerde statuscallbacks. Het OpenCart-package bevat daarnaast een OCMOD-verbetering die Leanpay-status zichtbaar maakt in de admin orderlijst.