Le réseau se reconnaît tout seul. The network recognises itself.

Pour le marchandFor the merchant

Le parcours clientThe customer journey

Quatre temps, dont un seul se passe sur votre boutique. La confirmation, elle, a lieu sur le téléphone du client. Four moments, only one of which happens on your store. The confirmation itself takes place on the customer's phone.

Quand le numéro ne convient pasWhen the number doesn't work

Un numéro incomplet, mal formé, étranger, ou appartenant à un réseau non pris en charge bloque le bouton de paiement B-Cash — et lui seul. Vos autres moyens de paiement restent utilisables normalement. Aucun appel de paiement n'est déclenché tant que le numéro n'est pas reconnu. An incomplete, malformed, foreign, or unsupported number disables the B-Cash payment button — and only that one. Your other payment methods keep working normally. No payment call is made until the number is recognised.

Pour le marchandFor the merchant

Qui paie les fraisWho pays the fees

Deux politiques, un réglage. Dans les deux cas, le montant affiché au client est exactement le montant débité — jamais un centime d'écart. Two policies, one setting. Either way, the amount shown to the customer is exactly the amount debited — never a franc off.

Exemple sur une commande de 10 000 XAF avec des frais de 250 XAF : Example on a 10,000 XAF order with 250 XAF in fees:

Le réglage se trouve dans WooCommerce → Réglages → Paiements → B-Cash, champ Politique de frais. Le libellé de la ligne est modifiable. The setting lives in WooCommerce → Settings → Payments → B-Cash, field Fee policy. The line label can be customised.

Pour le marchandFor the merchant

Suivre vos paiementsTracking payments

Tout se passe dans WooCommerce. Une page dédiée donne le détail technique quand vous en avez besoin. Everything happens inside WooCommerce. A dedicated page gives you the technical detail when you need it.

Sur la commandeOn the order

Chaque commande payée par B-Cash porte la référence de transaction, le réseau utilisé, le numéro masqué, les frais et le total débité. Une note de commande enregistre chaque étape. Every B-Cash order carries the transaction reference, the network used, the masked phone number, the fees and the total debited. An order note records each step.

Page B-CashB-Cash page

Dans WooCommerce → B-Cash → Transactions, vous retrouvez toutes les tentatives de paiement : date, commande, essai, réseau, numéro masqué, montant, statut et référence. Un bouton Synchroniser force la relecture d'une transaction auprès de B-Cash si vous avez un doute. Under WooCommerce → B-Cash → Transactions you'll find every payment attempt: date, order, attempt, network, masked number, amount, status and reference. A Sync button forces a fresh read from B-Cash whenever you're unsure.

Pour le marchandFor the merchant

Remboursements et annulationRefunds and cancellation

RembourserRefunding

Le remboursement se fait depuis l'écran habituel de WooCommerce, total ou partiel. Le plugin transmet la demande à B-Cash et attend une confirmation vérifiée avant de marquer le remboursement comme effectué. Refunds happen from the usual WooCommerce screen, in full or in part. The plugin forwards the request to B-Cash and waits for a verified confirmation before marking the refund as complete.

Le bouton de remboursement n'apparaît que si votre compte B-Cash dispose du droit correspondant. The refund button only appears if your B-Cash account holds the matching permission.

AnnulerCancelling

Une demande de paiement peut être annulée tant qu'elle n'est pas partie chez l'opérateur. Une fois en cours de traitement, elle ne l'est plus : l'argent est peut-être déjà en mouvement. Si le client ne confirme jamais, la demande expire d'elle-même et la commande redevient payable. A payment request can be cancelled as long as it hasn't reached the operator. Once it is being processed it cannot: money may already be moving. If the customer never confirms, the request expires on its own and the order becomes payable again.

Contre-passationReversal

Si B-Cash contre-passe une transaction sans que vous l'ayez demandé, la commande est repassée en remboursée et une note d'alerte est ajoutée. Vérifiez avant toute expédition. If B-Cash reverses a transaction you didn't request, the order is moved to refunded and an alert note is added. Check before shipping anything.

InstallationSetup

PrérequisRequirements

À vérifier avant de commencer. Si l'un de ces points manque, la passerelle n'apparaîtra pas au moment du paiement. Check these first. If any is missing, the gateway simply won't show up at checkout.

