HandyPay

Guide d'intégration

Paiement WHMCS

Connectez WHMCS à HandyPay pour des factures ponctuelles et des abonnements récurrents tout en gardant le test et la facturation en direct complètement séparés.

Liste de contrôle de configuration

  1. Créez une clé API dans le portail marchand. Commencez par un hp_test_ La clé.
  2. Conservez la clé dans la configuration WHMCS gateway. Ne le placez jamais dans JavaScript côté client ou dans un modèle public.
  3. Utilisation https://api.handypay.me/api/v1 comme la base de API URL.
  4. Enregistrer un paramètre webhook qui peut recevoir des événements de paiement et de cycle de vie d'abonnement.
  5. Exécuter une facture de test complète avant de remplacer la clé par une hp_live_ La clé.

Essai en toute sécurité

Les clés de test utilisent un compte de test dédié. Produits, clients, paiements, abonnements et webhooks créés avec une clé de test ne peuvent pas apparaître dans l'activité en direct.

Vérifier l'activité d'essai
curl https://api.handypay.me/api/v1/test-payments \
  -H "Authorization: Bearer hp_test_your_api_key_here"
bash

La même activité est visible sous Test Mode dans le portail marchand HandyPay.

Comportement de la vérification

Créez une session de paiement hébergée pour chaque facture WHMCS. HandyPay affiche les méthodes de paiement éligibles pour le marchand, la monnaie, le client et l'appareil. La carte de paiement reste disponible lorsqu'une méthode supplémentaire n'est pas admissible.

Créer une facture de paiement
curl -X POST https://api.handypay.me/api/v1/payment-sessions \
  -H "Authorization: Bearer hp_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [{
      "amount": 4999,
      "currency": "usd",
      "name": "WHMCS invoice #1042",
      "quantity": 1
    }],
    "customer_email": "buyer@example.com",
    "success_url": "https://billing.example.com/payment-complete",
    "cancel_url": "https://billing.example.com/viewinvoice.php?id=1042",
    "metadata": { "whmcs_invoice_id": "1042" }
            }'
bash

Google Pay est déjà activé. Il n’y a aucun champ Google Pay à ajouter au module. Stripe Checkout l’affiche automatiquement lorsque le client et le paiement sont admissibles.

  • Effectuez le test dans un navigateur pris en charge, sur un appareil compatible doté d’une carte active dans Google Wallet.
  • N’utilisez pas de fenêtre privée ou de navigation incognito et autorisez le navigateur à vérifier les moyens de paiement enregistrés.
  • Google Pay est signalé comme un portefeuille de carte ; la session Checkout et le flux de webhooks existants continuent donc de rapprocher la facture WHMCS.
Tester les moyens de paiement sur ce navigateur →

Abonnements et sièges

Créez un produit d'abonnement une fois, puis créez une session d'abonnement pour le client. Jeu quantity pour la facturation par siège. Les abonnements actifs peuvent être mis à jour sans les remplacer.

Changer le nombre de sièges actifs
curl -X PATCH https://api.handypay.me/api/v1/subscriptions/sub_123/quantity \
  -H "Authorization: Bearer hp_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 8,
    "proration_behavior": "create_prorations"
  }'
bash
  • create_prorations place le réglage sur la facture suivante.
  • always_invoice facture immédiatement le rajustement.
  • none change le nombre de sièges sans réglage proportionnel.

Webhooks

Enregistrez le callback URL WHMCS avec le même mode de clé utilisé par la caisse. Un paramètre de test ne reçoit que des événements de test, et un paramètre de vie ne reçoit que des événements de l'ordre de l'événement.

Enregistrer un test webhook
curl -X POST https://api.handypay.me/api/v1/webhook-endpoints \
  -H "Authorization: Bearer hp_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://billing.example.com/modules/gateways/callback/handypay.php",
    "events": [
      "payment_intent.succeeded",
      "payment_intent.payment_failed",
      "customer.subscription.updated",
      "customer.subscription.deleted"
    ]
  }'
bash

Dépannage

Google Pay ne s’affiche pas : vérifiez que Google Wallet contient une carte active, utilisez un navigateur et un appareil pris en charge hors navigation privée et autorisez le navigateur à vérifier les moyens de paiement enregistrés. Stripe peut encore masquer un portefeuille pour une région ou une transaction non prise en charge ; la carte reste la solution de repli prise en charge.

Un paiement d'essai est manquant: confirmer la demande utilisée hp_test_ clé, puis vérifier l'espace de travail du mode test portail ou GET /v1/test-payments.

WHMCS ne met pas à jour: confirmer le callback URL est public HTTPS, vérifier la signature webhook contre le corps de la demande brute, et de retourner une réponse 2xx réussie seulement après la mise à jour de la facture réussit.