Mada BNPL Gateway for WooCommerce

Description

This gateway integrates WooCommerce with the Mada BNPL payment platform:

• On checkout it calls POST /engine/merchant/online/orders with your X-Merchant-Api-Key and redirects the shopper to Mada’s hosted checkout portal.
• The order is confirmed asynchronously by an HMAC-SHA256 signed ORDER webhook (X-Signature: <hex>).
• Supports both classic WooCommerce checkout and WooCommerce Checkout Blocks.
• Displays responsive promotional installment widgets on product and cart pages.

External Services

This plugin connects to external services operated by Mada BNPL to process Buy Now Pay Later payment sessions, render promotional installment breakdown widgets, and verify order statuses.

• Service Name: Mada BNPL Merchant API & CDN (https://api.mada-bnpl.com, https://api.sandbox.mada-bnpl.com, https://cdn.mada-bnpl.com)
• Purpose: Used during checkout to initiate BNPL payment sessions, render promotional installment widgets on product and cart pages, process order webhooks, and verify transaction completion.
• Data Transmitted: Order total amount, currency code, line item titles, quantities, unit prices, product URLs, image URLs, customer name, email address, phone number, and shipping address when an order is placed.
• Terms of Service: https://mada-bnpl.com/en/legal/terms
• Privacy Policy: https://mada-bnpl.com/en/legal/privacy-policy

Source Code & Build Tools

This plugin includes complete, unminified, human-readable source files for its WooCommerce integration code:

• The storefront promotional widget is loaded from https://cdn.mada-bnpl.com for the selected environment.
• The WooCommerce Checkout Blocks integration script source is located at assets/js/blocks.js.
• The Mada Payment Widget bundle is loaded from the Mada BNPL CDN for the environment selected in the gateway settings.
• Mada Payment Widget source code: https://github.com/ahbmer3i/mada-payment-widget
• Build instructions: Clone the source repository, run npm ci, then run npm run build:bundle. The generated CDN bundle is dist/bundle.js.

Webhook & Status Mapping

The webhook eventStatus maps to WooCommerce as:

Mada eventStatus
WooCommerce Result

SUCCESS
payment_complete (paid)

SETTLED
payment_complete (paid)

PENDING
on-hold

CANCELLED
cancelled

EXPIRED
failed

REJECTED
failed

Order Correlation

Each WooCommerce order is sent to Mada with reference_id = mg_{orderId}_{timestamp}, which Mada BNPL stores and echoes back in the ORDER webhook. The plugin resolves an incoming webhook to a WooCommerce order in this order:

1. reference_id (mg_{id}_{timestamp}) -> WC order.
2. Stored Mada orderId.
3. Stored Mada orderReference.
4. Stored checkoutId.

Reconciliation (Safety Net)

The webhook is the source of truth, but confirmation never depends on it alone:

• On the success return URL the plugin calls GET /engine/merchant/orders/{id} and confirms the order if payment status is completed.
• A 15-minute WP-Cron sweep (mada_bnpl_reconcile_cron) reconciles any pending Mada orders from the last 24h via their stored order IDs.

Branding / Appearance

The payment method renders as the Mada badge (logo + title + description) on both classic and Blocks checkout, matching the Mada design system. Styling lives in assets/css/checkout.css; the logo is loaded from the environment CDN.