Droits requis sur votre compte B-CashPermissions required on your B-Cash account

Vérifiez ces droits dans votre tableau de bord B-Cash. Le plugin les affiche et signale ceux qui manquent. Check these in your B-Cash dashboard. The plugin displays them and flags any that are missing.

InstallationSetup

Installer le pluginInstall the plugin

Comptez une quinzaine de minutes, test en sandbox compris. Allow about fifteen minutes, sandbox test included.

1. Installer et activerInstall and activate

   Dans Extensions → Ajouter → Téléverser, envoyez le fichier bcash-payments-for-woocommerce.zip puis activez. Aucune compilation n'est nécessaire : le paquet est prêt à l'emploi. Under Plugins → Add New → Upload, send bcash-payments-for-woocommerce.zip and activate. No build step is needed: the package ships ready to run.

2. Renseigner vos identifiantsEnter your credentials

   Ouvrez WooCommerce → B-Cash → Connexion, collez votre clé publique et votre secret, puis enregistrez. Le plugin teste immédiatement la connexion et affiche le nom de votre compte marchand. Si ce nom n'apparaît pas, ne continuez pas — voir la section Résolution de problèmes. Open WooCommerce → B-Cash → Connection, paste your public key and secret, then save. The plugin immediately tests the connection and shows your merchant account name. If that name doesn't appear, stop here — see Troubleshooting.

   L'environnement est déduit du préfixe de la clé : pk_test_ pour la sandbox, pk_live_ pour la production. Un bandeau le rappelle en permanence. The environment is inferred from the key prefix: pk_test_ for sandbox, pk_live_ for production. A banner reminds you at all times.

   Plus sûr : les constantesSafer: use constants

   En production, préférez placer vos identifiants dans wp-config.php. Ils ne transitent alors jamais par la base de données et ne sont pas modifiables depuis l'administration. In production, prefer putting your credentials in wp-config.php. They then never touch the database and cannot be changed from the admin.

   CopierCopy

   define( 'BCASH_PK', 'pk_live_votre_cle_publique' );
   define( 'BCASH_SK', 'sk_live_votre_secret' );

3. Enregistrer les notificationsRegister notifications

   Onglet Webhooks → Enregistrer cette boutique. Le plugin déclare son adresse auprès de B-Cash et stocke le secret de signature, chiffré. Cliquez ensuite sur Envoyer un test : la date de réception doit apparaître en quelques secondes. Go to the Webhooks tab → Register this store. The plugin declares its address with B-Cash and stores the signing secret, encrypted. Then click Send a test: the received timestamp should appear within seconds.

   Sans cette étape, vos commandes resteront en attente même après un paiement réussi. Skip this and your orders will sit on hold even after a successful payment.

4. Activer la passerelleEnable the gateway

   Dans WooCommerce → Réglages → Paiements, activez B-Cash — Paiement Mobile Money. Choisissez votre politique de frais et, si vous le souhaitez, adaptez le titre affiché au client. Under WooCommerce → Settings → Payments, enable B-Cash — Mobile Money. Choose your fee policy and, if you like, adjust the title shown to customers.

5. Passer une commande de testPlace a test order

   Avec des identifiants sandbox, passez une commande de bout en bout et vérifiez qu'elle se confirme seule. Voir la section suivante pour forcer un succès, un échec ou une expiration. With sandbox credentials, place an end-to-end order and check it confirms on its own. See the next section to force a success, a failure or an expiry.

InstallationSetup

NotificationsNotifications

C'est par elles que votre boutique apprend qu'un paiement a abouti. Elles méritent deux minutes d'attention. This is how your store learns a payment succeeded. Worth two minutes of your attention.

B-Cash envoie ses notifications à une adresse unique sur votre site : B-Cash sends its notifications to a single address on your site:

https://votre-boutique.example/wp-json/bcash/v1/webhook

Chaque message est signé. Le plugin recalcule la signature sur le contenu exact reçu et rejette tout ce qui ne correspond pas. Une adresse IP ne prouve rien et n'est jamais utilisée comme preuve. Every message is signed. The plugin recomputes the signature over the exact payload received and rejects anything that doesn't match. An IP address proves nothing and is never used as proof.

