=== Mada BNPL Gateway for WooCommerce ===
Contributors: madabnpl, mada
Tags: woocommerce, payment gateway, bnpl, installments, mada
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
WC requires at least: 7.0
WC tested up to: 9.0
Stable tag: 1.1.7
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Accept Buy Now, Pay Later payments through the Mada BNPL platform. Redirect-based checkout confirmed by signed order webhooks.

== 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`.

== 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:
   * **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.
4. In the Mada merchant portal, create an **ORDER** webhook pointing at the endpoint shown in gateway settings (`rest_url('mada-bnpl/v1/webhook')`).

== 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.

== 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.
