Checkout controls for Sri Lankan BNPL gateways (Koko, Mintpay) on WooCommerce

By /

Abstract

Buy-Now-Pay-Later (BNPL) adoption in Sri Lanka has grown quickly, with Koko and Mintpay leading usage among fashion, lifestyle, and DTC brands. Merchants report two persistent checkout issues in WooCommerce: (1) limited ability to apply BNPL-specific pricing controls (e.g., surcharge or shipping uplift) in a transparent way, and (2) UI/fragment refresh inconsistencies that cause shipping totals and installment messages to be out of sync when the customer switches payment methods.
This paper documents the problem, outlines experimental findings across common WooCommerce setups, and describes Vector Arts Labs’ checkout control approach that adds policy-transparent pricing, installment clarity, and reliable totals for BNPL—without handling card data or bypassing gateway security.

1) Problem statement

  1. Pricing asymmetry. BNPL introduces costs (processing, settlement time) that aren’t easily contained to a specific method in stock WooCommerce.
  2. Fragment desynchronization. In several themes, selecting BNPL does not immediately refresh shipping HTML; totals update server-side but UI shows stale numbers until the shopper changes country/zone or shipping method.
  3. Installment ambiguity. “Pay in 3” amounts often reflect product subtotal only, not subtotal + freight + taxes/discounts, creating confusion.
  4. Disclosure & compliance. Adjustments must be clearly labeled, tax-aware, and consistent with gateway merchant terms and Sri Lankan consumer-transparency expectations.

2) Research questions

  • RQ1. Can we present accurate BNPL totals (including shipping) at the moment the customer toggles to Koko/Mintpay, across popular WooCommerce themes?
  • RQ2. Which merchant-side control (surcharge vs. shipping uplift vs. flat shipping) yields the most predictable customer understanding and lowest checkout friction?
  • RQ3. How do we achieve the above without touching payment credentials or revealing gateway internals, and while retaining clear disclosure?

3) Experimental setup

Platforms. WooCommerce (current LTS), PHP 7.4–8.2, a sample of common Sri Lankan themes and checkout page builders.
Gateways. Koko, Mintpay (merchant test accounts where available), plus COD and direct bank transfer as baselines.
Data. We instrumented checkout events—woocommerce_update_order_review, updated_checkout, package rate computations, and gateway description rendering—measuring time to accurate total, fragment stability, and customer-visible rows.
Scenarios.

  • S1: Toggle payment → BNPL (no country change)
  • S2: Toggle payment → BNPL with coupon added/removed
  • S3: Toggle payment → BNPL with shipping method change
  • S4: Return from gateway decline → re-quote

4) Key findings

  1. Woo fragment caching explains most stale-UI cases. Server totals update correctly, but shipping HTML isn’t replaced unless another trigger fires (country/postcode change).
  2. BNPL surcharge is simplest to reason about, but some merchants prefer moving the cost into shipping (seen as fairer for high-weight orders).
  3. Flat shipping (BNPL mode) delivers the clearest UI in stores with complex zone matrices: show a single “Shipping (BNPL)” line and hide the native row while BNPL is active.
  4. Installment accuracy materially improves trust when it is derived from the final payable total (subtotal + shipping – discounts + tax).

5) Approach (high-level design)

We do not alter gateway logic or handle card data. We operate entirely inside WooCommerce hooks and fragments.

5.1 Detection layer

  • Read the current payment method from the live checkout request (not only session) to avoid stale state during AJAX refresh.

5.2 Pricing layer (merchant controls)

  • Method A – Surcharge (percent/fixed): Add a labeled fee only when BNPL is selected.
  • Method B – Shipping uplift (percent/fixed): Increase the shipping component only; supports targeting by method_id or exact rate_key.
  • Method C – Flat (BNPL) shipping: Override the chosen rate with a clear flat value while BNPL is selected (country-agnostic presentation).
  • All methods are tax-aware and idempotent; they include a fallback fee if a theme blocks rate modification so totals still change when BNPL is chosen.

5.3 Presentation layer

  • When BNPL is active, hide the native shipping row and render a single “Shipping (Koko/Mintpay)” row with the combined amount (base shipping + uplift, or flat).
  • Render one installment widget (no duplicates), computed from the final total.
  • Debounce fragment updates to prevent update loops.

5.4 Reliability layer

  • Clear Woo shipping_for_package_ caches* upon payment change.
  • Use namespaced, one-shot listeners for updated_checkout to avoid re-entrancy.
  • Provide a fallback fee path so UI and totals remain correct even under non-standard themes.

6) Results (summarized)

  • Time to accurate total (median): < 400 ms after BNPL selection across tested themes.
  • UI correctness: 100% of scenarios displayed a single shipping row with the correct combined value when BNPL was active.
  • Installment accuracy: Always matched final payable amounts (3 × amount rounded to store currency precision).
  • No card data handled: All operations constrained to WooCommerce session and cart math.

(Exact timings vary by theme and hosting; figures based on controlled staging.)

7) Merchant impact & recommendations

  • Transparency drives conversion. Clear labeling—“Shipping (Koko)” or “BNPL surcharge (X%)”—reduced support queries in pilots.
  • Choose the control that matches your unit economics:
    • Low, stable logistics cost → Surcharge is simplest.
    • Weight/zone-sensitive freight → Shipping uplift scales better.
    • Highly variable/multi-zone setups → Flat BNPL shipping keeps UI predictable.
  • Accounting & tax: Confirm with your accountant whether the adjustment should be taxable. Our implementation supports both.

8) Compliance & ethics (Sri Lanka context)

  • Disclosure: Any BNPL-specific adjustment is explicitly labeled in the order summary and payment method description.
  • Gateway terms: Merchants should verify the latest Koko/Mintpay policies regarding surcharges and presentment.
  • Consumer protection: Practices are designed for price transparency; confirm alignment with local guidance and your legal counsel.
  • Security: We never access card data; we do not circumvent gateway authentication or risk controls.

9) Limitations & future work

  • Theme variance: Some builders replace Woo templates aggressively; we include fallbacks, but bespoke themes may require minor CSS/JS hooks.
  • Multi-package carts: We support multi-package quoting, but custom courier plugins can require targeted mapping.
  • Analytics: Adding optional event telemetry (gateway toggles, time-to-accurate-total) will help correlate UX changes → conversion.
  • Gateway coverage: Extend presets beyond Koko/Mintpay on request.

10) Implementation checklist (practical)

  • Enable Method A/B/C in admin; set Live/Test.
  • Decide taxable vs non-taxable adjustment with finance.
  • Write a short payment-method note (“When paying with Koko/Mintpay, shipping is quoted as… / a X% fee applies”).
  • QA: toggle gateway, apply coupons, change country and shipping method; verify single shipping row + correct installments.
  • Monitor abandonment for two weeks; adjust labels/values if needed.

Frequently asked questions

Does this bypass gateway security?
No. “Bypass” refers to WooCommerce presentation limits—we don’t touch card data or gateway auth.

Can I charge a BNPL fee legally?
Policies evolve. We provide the tooling and transparent labels; confirm with gateway terms and your legal/tax advisors.

Will this slow the checkout?
No heavy assets—only Woo hooks and lightweight fragments with debouncing.

Can I target only certain shipping methods?
Yes—by method_id (e.g., flat_rate) or exact rate keys (e.g., flat_rate:3).

Meet Our Experts

Learn from the minds behind Vector Arts Labs.

Explore Experts
Scroll to Top