Ce qui est prévu, et qui arrive vraimentWhat's anticipated, and does happen

• Un message en double — reçu deux fois, traité une seule. La commande n'est jamais confirmée deux fois.A duplicate message — received twice, processed once. The order is never confirmed twice.
• Des messages dans le désordre — un « en cours » arrivé après un « réussi » est ignoré. L'état ne recule jamais.Out-of-order messages — a “processing” arriving after a “succeeded” is ignored. State never goes backwards.
• Aucun message du tout — le plugin relit la transaction auprès de B-Cash à 15 s, 30 s, 1 min et 2 min, puis toutes les heures. Une notification perdue ne bloque pas une commande.No message at all — the plugin re-reads the transaction from B-Cash at 15 s, 30 s, 1 min and 2 min, then hourly. A lost notification never strands an order.
• Un changement de secret — pendant 24 heures, l'ancien et le nouveau sont acceptés. Aucune coupure.A secret rotation — for 24 hours both the old and the new are accepted. No downtime.

InstallationSetup

Tester avant productionTest before going live

Avec des identifiants pk_test_, aucun argent réel ne circule. Le montant de la commande décide du scénario. With pk_test_ credentials, no real money moves. The order amount decides the scenario.

La liste de recetteThe acceptance checklist

Avant de basculer en production, vérifiez ces huit points : Before switching to production, verify these eight points:

• Un paiement MTN aboutit et la commande passe en payée.An MTN payment completes and the order becomes paid.
• Un paiement Orange aboutit également.An Orange payment completes too.
• Un numéro en 660 ou 685 bloque le bouton, sans appel de paiement.A 660 or 685 number disables the button, with no payment call.
• Les frais apparaissent bien dans le total si vous les facturez au client.Fees show in the total if you pass them to the customer.
• Un montant en …13 échoue proprement, avec un message compréhensible.An amount ending …13 fails cleanly, with a readable message.
• Un double clic sur « Payer » ne crée qu'une seule transaction.Double-clicking “Pay” creates only one transaction.
• Un remboursement partiel puis total fonctionne.A partial then a full refund both work.
• Le test de notification a bien été reçu.The notification test was received.

RéférenceReference

Cycle de vie d'un paiementPayment lifecycle

Correspondance entre l'état côté B-Cash et le statut de votre commande WooCommerce. How a B-Cash state maps to your WooCommerce order status.

Le cas de la coupure réseauThe network cut case

Si la connexion se coupe pendant l'envoi de la demande, le plugin ne conclut jamais à l'échec et ne recrée jamais une seconde demande. Il marque la tentative comme incertaine, puis interroge B-Cash avec la même clé d'identification pour savoir ce qui s'est réellement passé. C'est ce mécanisme qui rend un double débit impossible. If the connection drops while the request is in flight, the plugin never concludes it failed and never creates a second request. It marks the attempt as uncertain, then queries B-Cash with the same identifying key to find out what actually happened. This is what makes a double charge impossible.

RéférenceReference

Résolution de problèmesTroubleshooting

Les cas réellement rencontrés, dans l'ordre de fréquence. The cases that actually come up, in order of frequency.

B-Cash n'apparaît pas au paiementB-Cash doesn't appear at checkout

Cinq causes possibles, à vérifier dans cet ordre :Five possible causes, check in this order:

• La devise de la boutique n'est pas XAF.The store currency isn't XAF.
• La passerelle n'est pas activée dans Réglages → Paiements.The gateway isn't enabled under Settings → Payments.
• Les identifiants ne sont pas renseignés, ou le test de connexion a échoué.Credentials are missing, or the connection test failed.
• Le site n'est pas en HTTPS alors que vous utilisez des identifiants de production.The site isn't on HTTPS while you're using production credentials.
• Un droit obligatoire manque sur votre compte B-Cash — l'onglet Connexion le signale en rouge.A required scope is missing on your B-Cash account — the Connection tab flags it in red.

Le test de connexion échoueThe connection test fails

