=== Fosia Pay Lite – PawaPay Mobile Money for WooCommerce ===
Contributors: fosialtd
Tags: mobile money, pawapay, mtn momo, mpesa, orange money
Requires at least: 5.8
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Free Mobile Money gateway for WooCommerce with PawaPay: MTN MoMo, Airtel Money, Orange Money, M-Pesa and more. No commission, unlimited payments.

== Description ==

Fosia Pay Lite is a free WooCommerce payment gateway for Mobile Money in Africa, powered by the [PawaPay](https://www.pawapay.io) API. Accept **MTN MoMo** (MTN Mobile Money), **Airtel Money**, **Orange Money**, **M-Pesa**, Moov Money, Wave and more than 40 other mobile wallets in 21 African countries, from Rwanda, Uganda, Kenya and Ghana to Cameroon, Côte d'Ivoire, Senegal and DR Congo.

The customer is sent to PawaPay's secure payment page, picks their operator, approves the payment on their phone with their Mobile Money PIN, and comes back to your store. The order is marked paid only once the payment is confirmed.

**No commission on your sales, ever.** The only fees are PawaPay's own processing fees, agreed directly between you and PawaPay. **No limit on the number of payments**, no licence key, no time limit.

https://www.youtube.com/watch?v=GnFboHhBiuQ

En français : [Fosia Pay — le Mobile Money sur WooCommerce avec PawaPay](https://www.youtube.com/watch?v=bUKGWBsmbtw)

= Features =

* WooCommerce payment gateway for the classic checkout and the block-based Cart & Checkout
* Works in the countries and with the operators enabled on your PawaPay account (MTN MoMo, Airtel Money, Orange Money, M-Pesa, Moov, Vodacom and more)
* PawaPay hosted payment page: the plugin never sees or stores Mobile Money PINs
* Automatic conversion from your store currency to the customer's Mobile Money currency
* Amounts follow the decimals and limits set on your PawaPay account
* Payment confirmation you can trust: signed PawaPay callbacks (RFC 9421) are verified, and any unsigned callback is double-checked with PawaPay before an order is marked paid
* Dashboard: volume per currency, success rate and recent payments
* Insights, computed on your site from your own orders: unfinished checkouts at the PawaPay page, failed payments by reason, refunds done by hand
* Sandbox mode for testing before going live
* Compatible with WooCommerce High-Performance Order Storage (HPOS)
* Ready for translation

= Supported countries and Mobile Money operators =

Fosia Pay Lite works with the countries and operators enabled on your PawaPay account:

* **Benin**: MTN MoMo, Moov Money
* **Burkina Faso**: Orange Money, Moov Money
* **Cameroon**: MTN Mobile Money, Orange Money
* **Congo (Brazzaville)**: MTN MoMo, Airtel Money
* **DR Congo**: Vodacom M-Pesa, Airtel Money, Orange Money
* **Côte d'Ivoire**: MTN MoMo, Orange Money, Wave
* **Ethiopia**: Safaricom M-Pesa
* **Gabon**: Airtel Money
* **Ghana**: MTN MoMo, Telecel Cash, AT Money
* **Kenya**: M-Pesa
* **Lesotho**: M-Pesa
* **Malawi**: Airtel Money, TNM Mpamba
* **Mozambique**: Vodacom M-Pesa, Movitel e-Mola
* **Nigeria**: MTN MoMo, Airtel
* **Rwanda**: MTN MoMo, Airtel Money
* **Senegal**: Orange Money, Wave, Free Money
* **Sierra Leone**: Orange Money
* **Tanzania**: Vodacom M-Pesa, Airtel Money, Mixx by Yas, Halopesa
* **Uganda**: MTN MoMo, Airtel Money
* **Zambia**: MTN MoMo, Airtel Money, Zamtel Kwacha
* **Zimbabwe**: EcoCash

Your store can keep its prices in US dollars, euros or any currency: the amount is converted to the customer's Mobile Money currency (RWF, UGX, KES, TZS, GHS, XOF, XAF, CDF, ZMW, NGN and more) at checkout.

= Fosia Pay Pro =

Fosia Pay Pro is a separate, paid plugin by the same team. It adds on-site checkout without redirect, refunds from WooCommerce, payouts, payment links with QR codes, a REST API, and a callback router for several sites on one PawaPay account. Fosia Pay Lite works fully on its own. [Learn more](https://pay.fosiarw.com).

= Requirements =

* WooCommerce
* A [PawaPay](https://www.pawapay.io) merchant account and API token

== External services ==

= PawaPay (payment processor) =

The plugin cannot take payments without PawaPay. Requests go to `api.pawapay.io` (live) or `api.sandbox.pawapay.io` (sandbox mode), with your PawaPay API token.

* **At checkout**, when a customer pays with Mobile Money: the plugin reads your account's amount rules (decimals, minimum and maximum, cached for 1 hour) and creates a PawaPay payment page with the amount and currency, the customer's country, a short text ("Order 123"), a payment id, your store's return URL and the checkout language. The customer's phone number is only sent if you turn on "Pre-fill and lock the Mobile Money number" in the settings (it is then checked with PawaPay's phone number validation).
* **When PawaPay sends a payment result** to your callback URL, or when the customer returns to your store: the plugin may ask PawaPay for the payment's status, and downloads PawaPay's public signing keys (cached for 12 hours) to verify signed callbacks.
* **When you click "Test Connection"** in the settings: the plugin reads your PawaPay account configuration.

PawaPay [Merchant Terms of Service](https://www.pawapay.io/merchant-terms-of-service) and [Privacy Policy](https://www.pawapay.io/privacy-policy).

= ExchangeRate-API (open.er-api.com) =

Used only when your store currency differs from the customer's Mobile Money currency (for example, a EUR store and a customer in Rwanda paying in RWF). At checkout, if no rates are cached, the plugin requests `https://open.er-api.com/v6/latest/{store currency}`. Only the currency code is sent: no personal, customer or order data. Rates are cached for 12 hours.

ExchangeRate-API [Terms of Use and privacy](https://www.exchangerate-api.com/terms).

= Fosia (pay.fosiarw.com) — only if you opt in =

Off by default: nothing is sent to Fosia unless an administrator ticks the consent box and clicks "Connect this site" in FosiaPay > Dashboard > "Connect this site to Fosia (optional)".

* **When you connect**, then **at most once a day**, the plugin sends `https://pay.fosiarw.com/wp-json/fosia/v1/heartbeat`: a random installation ID created on your site, the plugin name and version, your WordPress and PHP versions and your site language. Fosia uses it to count active installations and decide which WordPress and PHP versions to keep supporting.
* **When you click "Disconnect"**, or delete the plugin while connected: the plugin sends the installation ID with a deletion request, Fosia's server deletes the record, and the ID is removed from your site.
* Your domain, e-mail address, customers, orders and PawaPay token are never sent (the request uses a neutral user agent, without your site address).

Fosia [Terms of Service](https://pay.fosiarw.com/terms-of-service/) and [Privacy Policy](https://pay.fosiarw.com/privacy-policy/).

= Fosia (pay.fosiarw.com) — "Quick feedback" when you deactivate, only if you submit it =

When you click "Deactivate" on Fosia Pay Lite in Plugins, a "Quick feedback" window asks why. It is optional: nothing is sent if you click "Skip & Deactivate", the × or Escape (closing it keeps the plugin active).

* **Only if you pick a reason and click "Submit & Deactivate"**, your site (not your browser) sends once to `https://pay.fosiarw.com/wp-json/fosia/v1/feedback`: the reason, the text you typed (optional, 500 characters at most), the product and edition (Fosia Pay Lite), the plugin, WordPress and PHP versions and the site language.
* **Your site address and your e-mail address are sent only if you tick "You may email me about this"** (unticked by default), so that Fosia can answer you. No customer, order or payment data and no PawaPay token are ever sent; the request uses a neutral user agent, without your site address.
* Fosia keeps the answers 12 months, then deletes them. No IP address is stored.

Fosia [Terms of Service](https://pay.fosiarw.com/terms-of-service/) and [Privacy Policy](https://pay.fosiarw.com/privacy-policy/).

= YouTube (setup video), only when you press play =

The Welcome step of the guided setup shows a picture of the Fosia Pay video, stored in the plugin. Nothing is requested from YouTube until you click it; the video then plays from `https://www.youtube-nocookie.com` (Google), which receives your IP address and browser details like any embedded video. Without JavaScript the link opens the video on youtube.com.

YouTube [Terms of Service](https://www.youtube.com/t/terms) and Google [Privacy Policy](https://policies.google.com/privacy).

No other external request is made. The dashboard, its insights and the guided setup load nothing from outside your site (apart from the video above, on click); links to pay.fosiarw.com, PawaPay and WhatsApp only open when you click them.

== Installation ==

1. Install and activate WooCommerce.
2. Install Fosia Pay Lite from Plugins > Add New, then activate it.
3. Go to WooCommerce > Settings > Payments > Fosia Pay Lite.
4. Enter your PawaPay API token and choose Sandbox or Live.
5. Copy the Callback URL shown in the settings into your PawaPay Dashboard under System Configuration > Callback URLs (Deposits). Turning on "signed callbacks" there is recommended.
6. Click "Test Connection", then save.

== Frequently Asked Questions ==

= How do I accept MTN MoMo payments on WooCommerce? =

Install and activate Fosia Pay Lite, then follow the guided setup: choose Sandbox or Live, paste your PawaPay API token and copy the callback URL into your PawaPay Dashboard. Place a test order in sandbox mode, then switch to Live. Customers choose MTN MoMo (MTN Mobile Money) on the payment page and approve the payment on their phone. MTN MoMo is available in Benin, Cameroon, Congo, Côte d'Ivoire, Ghana, Nigeria, Rwanda, Uganda and Zambia, if it is enabled on your PawaPay account.

= Does it work with M-Pesa (MPesa, Mpesa)? =

Yes. M-Pesa is supported in Kenya, Tanzania (Vodacom M-Pesa), DR Congo, Mozambique, Lesotho and Ethiopia, if it is enabled on your PawaPay account.

= Does it work with Airtel Money? =

Yes, in Rwanda, Uganda, Tanzania, Zambia, Malawi, DR Congo, Congo, Gabon and Nigeria, if it is enabled on your PawaPay account.

= Does it work with Orange Money? =

Yes, in Cameroon, Côte d'Ivoire, Senegal, Burkina Faso, DR Congo and Sierra Leone, if it is enabled on your PawaPay account. Wave, Moov Money and Free Money are supported in West Africa too.

= Is Fosia Pay Lite free? =

Yes. It is free, with no limit on the number of payments, no licence key and no time limit. Fosia takes no commission on your sales.

= Does Fosia Pay Lite take a commission on my sales? =

No, never. The only fees are PawaPay's own processing fees.

= Is there a limit on the number of payments? =

No. Fosia Pay Lite has no payment limit and no time limit.

= Do I need a PawaPay account? =

Yes. Fosia Pay Lite connects to the PawaPay API to process payments, and the money goes to your own PawaPay merchant account, never through Fosia. Apply for a merchant account at pawapay.io: PawaPay checks your business documents and enables the countries and operators you ask for. You can start with a sandbox account to test.

= Which countries and operators are supported? =

21 African countries: Benin, Burkina Faso, Cameroon, Congo, DR Congo, Côte d'Ivoire, Ethiopia, Gabon, Ghana, Kenya, Lesotho, Malawi, Mozambique, Nigeria, Rwanda, Senegal, Sierra Leone, Tanzania, Uganda, Zambia and Zimbabwe, with MTN MoMo, Airtel Money, Orange Money, M-Pesa, Moov Money, Wave, Telecel Cash, EcoCash and other operators depending on the country. See "Supported countries and Mobile Money operators" above. You can use those enabled on your PawaPay account.

= Can my store keep its prices in US dollars or euros? =

Yes. The amount is converted to the customer's Mobile Money currency at checkout, at the current exchange rate. Fosia Pay Lite sits next to your other WooCommerce payment methods (cards, PayPal and so on).

= Does it work with the WooCommerce block checkout? =

Yes. It works with the classic checkout and the block-based Cart & Checkout, and with High-Performance Order Storage (HPOS).

= Does the customer stay on my site? =

No: the customer is redirected to PawaPay's secure payment page, then back to your store. Fosia Pay Pro offers on-site checkout.

= Can I refund from WooCommerce? =

Not with Fosia Pay Lite: refund the customer from your PawaPay Dashboard. Fosia Pay Pro adds refunds from WooCommerce.

= Do I need to turn on signed callbacks? =

It is recommended, not required. Signed callbacks are verified and applied at once; unsigned callbacks are never trusted on their own: the plugin asks PawaPay for the real status first.

= Does the plugin send data to Fosia? =

Not unless you choose to. The dashboard insights are computed on your site from your own orders and are never sent. The optional "Connect this site to Fosia" (off by default) sends a random installation ID, the plugin, WordPress and PHP versions and the site language once a day; you can disconnect at any time and the record is deleted. When you deactivate the plugin, the "Quick feedback" window sends your answer only if you click "Submit & Deactivate" (your site address and e-mail only if you tick the box). See "External services".

= Can I hide the Pro suggestions? =

Yes. The insights card on the FosiaPay dashboard has a "Hide" link, the hint on order screens has "Don't show again", and the "Mobile Money this month" widget on the WordPress dashboard can be hidden from Screen Options. Hiding them changes nothing else: every Lite feature keeps working.

= What happens to my data when I delete the plugin? =

Deleting the plugin removes its settings (including your API token) and cached data, and, if the site was connected to Fosia, asks Fosia's server to delete its record. Your orders and their notes are kept.

== Changelog ==

= 1.1.0 =
* Added: a guided setup that opens once, right after you activate the plugin (never on bulk activation): Welcome (what Fosia Pay Lite does, the video, which loads from YouTube only when you press play), Mode (Sandbox or Live), PawaPay token (saved and tested), Confirmations (the callback URL with a Copy button), Done (what is set up, next step, help links). "Exit guided setup" on every step saves what you entered; "Resume setup" stays on the FosiaPay dashboard until it is finished. Phone-friendly and keyboard-friendly.
* Added: a short "Quick feedback" window when you deactivate the plugin, with a link to support. Optional: nothing is sent on "Skip & Deactivate"; see "External services" for what "Submit & Deactivate" sends.

= 1.0.7 =
* Fixed: the "Test Connection" button in the gateway settings always answered "Request failed (400)", because WooCommerce does not load payment gateways during AJAX requests. The check is now registered when the plugin loads. The "Don't show again" link on the refund notice had the same problem and is fixed too.
* Added: "Insights" on the FosiaPay dashboard, computed on your site from your own orders (nothing is sent): this month's unfinished checkouts at the PawaPay page, failed payments by reason and refunds done by hand, each with a daily trend and what Fosia Pay Pro would change. Can be hidden.
* Added: failed payments now keep PawaPay's failure code on the order, so the dashboard can group them by reason.
* Added: on a Mobile Money order that failed or was refunded by hand, a one-line hint in the order details, with "Don't show again".
* Added: a "Mobile Money this month" widget on the WordPress dashboard (paid orders, unfinished checkouts, failed payments). Hide it from Screen Options.
* Added: optional "Connect this site to Fosia", off by default. Once you agree, a random installation ID, the plugin, WordPress and PHP versions and the site language are sent once a day; "Disconnect" (or deleting the plugin) deletes the record. See "External services".
* Changed: the refund notice on the order screen is no longer shown once the order has a refund.
* Added: a setup checklist at the top of the FosiaPay dashboard (turn on the gateway, add the PawaPay token, test the connection, paste the callback URL with a Copy button, first payment), with Sandbox/Live shown. Once everything is done it shrinks to a one-line status (connection tested, last callback received).
* Changed: no "Upgrade to Pro" page or menu item any more, and no Pro mention in insights, notices or order hints; one plain line at the bottom of the FosiaPay dashboard says what the separate Pro plugin adds.
* Changed: the dashboard shows "—" instead of "0%" success rate when there is no transaction yet, splits transactions into paid / pending / failed, and the empty activity card links to "All time".

= 1.0.6 =
* Changed: no more monthly payment limit. Fosia Pay Lite is free with unlimited payments.
* Fixed: payments were never confirmed when PawaPay's "signed callbacks" option was off. Unsigned callbacks are now checked with PawaPay (deposit status) before an order is marked paid, with abuse limits. The "Webhook Secret" setting was removed (PawaPay has no such secret).
* Fixed: signed callbacks could never be verified because WordPress adds slashes to request headers.
* Fixed: a payment page rejected by PawaPay (HTTP 200, status REJECTED) showed "Payment Error: Unknown"; the customer now gets a clear message and the reason is added to the order notes. A timeout or PawaPay server error is checked instead of being treated as a failure.
* Fixed: amounts now follow the decimals and limits of your PawaPay account (amounts like "1500.00" were refused), and the order text sent to PawaPay respects its format.
* Changed: the customer types their Mobile Money number on PawaPay's page and may pay from any number. Optional setting to pre-fill and lock it to the billing phone (validated by PawaPay).
* Changed: the confirmation page checks the payment status when the customer comes back from PawaPay.
* Changed: PawaPay v2 public key endpoint; operator read from the v2 callback.
* Changed: logs go to WooCommerce > Status > Logs, without phone numbers or request bodies; new "Debug log" setting.
* Changed: the "Upgrade to Pro" page no longer downloads prices from pay.fosiarw.com; admin notices are limited to the relevant screens and can be dismissed.
* Changed: all texts are translatable; deleting the plugin removes its settings.

= 1.0.5 =
* Fixed: orders stay "Pending payment" until PawaPay confirms payment.
* Fixed: a late "failed" callback could mark an already-paid order as failed.
* Fixed: a completed payment with a different amount or currency now puts the order on hold.
* Security: stricter callback signature checks.
* Fixed: currency conversion rounding, dashboard totals per currency.

= 1.0.4 =
* Added: refunds notice on order screens. Fixed: checkout is blocked instead of under-charging when exchange rates are unavailable.

= 1.0.0 =
* Initial release.

== Upgrade Notice ==

= 1.1.0 =
A guided setup opens once after activation (Mode, PawaPay token, callback URL), and an optional Quick feedback window when you deactivate.

= 1.0.7 =
New Insights on the dashboard, computed locally from your own orders. Optional, off-by-default "Connect this site to Fosia".

= 1.0.6 =
No more payment limit. Payments are now confirmed even without PawaPay "signed callbacks", and PawaPay rejections are shown clearly. Recommended update.
