=== Cartflox Payments for WooCommerce ===
Contributors: cartflox
Tags: payment gateway, mobile money, orange money, wave, africa
Requires at least: 6.2
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 4.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Accept Orange Money, Wave, MTN MoMo, Moov Money, M-Pesa and bank cards on your WooCommerce store, through Cartflox.

== Description ==

Cartflox adds a payment method to your WooCommerce store for African mobile money and bank cards. When the customer places the order, they are sent to the Cartflox payment page, where they choose their operator, enter their number and confirm. They come back to your store, and the order is marked as paid on its own thanks to the signed webhook.

The plugin works with both Cartflox offers: your own aggregator accounts, or the payment methods provided by Cartflox. One secret key is all you need.

= Everything is configurable =

* Title, description, which operator logos are shown and how big they are.
* Place order button text, message on the thank you page and in the order emails.
* Payment session label with variables, return address after payment and after the customer gives up.
* Order status while awaiting payment and once paid.
* Automatic check of pending orders, automatic cancellation after a delay you choose.
* Fixed or percentage fee when the customer picks Cartflox, minimum and maximum amount, accepted currencies.
* Automatic webhook registration, detailed log.

= Built to be reliable =

* The webhook is verified with an HMAC-SHA256 signature and a timestamp before anything touches an order.
* The received amount and currency are compared with the order total; a mismatch puts the order on hold with an explanatory note instead of marking it paid.
* If the webhook cannot arrive, the order is still confirmed when the customer returns, and by a check that runs every five minutes for 24 hours.
* Works with both the classic and the block based checkout, and with High Performance Order Storage.

= For developers =

* `cartflox_session_donnees( $data, $order )` filters the payload sent to Cartflox.
* `cartflox_montant_frais( $amount, $cart )` filters the payment fee.
* `cartflox_paiement_confirme( $order, $data )` fires when a payment is confirmed.

== External services ==

This plugin connects to the Cartflox payment service to create and follow payment sessions. It is required for the plugin to work: without it, no payment can be taken.

When a customer places an order and selects Cartflox, the plugin sends to `https://cartflox.com/api`:

* the order amount, currency and label,
* the customer name, email address and phone number, when the prefill option is enabled,
* the order number, order key and your store address, so the payment can be matched back to the order.

The plugin also asks Cartflox for the status of a payment session, and registers your store webhook address so Cartflox can notify your store when a payment succeeds or fails.

Service provided by Cartflox. Terms of service: https://cartflox.com/terms. Privacy policy: https://cartflox.com/privacy.

== Installation ==

1. In WordPress, go to Plugins, Add New, Upload Plugin, choose the .zip file, then Activate.
2. Go to WooCommerce, Settings, Payments, Cartflox, Manage.
3. Paste your secret key (it starts with af_live_sec_), found in your Cartflox dashboard under API and logs.
4. Save. The plugin checks the key and registers your store webhook address in Cartflox.

Your store must be served over HTTPS to receive webhooks. Without HTTPS, orders are confirmed when the customer returns and by the automatic check.

== Frequently Asked Questions ==

= Do I need a Cartflox account? =

Yes. Create one at https://cartflox.com, then copy your secret key from the API and logs page.

= The customer paid but the order is still pending =

Open the order: the Cartflox box shows the real payment status, and the Check now button asks Cartflox directly. Also make sure your store is on HTTPS and that the webhook is registered, which the Connection status panel tells you.

= Can I charge a fee to the customer? =

Yes, in the Fees and limits section: a fixed amount, a percentage, or both.

= Which currencies are supported? =

XOF, XAF, GHS, NGN, KES, GNF, CDF, RWF, TZS, UGX, ZMW, MAD, USD and EUR. Cartflox expects whole amounts, so currencies with decimals are rounded to the unit.

= Is the plugin translated? =

The interface is in English and ships with a full French translation.

== Screenshots ==

1. The payment method at checkout, with the operator logos you selected.
2. The plugin settings in WooCommerce, with the connection status panel.
3. The Cartflox box on an order: status, operator, reference and manual check.
4. The thank you page while the payment is being confirmed.

== Changelog ==

= 4.1.0 =
* English interface with a complete French translation.
* Compliance work for the WordPress plugin directory: escaping, sanitisation, translator comments.
* Declares WooCommerce as a required plugin.

= 4.0.0 =
* Full rewrite: settings organised in sections, everything configurable.
* Connection status panel and a Test the connection button.
* Cartflox box on every order with status, operator, reference, manual check and a link to Cartflox.
* Automatic check of pending orders every five minutes, optional automatic cancellation.
* Thank you page that updates by itself while the payment is confirmed.
* Fixed or percentage payment fee, also in the block based checkout.
* Configurable place order button text, chosen logos at the size you want.
* Cartflox reference added to the order emails.
* Idempotency key: no more duplicate sessions when a customer comes back to pay.
* Phone number converted to international format from the billing country.

= 3.0.0 =
* Signed webhook, status check when the customer returns, block checkout and HPOS support.

== Upgrade Notice ==

= 4.1.0 =
Interface now in English with a French translation, and compliance with the plugin directory rules.