La cause la plus fréquente n'est pas le secret : c'est l'horloge du serveur. B-Cash refuse une requête dont l'horodatage s'écarte de plus de cinq minutes. Demandez à votre hébergeur de vérifier la synchronisation NTP. Vérifiez ensuite que la clé et le secret proviennent du même environnement — une clé pk_test_ avec un secret sk_live_ échoue toujours. The commonest cause isn't the secret: it's the server clock. B-Cash rejects a request whose timestamp drifts by more than five minutes. Ask your host to check NTP sync. Then confirm the key and secret come from the same environment — a pk_test_ key with an sk_live_ secret always fails.

Les commandes restent en attenteOrders stay on hold

Le paiement a peut-être réussi sans que votre boutique l'apprenne. Deux vérifications : The payment may well have succeeded without your store hearing about it. Two checks:

• Les notifications arrivent-elles ? Onglet Webhooks → Envoyer un test. Si rien n'arrive, l'adresse n'est pas enregistrée, elle n'est pas en HTTPS, ou un pare-feu bloque les requêtes entrantes. Are notifications arriving? Webhooks tab → Send a test. If nothing lands, the address isn't registered, isn't on HTTPS, or a firewall is blocking inbound requests.
• Les tâches planifiées tournent-elles ? Regardez WooCommerce → État → Action Scheduler. Si des tâches s'accumulent en attente, WP-Cron est probablement désactivé — c'est fréquent chez les hébergeurs qui imposent un cron système. Are scheduled tasks running? Look at WooCommerce → Status → Action Scheduler. If tasks pile up as pending, WP-Cron is likely disabled — common with hosts that mandate a system cron.

En attendant, le bouton Synchroniser de la page Transactions règle le cas immédiatement, commande par commande. Meanwhile, the Sync button on the Transactions page settles it right away, order by order.

La ligne de frais n'apparaît pasThe fee line doesn't appear

Vérifiez que la politique est bien « frais à la charge du client ». En mode absorbé, aucune ligne n'est ajoutée — c'est le comportement attendu. Sinon, la ligne n'apparaît qu'une fois le numéro saisi et le réseau reconnu : sans opérateur, aucun calcul de frais n'est possible. Check the policy is set to “customer pays the fees”. In absorbed mode no line is added — that's expected. Otherwise, the line only appears once a number is entered and the network recognised: with no operator, no fee can be computed.

Un réseau est indisponibleA network is unavailable

Quand un opérateur est déclaré hors service, le paiement est bloqué pour ce réseau et un message l'explique au client. En état dégradé, vous choisissez : bloquer ou laisser passer avec un avertissement. Le réglage se trouve dans les options de la passerelle. When an operator is reported down, payment is blocked for that network and a message explains why. In degraded state, you choose: block, or allow with a warning. The setting lives in the gateway options.

Où trouver les journauxWhere to find the logs

WooCommerce → État → Journaux, source bcash-payments. Les secrets, signatures et numéros complets en sont systématiquement expurgés : vous pouvez transmettre un extrait au support sans risque. Joignez-y l'identifiant de corrélation affiché sur la transaction, il permet de retrouver la trace côté B-Cash. WooCommerce → Status → Logs, source bcash-payments. Secrets, signatures and full phone numbers are systematically stripped: you can send an excerpt to support safely. Include the correlation ID shown on the transaction — it lets B-Cash find the matching trace.

RéférenceReference

Codes d'erreurError codes

Ce que le plugin fait déjà tout seul, et ce qui réclame votre intervention. What the plugin already handles on its own, and what needs you.

Le client, lui, ne voit jamais ces codes : le plugin traduit chacun en un message compréhensible et sans détail technique. Customers never see these codes: the plugin translates each into a plain message with no technical detail.

RéférenceReference

Pour les développeursFor developers

Points d'extension, routes, tables et tests. Extension points, routes, tables and tests.

FiltresFilters

// Conserver une commande expirée en attente plutôt que de l'échouer
add_filter( 'bcash_wc_expired_order_status', function () {
    return 'on-hold';
} );

// Rendre la ligne de frais taxable
add_filter( 'bcash_wc_fee_taxable', '__return_true' );

Routes RESTREST routes

Tables et métadonnéesTables and metadata

