> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usebila.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# WooCommerce - Bila Payment Gateway

> Accept mobile money payments on your WooCommerce store via Bila from Airtel Money, MTN MoMo, and Zamtel Kwacha.

## Overview

The Bila Payment Gateway plugin connects your WooCommerce store to Bila, letting you accept real-time mobile money payments from customers in Zambia. When a customer checks out, a push payment prompt is sent directly to their phone.

<Info>
  The plugin is free and open source. Download it from the official WordPress plugin directory: [wordpress.org/plugins/devdraft-bila-payment-gateway](https://wordpress.org/plugins/devdraft-bila-payment-gateway)
</Info>

***

## Watch: How to Accept Mobile Money on WooCommerce | Bila Plugin Setup

<iframe src="https://www.youtube.com/embed/iTVBFYg6qqM" title="YouTube video player" frameborder="0" className="w-full aspect-video rounded-xl" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

***

## Supported Operators

| Operator      | Network       |
| ------------- | ------------- |
| Airtel Money  | Airtel Zambia |
| MTN MoMo      | MTN Zambia    |
| Zamtel Kwacha | Zamtel        |

***

## Features

| Feature                 | Description                                                                                         |
| ----------------------- | --------------------------------------------------------------------------------------------------- |
| Push-to-pay             | Customer receives a payment prompt directly on their phone at checkout                              |
| Account name resolution | The customer's mobile money name is verified before the order is placed                             |
| Sandbox and live modes  | Test your integration in sandbox before going live                                                  |
| Webhook handling        | Automatically updates order status when `payment.completed` or `payment.failed` events are received |
| Thank-you page polling  | Falls back to polling if webhooks are delayed, so customers always see their payment status         |
| Configurable fees       | Choose who bears the transaction fee (merchant or customer) and which operators to enable           |
| HPOS compatible         | Works with WooCommerce High-Performance Order Storage                                               |

***

## Requirements

| Requirement           | Minimum                                       |
| --------------------- | --------------------------------------------- |
| WordPress             | 6.5 or higher                                 |
| PHP                   | 7.4 or higher                                 |
| WooCommerce           | Installed and active                          |
| Bila merchant account | [Sign up at usebila.com](https://usebila.com) |

***

## Installation & Setup

<Steps>
  <Step title="Download the plugin">
    Visit the [Bila plugin page on WordPress.org](https://wordpress.org/plugins/devdraft-bila-payment-gateway) and download the plugin ZIP file.
  </Step>

  <Step title="Install the plugin">
    Upload the plugin folder to `/wp-content/plugins/` on your server, **or** install the ZIP directly from your WordPress dashboard via **Plugins > Add New**.
  </Step>

  <Step title="Activate the plugin">
    Go to the **Plugins** screen on your WordPress dashboard and activate the plugin.
  </Step>

  <Step title="Confirm WooCommerce is active">
    Ensure WooCommerce is installed and active. The plugin will display a notice if WooCommerce is not detected.
  </Step>

  <Step title="Enable Bila in WooCommerce">
    Go to **WooCommerce > Settings > Payments** and enable **Bila - Mobile Money**.
  </Step>

  <Step title="Enter your API credentials">
    Enter your **Bila API key** and **Wallet ID**, then click **Save changes**.

    You can find both in your [Bila merchant dashboard](https://app.usebila.com).
  </Step>

  <Step title="Configure your webhook">
    In your [Bila merchant dashboard](https://app.usebila.com), create a new webhook with the following settings:

    | Field          | Value                                                                              |
    | -------------- | ---------------------------------------------------------------------------------- |
    | Endpoint URL   | `https://yourstore.com/?wc-api=bila_webhook` (replace with your store domain)      |
    | Events         | `payment.completed`, `payment.failed`                                              |
    | Signing secret | Copy from Bila and paste into the plugin settings under **Webhook Signing Secret** |

    <Warning>
      The signing secret is required. Incoming webhooks are rejected if it is not configured. Without webhooks, orders may remain on hold until the thank-you page polling confirms payment.
    </Warning>
  </Step>
</Steps>

<Tip>
  Start with **Sandbox mode** to test the full payment flow before switching to live. Toggle the mode in the plugin settings under **WooCommerce > Settings > Payments > Bila - Mobile Money**.
</Tip>

***

## How It Works

When a customer checks out and selects Bila Mobile Money as their payment method:

1. The customer enters their **mobile phone number** and selects their **network operator**.
2. Their account name is **resolved in real time** before the order is placed.
3. A **push payment prompt** is sent to their phone.
4. The customer approves the payment on their phone.
5. Bila sends a **webhook** to your store to update the order status automatically.
6. If the webhook is delayed, the **thank-you page polls** Bila as a fallback.

***

## Data Sent to Bila

The plugin sends the following data to Bila's servers during checkout:

| Data                                     | Purpose                                        |
| ---------------------------------------- | ---------------------------------------------- |
| Mobile phone number and network operator | Account name resolution and payment initiation |
| Order amount, reference, and country     | Payment collection                             |
| Customer name                            | Payment narration                              |

| Environment | API Endpoint          |
| ----------- | --------------------- |
| Live        | `api.usebila.com`     |
| Sandbox     | `sandbox.usebila.com` |

<Info>
  Your data is governed by our [Terms of Service](https://usebila.com/terms) and [Privacy Policy](https://usebila.com/privacy).
</Info>

***

## FAQ

<AccordionGroup>
  <Accordion title="Do I need a Bila account?">
    Yes. Sign up at [usebila.com](https://usebila.com) to obtain your API key and Wallet ID.
  </Accordion>

  <Accordion title="Which currencies are supported?">
    This gateway supports Zambian Kwacha (ZMW) mobile money collections only.
  </Accordion>

  <Accordion title="Does this work with HPOS?">
    Yes. The plugin is fully compatible with WooCommerce High-Performance Order Storage (HPOS).
  </Accordion>

  <Accordion title="What happens if the webhook fails?">
    The thank-you page automatically polls Bila for the payment status as a fallback. The order will be updated once the payment is confirmed.
  </Accordion>
</AccordionGroup>