=== Devdraft - Bila Payment Gateway for WooCommerce ===
Contributors: devdraft
Tags: woocommerce, payment gateway, mobile money, zambia, payments
Requires at least: 6.5
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv3 or later
License URI: http://www.gnu.org/licenses/gpl-3.0.html
WC requires at least: 8.0
WC tested up to: 10.8

Accept mobile money payments in Zambia via Bila — Airtel Money, MTN MoMo, and Zamtel Kwacha.

== Description ==

Devdraft - Bila Payment Gateway for WooCommerce lets your store accept mobile money payments through the [Bila](https://usebila.com) platform, a Devdraft product.

**Supported operators**

* Airtel Money
* MTN MoMo
* Zamtel Kwacha

**Features**

* Real-time mobile money collection (push payment prompt on the customer's phone)
* Sandbox and live API modes
* Webhook handling for `payment.completed` and `payment.failed` events
* Account name resolution at checkout
* Thank-you page status polling when webhooks are delayed
* Configurable fee bearer and enabled operators
* Compatible with WooCommerce High-Performance Order Storage (HPOS)

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/` or install the ZIP via **Plugins → Add New**.
2. Activate the plugin through the **Plugins** screen.
3. Ensure WooCommerce is installed and active.
4. Go to **WooCommerce → Settings → Payments** and enable **Bila – Mobile Money**.
5. Enter your Bila API key and wallet ID, then save changes.
6. **Webhook setup (required)** — In your [Bila merchant dashboard](https://usebila.com), create a webhook with the following settings:

* **Endpoint URL:** `https://yourstore.com/?wc-api=bila_webhook` (replace `yourstore.com` with your store domain)
* **Events:** `payment.completed`, `payment.failed`
* **Signing secret:** Copy the signing secret from Bila into **WooCommerce → Settings → Payments → Bila – Mobile Money → Webhook Signing Secret**, then save. The signing secret is required; incoming webhooks are rejected if it is not configured.

Without webhooks configured, orders may remain on hold until the thank-you page polling confirms payment.

== Frequently Asked Questions ==

= Do I need a Bila account? =

Yes. Sign up at [usebila.com](https://usebila.com) to obtain API credentials.

= Which currencies are supported? =

This gateway is intended for Zambian Kwacha (ZMW) mobile money collections via Bila.

= Does this work with HPOS? =

Yes. The plugin declares compatibility with WooCommerce custom order tables (HPOS).

== External services ==

This plugin requires an active [Bila](https://usebila.com) merchant account and connects to the Bila API to process mobile money payments (Airtel Money, MTN MoMo, Zamtel Kwacha) in Zambia. It is needed to initiate payment collections, resolve mobile money account names, check payment status, and receive payment confirmation webhooks. This plugin acts as the WooCommerce integration layer; all payment processing itself is handled by Bila.

The plugin sends the following data to Bila's servers (`api.usebila.com` for live mode, `sandbox.usebila.com` for test mode):

* Mobile phone number and network operator — sent when the customer enters payment details at checkout (for account name resolution) and when the order is placed (to initiate the payment).
* Order amount, reference, and country — sent when the order is placed, to initiate the payment collection.
* Customer name — sent when the order is placed, used for payment narration and account resolution.

This data is sent every time a customer pays with Bila Mobile Money, and again when the thank-you page polls Bila for payment status. Bila may also send webhooks (`payment.completed`, `payment.failed`) back to your store to update order status.

This service is provided by Bila, a Devdraft product: [Terms of Service](https://usebila.com/terms), [Privacy Policy](https://usebila.com/privacy).

== Changelog ==

= 1.0.0 =
* Added Bila mobile money payment gateway for WooCommerce (Airtel Money, MTN MoMo, Zamtel Kwacha)
* Added webhook handler for payment.completed and payment.failed events
* Added sandbox and live API modes with configurable API key and wallet ID
* Added account name resolution at checkout before order placement
* Added thank-you page status polling as a fallback when webhooks are delayed
* Added configurable fee bearer and enabled mobile money operators
