=== SunPayment — Mobile Money Gateway for WooCommerce ===
Contributors: sunpayment
Tags: woocommerce, mobile-money, orange-money, moov-money, telecel, burkina-faso, uemoa, payment-gateway
Requires at least: 5.8
Tested up to: 6.6
Stable tag: 2.1.0
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Acceptez les paiements Mobile Money (Orange Money, Moov Money et Telecel BDK) sur WooCommerce avec validation instantanée et réconciliation temps réel.

== Description ==

SunPayment est la passerelle de paiement Mobile Money de référence pour la zone UEMOA (Burkina Faso, Côte d'Ivoire, Sénégal, Mali).

Ce module permet à vos clients de régler leurs commandes en toute simplicité via leurs portefeuilles électroniques préférés :
* **Orange Money**
* **Moov Money**
* **Telecel BDK**

### Fonctionnalités Clés :
* **Redirection Hosted Checkout** : Interface de paiement ultra-rapide et responsive adaptée aux smartphones.
* **Checkout classique et checkout par blocs** : le champ « Numéro Mobile Money » est proposé dans les deux, pré-rempli avec le téléphone de facturation.
* **Compatible HPOS** : stockage des commandes dans les tables dédiées de WooCommerce (High-Performance Order Storage) déclaré et respecté.
* **Validation Instantanée par SMS** : Réconciliation automatique en moins de 300 ms sans intervention humaine.
* **Sécurité Bancaire HMAC-SHA256** : Chaque webhook est authentifié par sa signature, puis le paiement est revérifié auprès de l'API SunPayment avant de passer la commande en payée.
* **Remboursements** : une demande de remboursement depuis la commande WooCommerce crée la demande auprès de SunPayment (validation ensuite par SunPayment).
* **Prise en charge des Acomptes Partiels** : Gestion intelligente des paiements fractionnés avec consignation automatique.
* **Reçus Officiels PDF** : Téléchargement instantané de quittances avec QR Code et preuve cryptographique.

== Installation ==

1. Téléchargez l'archive `sunpayment-woocommerce.zip`.
2. Rendez-vous dans votre tableau de bord WordPress > **Extensions** > **Ajouter une extension** > **Téléverser une extension**.
3. Sélectionnez le fichier zip et cliquez sur **Installer maintenant**, puis sur **Activer l'extension**.
4. Allez dans **WooCommerce** > **Réglages** > onglet **Paiements** > **SunPayment Mobile Money**.
5. Renseignez votre **Clé API (API Key)** et votre **Secret API** obtenus dans votre Espace Marchand SunPayment. Les deux sont indispensables : l'API SunPayment les exige pour créer chaque paiement, et sans eux la passerelle n'est pas proposée au checkout. Le Secret API sert aussi à vérifier la signature des webhooks et à confirmer chaque paiement.
6. Choisissez l'**Opérateur Mobile Money** (Orange Money par défaut) et l'**Environnement** (en mode test, un badge « mode test » apparaît au checkout et l'identifiant de commande envoyé à SunPayment est préfixé par `test_`).
7. Laissez le champ **Secret de signature Webhook** vide, sauf si un secret webhook dédié a été configuré sur votre compte SunPayment.
8. Copiez l'URL Webhook indiquée et collez-la dans votre Espace Marchand > Webhooks, puis utilisez le bouton « Tester le webhook » du portail : il doit renvoyer un code 200.
9. Enregistrez les modifications : votre boutique est prête à encaisser !

== Numéro Mobile Money ==

SunPayment exige le numéro Mobile Money du client (8 à 15 chiffres, « + » initial toléré). Le plugin le demande dans le formulaire de paiement (champ « Numéro Mobile Money », pré-rempli avec le téléphone de facturation), aussi bien dans le checkout classique que dans le checkout par blocs. À défaut de saisie, le téléphone de facturation de la commande est utilisé ; si aucun des deux n'est valide, le paiement est refusé avec un message d'erreur. Aucun numéro de repli n'est jamais envoyé à SunPayment.

== Remboursements ==

Depuis la commande WooCommerce, « Rembourser via SunPayment » appelle `POST /api/v1/payments/{payment_id}/refunds/` (montant, motif, type `customer_refund`, clé d'idempotence). SunPayment enregistre la demande et réserve les fonds ; elle est ensuite validée (ou refusée) par SunPayment. Une note « remboursement demandé, en attente de validation » est ajoutée à la commande ; les webhooks `refund.approved`, `refund.completed`, `refund.rejected` et `refund.cancelled` y ajoutent ensuite le résultat. Si l'API refuse la demande (plafond, solde insuffisant, paiement non remboursable), le remboursement WooCommerce n'est pas créé et l'erreur est affichée.

== Sécurité des webhooks ==

SunPayment signe chaque notification avec l'en-tête `X-SunPayment-Signature: t=<horodatage unix>,v1=<HMAC-SHA256 hexadécimal>`. Le HMAC porte sur la chaîne `<t>.<corps brut>`. La clé de signature est le secret webhook dédié du compte marchand s'il existe, sinon l'empreinte SHA-256 de votre Secret API : le plugin la recalcule automatiquement à partir de vos réglages.

Le plugin applique les règles suivantes :
* Un webhook sans signature valide, ou dont l'horodatage s'écarte de plus de 5 minutes de l'horloge du serveur, est refusé (HTTP 401). Aucun court-circuit n'est possible si le secret est absent : le webhook est alors refusé aussi.
* Un webhook dont le `payment_id` n'est pas celui enregistré sur la commande (méta `_sunpayment_id`) est refusé (HTTP 403).
* Les relivraisons d'un même événement (en-tête `X-SunPayment-Event-Id`) répondent 200 sans rien modifier.
* Avant de passer une commande en payée sur `payment.completed`, le plugin relit le paiement via `GET /api/v1/payments/{id}/status/` avec vos identifiants API et vérifie le statut `completed`, l'identifiant de commande, la devise et le montant perçu. En cas d'écart, la commande passe « En attente » avec une note explicative et n'est jamais marquée payée.
* `payment.cancelled` et `payment.expired` n'annulent qu'une commande encore en attente, et seulement si l'API confirme le statut `cancelled` ou `expired`.
* `refund.*` et les autres événements sont consignés en note de commande, sans changer son statut.
* Si l'API SunPayment est momentanément injoignable, le plugin répond 503 et SunPayment relivre le webhook automatiquement.

== Changelog ==

= 2.1.0 =
* Numéro Mobile Money demandé au checkout (champ `sunpayment_phone`, checkout classique et par blocs), repli sur le téléphone de facturation, refus si aucun numéro valide : plus aucun numéro de repli envoyé à SunPayment.
* Compatibilité HPOS (tables de commandes dédiées) et checkout par blocs déclarées ; prise en charge du checkout par blocs (`WC_Sunpayment_Blocks_Support`, `assets/js/blocks.js`).
* Remboursements : `process_refund()` crée la demande via `POST /api/v1/payments/{payment_id}/refunds/` (type `customer_refund`, clé d'idempotence) et consigne « en attente de validation ».
* Webhooks : contrôle strict du `payment_id` par rapport à la commande (HTTP 403 sinon), déduplication par `X-SunPayment-Event-Id`, prise en charge de `payment.cancelled` et des événements `refund.*`, revérification du statut avant annulation sur `payment.cancelled` / `payment.expired`.
* Réglage **Opérateur Mobile Money** (orange, moov, telecel) utilisé dans chaque requête ; **Environnement** réellement appliqué (badge « mode test », `external_id` préfixé `test_`).
* `idempotency_key` et `cancel_url` transmis à la création du paiement ; requêtes HTTP sans suivi de redirection (`redirection => 0`), délai de 20 s ; la passerelle n'est proposée que si la clé API et le secret API sont renseignés.
* Icône `assets/icon.svg`.

= 2.0.1 =
* Vérification de signature alignée sur le format réellement émis par SunPayment (`t=…,v1=…`, HMAC de `t.corps`) avec fenêtre anti-rejeu de 5 minutes.
* La signature est désormais obligatoire : plus aucun webhook n'est accepté sans secret configuré.
* Clé de signature dérivée automatiquement du Secret API lorsque aucun secret webhook dédié n'est défini (comportement du serveur).
* Lecture des champs à la racine du payload (`payment_id`, `external_id`, `amount_paid`…), avec compatibilité `data.*`.
* Revérification du paiement auprès de l'API SunPayment (statut, commande, devise, montant) avant `payment_complete`.
* Prise en charge des événements `webhook.test`, `payment.partially_paid_expired` et `payment.needs_review`, déduplication par identifiant d'événement.

= 2.0.0 =
* Version initiale complète pour SunPayment V2.
* Support complet des webhooks signés HMAC-SHA256.
* Gestion des acomptes partiels et des expirations de délai.