Deux tables sont créées : {prefix}bcash_attempts (une ligne par tentative de paiement) et {prefix}bcash_webhook_events (déduplication des notifications). Les contraintes d'unicité sur la clé d'idempotence, la référence marchande et la référence B-Cash constituent le garde-fou ultime contre le double débit. Two tables are created: {prefix}bcash_attempts (one row per payment attempt) and {prefix}bcash_webhook_events (notification de-duplication). Unique constraints on the idempotency key, merchant reference and B-Cash reference are the last line of defence against double charging.

Chaque commande porte également _bcash_payment_reference, _bcash_payment_status, _bcash_operator, _bcash_phone_masked, _bcash_customer_fee, _bcash_total_charged et _bcash_last_sync. Le plugin passe exclusivement par les méthodes WooCommerce : rien n'est écrit directement en base, la compatibilité HPOS est donc totale. Each order also carries _bcash_payment_reference, _bcash_payment_status, _bcash_operator, _bcash_phone_masked, _bcash_customer_fee, _bcash_total_charged and _bcash_last_sync. The plugin goes exclusively through WooCommerce CRUD: nothing is written directly to the database, so HPOS compatibility is complete.

TestsTests

Sept suites s'exécutent sans dépendance externe, directement contre le code de production : Seven suites run with no external dependency, directly against production code:

php tests/run-all.php

Elles couvrent la détection d'opérateur, la signature des requêtes, la monotonie des états, la vérification des notifications et leur rotation de secret, les décisions de reprise, le calcul des frais et l'idempotence. Après composer install : composer test, composer lint, composer analyse. They cover operator detection, request signing, state monotonicity, notification verification and secret rotation, retry decisions, fee computation and idempotency. After composer install: composer test, composer lint, composer analyse.

RéférenceReference

Sécurité et donnéesSecurity & data

Vos identifiantsYour credentials

Le secret ne quitte jamais votre serveur et n'est jamais transmis au navigateur. S'il est stocké en base, il l'est chiffré, avec une clé dérivée des sels uniques de votre installation WordPress, et l'option n'est pas chargée automatiquement à chaque page. Seuls les quatre derniers caractères sont réaffichables. Placer les identifiants dans wp-config.php reste la méthode la plus sûre. The secret never leaves your server and is never sent to the browser. If stored in the database it is encrypted, using a key derived from your WordPress installation's unique salts, and the option isn't autoloaded on every page. Only the last four characters can be redisplayed. Putting credentials in wp-config.php remains the safest route.

Le numéro du clientThe customer's number

Il est masqué partout où il s'affiche — administration, emails, journaux — sous la forme +2376••••••56. Le numéro complet n'est conservé que chiffré, et uniquement pour permettre une reprise après incident. Le plugin s'intègre aux outils d'export et d'effacement de données de WordPress. It is masked everywhere it is displayed — admin, emails, logs — as +2376••••••56. The full number is only kept encrypted, and only to allow recovery after an incident. The plugin hooks into WordPress's data export and erasure tools.

Texte pour votre politique de confidentialitéText for your privacy policy

Le plugin propose automatiquement ce paragraphe dans l'assistant de confidentialité de WordPress : The plugin automatically suggests this paragraph in WordPress's privacy policy guide:

À la désinstallationOn uninstall

Désactiver le plugin ne supprime aucune donnée. À la désinstallation, les secrets sont toujours effacés ; l'historique des paiements n'est supprimé que si vous l'avez explicitement demandé dans les réglages — c'est une donnée comptable. Deactivating the plugin deletes nothing. On uninstall, secrets are always wiped; payment history is removed only if you explicitly asked for it in the settings — it is accounting data.

RéférenceReference

Compatibilité et supportCompatibility & support

Avant de contacter le supportBefore contacting support

L'onglet Diagnostics produit un rapport prêt à copier : versions, état HPOS, HTTPS, tâches planifiées, version du registre de numérotation et nombre de tentatives bloquées. Il ne contient ni secret ni numéro complet, vous pouvez le transmettre tel quel. Ajoutez-y la référence de transaction concernée. The Diagnostics tab produces a ready-to-copy report: versions, HPOS state, HTTPS, scheduled tasks, numbering registry version and how many attempts are stuck. It contains no secret and no full phone number, so you can share it as is. Add the transaction reference in question.