Title: Mada BNPL Gateway for WooCommerce
Author: madabnpl
Published: October 20, 2026
Last modified: October 20, 2026
---
Search plugins
# Mada BNPL Gateway for WooCommerce
By [madabnpl](https://profiles.wordpress.org/madabnpl/)
[Download](https://downloads.wordpress.org/plugin/mada-bnpl.1.1.7.zip)
* [Details](https://wordpress.org/plugins/mada-bnpl/#description)
* [Reviews](https://wordpress.org/plugins/mada-bnpl/#reviews)
* [Installation](https://wordpress.org/plugins/mada-bnpl/#installation)
* [Development](https://wordpress.org/plugins/mada-bnpl/#developers)
[Support](https://wordpress.org/support/plugin/mada-bnpl/)
## 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: `).
* 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.
## Installation
1. Copy this folder to `wp-content/plugins/woocommerce-mada-bnpl-gateway` (or zip
it and upload via Plugins > Add New > Upload).
2. Activate **Mada BNPL Gateway for WooCommerce**.
3. Go to **WooCommerce > Settings > Payments > Mada BNPL** and configure:
4. * **Environment**: Development, Staging, Sandbox, or Production.
* **Merchant API Key**: Your `X-Merchant-Api-Key` from the Mada merchant portal.
* **Webhook signing secret**: The secret issued with your webhook key in the Mada
portal.
5. In the Mada merchant portal, create an **ORDER** webhook pointing at the endpoint
shown in gateway settings (`rest_url('mada-bnpl/v1/webhook')`).
## Reviews
There are no reviews for this plugin.
## Contributors & Developers
“Mada BNPL Gateway for WooCommerce” is open source software. The following people
have contributed to this plugin.
Contributors
* [ madabnpl ](https://profiles.wordpress.org/madabnpl/)
* [ mada ](https://profiles.wordpress.org/mada/)
[Translate “Mada BNPL Gateway for WooCommerce” into your language.](https://translate.wordpress.org/projects/wp-plugins/mada-bnpl)
### Interested in development?
[Browse the code](https://plugins.trac.wordpress.org/browser/mada-bnpl/), check
out the [SVN repository](https://plugins.svn.wordpress.org/mada-bnpl/), or subscribe
to the [development log](https://plugins.trac.wordpress.org/log/mada-bnpl/) by [RSS](https://plugins.trac.wordpress.org/log/mada-bnpl/?limit=100&mode=stop_on_copy&format=rss).
## Changelog
#### 1.1.7
* Show Arabic checkout copy and RTL punctuation when the store is Arabic.
#### 1.1.6
* Shrink and wrap the checkout payment badge on narrow screens so the logo and
copy stay inside the card.
* Sit the subtitle in the text column, flush with the start of the logo.
* Keep “Don’t have a Mada account?” under the payment card, not inside the badge
box.
#### 1.1.5
* Flip the checkout payment badge when the store is RTL.
* Keep “Pay in 4 simple, interest free” inside the payment method card and bold“
Don’t have a Mada account?”
#### 1.1.4
* Load the checkout and payment method badge from the environment CDN instead of
the local SVG.
* Match Figma checkout copy: “Pay in 4 simple, interest free”.
#### 1.1.3
* Fix cart widget reading JOD prices when the symbol د.ا sits before the amount(
د.ا690.00 no longer becomes 0.69).
#### 1.1.2
* Rebrand payment method: title “Pay with Mada”, description “Pay in 4 simple,
interest free payments”.
* Add “Don’t have a Mada account?” CTA below payment method on checkout.
* Update Ninja Quick Buy popup label to match new branding.
* Responsive checkout payment badge styling for mobile.
#### 1.1.0
* Auto-show Mada BNPL in the Ninja Quick Buy popup when both plugins are active—
no merchant setup required.
* Fix promotional widget amounts that could be divided as fils on JOD stores; PHP
amounts are treated as major units.
#### 1.0.9
* Hide footer payment badge on checkout page to prevent duplicate Mada logo below
payment options.
#### 1.0.8
* Fix cart promotional widget positioning to consistently appear directly above
the “Proceed to Checkout” button across classic themes, block carts, and custom
page builder layouts.
#### 1.0.6
* Declare “Tested up to” exclusively in readme.txt and remove from main plugin
file header per WordPress.org guidelines.
#### 1.0.5
* Fix promotional widget amounts that were 100x too large when WooCommerce stored
prices in cents.
* Keep the product-page widget behind the mini-cart sidebar instead of stacking
on top of it.
#### 1.0.4
* Move webhook signature verification into permission_callback per WordPress REST
API guidelines.
#### 1.0.3
* Send X-Cancel-Callback-Url (cart page) so checkout header X abandons without
running the fail handler.
#### 1.0.2
* Hide the promotional widget unless currency is JOD and country is Jordan.
* Fix incorrect widget amounts caused by mini-cart qty and line-item totals.
#### 1.0.1
* Hide the promotional widget when the storefront currency is not JOD.
* Quantity changes update the widget immediately without a page refresh.
#### 1.0.0
* First 1.x release. V2 initiate, webhook confirmation, and promotional widgets.
## Meta
* Version **1.1.7**
* Last updated **2 weeks ago**
* Active installations **10+**
* WordPress version ** 6.0 or higher **
* Tested up to **7.1.4**
* PHP version ** 7.4 or higher **
* Tags
* [bnpl](https://wordpress.org/plugins/tags/bnpl/)[installments](https://wordpress.org/plugins/tags/installments/)
[mada](https://wordpress.org/plugins/tags/mada/)[payment gateway](https://wordpress.org/plugins/tags/payment-gateway/)
[woocommerce](https://wordpress.org/plugins/tags/woocommerce/)
* [Advanced View](https://wordpress.org/plugins/mada-bnpl/advanced/)
## Ratings
No reviews have been submitted yet.
[Your review](https://wordpress.org/support/plugin/mada-bnpl/reviews/#new-post)
[See all reviews](https://wordpress.org/support/plugin/mada-bnpl/reviews/)
## Contributors
* [ madabnpl ](https://profiles.wordpress.org/madabnpl/)
* [ mada ](https://profiles.wordpress.org/mada/)
## Support
Got something to say? Need help?
[View support forum](https://wordpress.org/support/plugin/mada-bnpl/)