Leanpay

Context

Leanpay enables “pay by instalments” purchases for e-commerce merchants. For WooCommerce and OpenCart shops, the integration must fit each platform’s checkout/order lifecycle, communicate instalment pricing clearly across the storefront, and remain operationally safe through asynchronous outcomes (redirect flows + server callbacks).

Problem

Instalment payments add complexity beyond a simple redirect:

• Merchants need up-to-date instalment plans (per market and financial product/group).
• Checkout must redirect into Leanpay’s flow and safely return the customer.
• Order completion must be driven by a verified server callback to prevent spoofed “success” states.
• Admins need operational visibility (status, logs/metadata) and actions (e.g. delivery confirmation).

Project Goals

• Provide Leanpay as a first-class payment method in both WooCommerce and OpenCart.
• Display instalment pricing and a calculator UI on catalog/product/checkout pages.
• Keep instalment plans synchronized automatically and on-demand.
• Finalize orders via verified status callbacks and store Leanpay metadata on orders/transactions.
• Support multiple Leanpay markets/environments and common platform feature sets.

Constraints & Challenges

• Keep the callback path authoritative (never “status by redirect URL”).
• Prevent rounding/currency mismatches and enforce market-specific min/max limits.
• Keep admin configuration merchant-friendly (WooCommerce settings; OpenCart multi-store settings).
• Ensure storefront widgets react to cart totals and product variations without breaking checkout UX.

Solution Overview

We built Leanpay modules for two platforms with a shared goal: secure instalment checkout + consistent instalment pricing UX.

• WooCommerce: gateway + instalment widgets + scheduled plan sync + admin order meta box actions.
• OpenCart: payment extension + events-based instalment widgets + local transaction/plan storage + admin configuration + OCMOD enhancement for order list status.

Architecture & Technical Approach

WooCommerce module

Gateway configuration (wp-admin)

• API key + secret, environment (production/sandbox), market endpoint (`si`, `hr`, `ro`, `hu`).
• Callback URL surfaced as a read-only “API Vendor URL” to copy into Leanpay vendor configuration.
• Min/max order totals for availability and optional IP allowlist in sandbox.
• Payment title/description + order statuses for success/failure and optional custom redirect pages.

Instalment plans sync and storage

• Creates a custom WP DB table (`wp_leanpay_cene_tmp_2022`) on activation.
• Fetches `vendor/installment-plans` per market and stores plan groups and prices locally.
• Supports daily scheduled updates and a manual “Update product prices” action in settings.

Storefront display widgets

• Catalog: “from X / month” label injected in product loops.
• Product: calculator tooltip with jQuery UI slider; variation prices updated via AJAX.
• Checkout: instalment display and optional dynamic gateway title enrichment.
• Shortcodes: `[leanpay_catalog]`, `[leanpay_product_page]`.

Payment initiation (token → checkout)

• `process_payment()` redirects into an internal confirmation script.
• Token request to `https://{env}.leanpay.{market}/vendor/token` and form submit to `https://{env}.leanpay.{market}/vendor/checkout`.
• Payload includes vendor transaction id, amount, billing data, language, and cart items.

Status callback verification

• Callback endpoint parses JSON and resolves order from `vendorTransactionId`.
• Validates `md5Signature` using `API_secret` and updates order status deterministically.
• Stores diagnostic order metadata (e.g. `leanpay_vendor_transaction_id`, `leanpay_order_status`).

Admin order operations

• Order meta box (HPOS-safe screen ids) shows Leanpay status and enables operational actions.
• AJAX action for delivery confirmation (`/vendor/transaction/delivery`).
• AJAX action for verification-document status (`/api/verification-document/get`) stored in order meta.

WooCommerce Blocks + HPOS compatibility

• Declares compatibility with `custom_order_tables` (HPOS) and `cart_checkout_blocks`.
• Registers a Blocks payment method integration script (`assets/js/checkout.js`).

OpenCart module

Payment gateway flow

• Validates base currency and min/max totals (market-specific defaults; e.g. RO differs).
• Creates a UUID `vendorTransactionId` and stores it in `mojakoda_leanpay_transactions`.
• Requests a token via Leanpay and redirects to `vendor/checkout?token=...`.

Verified callback + order state mapping

• Status endpoint: `index.php?route=extension/payment/leanpay/status`.
• Validates JSON schema and verifies MD5 signature using the configured “secret word”.
• Maps `SUCCESS` to the configured “paid” status (with audit note) and stores the status in the transaction table.

Instalment plans sync + local storage

• Stores groups and `loanAmounts` JSON in `mojakoda_leanpay_installments` per country.
• Admin selects which instalment group to use for storefront rendering.

Storefront instalment widgets (Events)

• Injects instalment UI on product pages (tooltip + slider), checkout, and category listings.
• Loads jQuery UI + `leanpay.css` for the calculator UI.

Admin UX + operations

• Multi-store aware settings (optional “global settings”), geo-zone restriction, sort order, and debug logging.
• OCMOD adds a “Leanpay Status” column to the admin order list, sourced from the transaction table.

Technology Stack

• 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)

Implementation Process

1. Define the order state model and make the verified callback authoritative.
2. Implement gateway settings UX and environment/market handling per platform.
3. Implement instalment plan retrieval + local storage + admin selection.
4. Add storefront widgets (catalog/product/checkout) and variation/cart-aware updates.
5. Implement callback signature validation and deterministic order finalization.
6. Add admin operations tooling (WooCommerce meta box actions; OpenCart order list status via OCMOD).

Results & Impact

• Merchants can offer Leanpay instalment payments on WooCommerce and OpenCart with predictable order finalization.
• Customers see instalment pricing early and get a consistent calculator UX through checkout.
• Operations get visibility and actions in admin (order status metadata, delivery/verification flows, logs).
• Instalment plan data stays current via background updates with manual overrides.

Reflection

For instalment payments, stability comes from treating the signed server callback as the only source of truth. The redirect/return flow is a UX path, not an authorization signal. This prevents spoofed “paid” states and reduces support load caused by ambiguous outcomes.

Summary

Leanpay was integrated into WooCommerce and OpenCart as a secure instalment payment solution with local plan storage, storefront pricing widgets, and verified status callbacks. The OpenCart package additionally includes an OCMOD enhancement that surfaces Leanpay status in the admin order list.