Aller au contenu
Perly
CommencerCommencer gratuitement

Guides

WHMCS

Une passerelle de paiement pour WHMCS : vos clients règlent leurs factures en bitcoin ou en USDC/USDT directement sur votre portefeuille, et un webhook signé enregistre le paiement.

Voir en Markdown

Le module Perly Pay ajoute la crypto à vos factures WHMCS. Le client touche Pay with crypto ; le solde de la facture devient une facture Perly Pay, payée par-dessus la page WHMCS ou sur sa propre page ; un webhook signé enregistre le paiement dans WHMCS. WHMCS 8, PHP 8.1+ avec curl. Rien à installer avec Composer : le SDK PHP est inclus.

Perly Pay facture en USD ou en EUR. Pour les clients dans une autre devise, réglez Convert To For Processing de la passerelle sur USD ou EUR ; le paiement est quand même enregistré dans la devise de la facture. Sans cela, ces clients voient une note les invitant à choisir un autre moyen de paiement.

Installation

  1. 1

    Obtenez le zip

    Le module est en route vers le WHMCS Marketplace. D’ici là, écrivez-nous pour recevoir perly-pay-whmcs.zip.

  2. 2

    Téléversez

    Décompressez-le dans votre dossier WHMCS. Il ajoute modules/gateways/perlypay.php, modules/gateways/callback/perlypay.php et modules/gateways/perlypay/.

  3. 3

    Activez

    Configuration → Apps & Integrations → Payment Gateways (ou Setup → Payment Gateways), activez Perly Pay.

Réglages

RéglageValeur
Secret key (clé secrète)Depuis Dashboard → Developers → API keys. sk_test_… pour le mode test, sk_live_… pour l’argent réel.
Webhook signing secret (secret de signature)whsec_…, tiré du webhook que vous ajoutez pour ce WHMCS (ci-dessous).
Payment page (page de paiement)Overlay ouvre la caisse par-dessus la facture (pay.js). Redirect y envoie le client. Sur téléphone, c’est toujours la page elle-même.
Currencies (devises)USD et EUR, ou une seule des deux.
  1. 1

    Collez la clé

    Enregistrez, puis touchez Test connection dans le champ de la clé : il indique si la clé marche, son mode, et si le webhook de ce WHMCS existe dans Perly Pay.

  2. 2

    Ajoutez le webhook

    Dans Dashboard → Developers → Webhooks, ajoutez l’adresse indiquée dans les réglages, https://your-whmcs/modules/gateways/callback/perlypay.php, avec les événements de facture et de remboursement. Collez son secret et enregistrez.

  3. 3

    Autorisez l’overlay

    Dans Dashboard → Settings, ajoutez l’adresse de votre WHMCS à Sites that may embed the checkout. Sans cela, l’overlay propose d’ouvrir la caisse dans un nouvel onglet.

Test

Avec une clé sk_test_…, ouvrez une facture impayée dans l’espace client et touchez Pay with crypto. Payez-la avec des monnaies de test, ou depuis l’API — l’id de la facture figure sur la page de paiement :

bash
curl -X POST https://pay.perly.io/api/v1/invoices/inv_…/simulate \
  -H "Authorization: Bearer $PERLY_PAY_SECRET_KEY" -H "Content-Type: application/json" -d '{}'

En quelques secondes, la facture WHMCS passe à Paid. Billing → Gateway Log montre le réseau, le montant et un lien vers la transaction.

Comment les factures suivent les paiements

Dans Perly PayDans WHMCS
Payé et l’expéditeur contrôlé (invoice.fulfilled)Un paiement du solde facturé au client, dans la devise de la facture, sous l’id de paiement Perly Pay (pay_…). WHMCS marque la facture Paid et fait le reste comme d’habitude.
Vu, payé en partie, payé mais encore en contrôleUne ligne dans le Gateway Log. Pas de paiement.
Retenu pour vérificationUne ligne dans le Gateway Log avec la raison. Décidez dans Perly Pay.
Expiré ou annuléUne ligne dans le Gateway Log. Toucher à nouveau le bouton crée une nouvelle facture.
Remboursement ouvert, prêt, envoyé, confirméUne ligne dans le Gateway Log, avec quoi envoyer et où.

Toucher à nouveau le bouton réutilise la facture ouverte tant que le solde est le même. Chaque paiement est enregistré une seule fois, quel que soit le nombre d’arrivées du webhook, et seulement pour les factures créées par ce WHMCS.

Remboursements

Remboursez la transaction dans WHMCS comme d’habitude : le module ouvre un remboursement dans Perly Pay, dans la monnaie payée (la même part pour un remboursement partiel). Perly Pay demande une adresse au client par e-mail et la contrôle ; le Gateway Log indique ensuite quoi envoyer et où. Vous envoyez depuis votre portefeuille et collez l’id de transaction dans Perly Pay — Perly Pay ne détient jamais l’argent.

Passer en réel

  • Activez le mode réel dans Perly Pay et connectez les clés publiques de votre portefeuille.
  • Collez une clé sk_live_…. Les clés et webhooks réels sont distincts de ceux de test : ajoutez à nouveau l’adresse de retour en mode réel et collez son secret.
  • Ajoutez l’adresse https de votre WHMCS à Sites that may embed the checkout en mode réel.
  • Payez une petite facture réelle et remboursez-la.