Stripe

Où dans l'admin : Finance › Payment channels › Stripe (/payments/stripe). Commutateurs et frais : Finance › Payment channels › Fees & limits (/payments/fees).

Description

Stripe prend en charge les paiements par carte pour les recharges de portefeuille. Avec le même compte, vous pouvez également proposer Apple Pay, Google Pay, Link et Alipay, et permettre aux clients d'enregistrer une carte pour le rechargement automatique. Utilisez-le comme canal principal pour les clients internationaux.

Prérequis

Élément	Prérequis
Compte Stripe	Un compte Stripe capable d'accepter les paiements en USD. Alipay est facturé en JPY et doit être activé par Stripe sur votre compte.
Clés	Une clé secrète (sk_live_... ou sk_test_...) et une clé publiable (pk_live_... ou pk_test_...). Le formulaire n'accepte que les clés portant ces préfixes.
Réseau	Votre panneau doit être accessible en HTTPS depuis Internet (Stripe appelle le webhook) et doit pouvoir joindre api.stripe.com sur le port 443.
Domaine (portefeuilles uniquement)	Le domaine destiné aux clients doit desservir /.well-known/apple-developer-merchantid-domain-association — NexCMP s'en charge pour vous.
Dépendances	Aucune.

Comptes Stripe partagés

NexCMP traite uniquement les événements de webhook pour les paiements qu'il a créés lui-même, vous pouvez donc utiliser un compte Stripe qui dessert également une autre application.

Préparer l'infrastructure

Du côté de Stripe :

1. Connectez-vous au Stripe Dashboard. Activez ou désactivez Test mode selon que vous effectuez un essai ou passez en production. Les clés d'un mode ne fonctionnent jamais avec l'autre.
2. Ouvrez Developers › API keys. Copiez la Publishable key, puis révélez et copiez la Secret key. Gardez la clé secrète confidentielle.
3. (Optionnel) Ouvrez Settings › Payment methods et activez Alipay si vous souhaitez le proposer.
4. Vous n'avez pas besoin de créer le webhook manuellement — NexCMP peut le créer pour vous (voir l'étape 5 ci-dessous). Si vous préférez le faire manuellement, créez un point de terminaison dans Developers › Webhooks avec l'URL et les événements indiqués dans Webhook.

Connecter dans NexCMP

1. Ouvrez Finance › Payment channels › Stripe (/payments/stripe).
2. Dans la carte API keys, choisissez le Mode (live ou test), puis collez la Secret key et la Publishable key.
3. Cliquez sur Save. Les clés sont écrites dans un fichier de configuration sur le serveur que seul le compte de service NexCMP peut lire. Elles ne sont jamais renvoyées au navigateur ; par la suite, la page n'affiche que les 4 derniers caractères.
4. Cliquez sur Check. Une boîte de dialogue indique la connexion, le mode, le solde disponible et en attente, l'ID du compte, si les débits sont activés, si un webhook existe et si Alipay est disponible. Une ligne rouge indique qu'un élément nécessite votre attention.
5. Dans la carte Webhook, cliquez sur Create webhook et confirmez. NexCMP demande à Stripe de créer le point de terminaison avec chaque événement requis et remplit automatiquement le champ Webhook signing secret (whsec_...). L'URL préremplie dans le champ est https://<your-domain>/v1/billing/stripe/webhook, par exemple https://cloud.example.com/v1/billing/stripe/webhook.
6. Ouvrez Fees & limits (/payments/fees), laissez Card (Stripe) activé, définissez Stripe fee % et Stripe fixed fee (cents) selon votre tarif réel, puis cliquez sur Save channels & fees. Voir Payment channels.

Webhook

La bannière rouge "Missing webhook_secret" s'affiche jusqu'à ce qu'un secret de signature soit enregistré. Sans cela, les recharges Stripe ne sont pas enregistrées, même si Stripe a encaissé l'argent.

Élément	Valeur
URL	https://<your-domain>/v1/billing/stripe/webhook
Événements	checkout.session.completed, payment_intent.succeeded, payment_intent.payment_failed, charge.refunded, charge.dispute.created, charge.dispute.closed, radar.early_fraud_warning.created, refund.updated, refund.failed
Signature	En-tête Stripe Stripe-Signature, HMAC-SHA256, tolérance de 300 secondes. Les requêtes dotées d'une mauvaise signature reçoivent un code HTTP 400.
Idempotence	Chaque ID d'événement est stocké une seule fois ; une livraison répétée ne crédite jamais deux fois.

Si vous avez effectué une mise à niveau à partir d'une version qui enregistrait moins d'événements, cliquez à nouveau sur Create webhook — l'ancien point de terminaison est conservé, vous devez donc le supprimer manuellement dans le Stripe Dashboard par la suite.

Les lignes 24h events et Latest event de la carte Webhook indiquent si Stripe parvient à joindre le panneau. Les événements individuels sont répertoriés dans Payment channels › Gateway events (/payments/events, onglet Stripe), où chaque événement peut être consulté (Payload) ou rejoué (Replay).

Apple Pay, Google Pay et Link

1. Dans la carte Wallets (Apple Pay · Google Pay · Link) & Alipay, le champ Customer app Domain registered with Stripe est prérempli avec le nom d'hôte de votre site (par exemple cloud.example.com).
2. Cliquez sur Register / verify domain et confirmez. NexCMP enregistre le domaine dans les domaines de moyens de paiement de Stripe et demande à Stripe de le valider.
3. Le résultat affiche le statut de Apple Pay, Google Pay et Link. Apple Pay n'apparaît que lorsque le statut est active.
4. Dans Fees & limits, laissez Apple Pay · Google Pay · Link activé.

Apple Pay reste inactif

Apple Pay nécessite que le fichier d'association de domaine réponde par HTTP 200 sur votre domaine public. Si vous placez Cloudflare ou un autre proxy en amont, ne bloquez pas /.well-known/.

Alipay

Alipay est optionnel. Activez-le dans Stripe Dashboard › Settings › Payment methods, cliquez sur Check et attendez que la boîte de dialogue indique qu'Alipay est disponible, puis activez Alipay (Stripe, JPY display) dans Fees & limits. Définissez Alipay fee %, Alipay fixed fee, le taux ¥/USD (50–500) et le spread de change % (0–20). Mettez régulièrement à jour le taux ¥/USD ; la page avertit lorsqu'il date de plus de 7 jours.

Vérification

1. En mode test, connectez-vous au portail en tant que client test, ouvrez Billing, cliquez sur Deposit, choisissez Card et payez le minimum avec la carte de test Stripe 4242 4242 4242 4242 (n'importe quelle date future, n'importe quel CVC).
2. Le solde augmente en quelques secondes et le paiement apparaît sous Finance › Billing › Top-ups avec le statut Completed.
3. Ouvrez Payment channels › Gateway events › Stripe: vous devriez voir checkout.session.completed ou payment_intent.succeeded avec une heure de traitement.
4. De retour sur la page Stripe, 24h events est supérieur à 0.

Avant de passer en production, basculez Mode sur live, collez les clés de production et cliquez de nouveau sur Create webhook (les webhooks du mode test et du mode production sont distincts).

Limites et notes

• Montants et devise. Les portefeuilles sont en USD. Les paiements par carte, portefeuille et link sont facturés en USD ; Alipay est affiché au client en JPY et converti selon votre taux.
• Frais. Le frais réel de Stripe n'est pas récupéré automatiquement ; le pourcentage de frais que vous définissez détermine ce que voit le client et ce qui est crédité sur le portefeuille. Choisissez Customer pays top-up fee dans Fees & limits pour facturer les frais en sus.
• Cartes enregistrées. Lorsque le client coche Save card for auto top-up, la carte est stockée chez Stripe et non sur votre serveur. Voir Saved payment methods.
• Remboursements. Le remboursement sur la carte s'effectue en deux étapes : un administrateur crée une demande de remboursement pour un paiement complété (Finance › Billing › Top-ups, action de remboursement sur le paiement) puis l'approuve sous Finance › Payouts › Card refunds (/billing/payouts). Les remboursements Alipay sont asynchrones ; un échec (refund.failed) restitue le montant retenu au portefeuille.
• Litiges. Sur charge.dispute.created, NexCMP bloque le compte du client, suspend ses services prépayés (rien n'est supprimé) et envoie une alerte administrateur. Si vous gagnez (charge.dispute.closed), le montant est recrédité sur le portefeuille.
• Paiements en attente. Si un webhook n'arrive jamais, NexCMP vérifie de lui-même auprès de Stripe les paiements restés en attente pendant plus de 10 minutes et les finalise. Les paiements de plus de 7 jours sont ignorés.
• Les Resellers peuvent connecter leur propre compte Stripe (webhook https://<their-domain>/v1/billing/stripe/webhook/r/<id>) ; voir Resellers.

Dépannage

Symptôme	Cause	Solution
"La clé secrète doit commencer par sk_live_/sk_test_"	Mauvaise clé collée	Collez la clé secrète depuis Developers › API keys.
"La clé secrète ne correspond pas au mode live/test"	Mode et clé discordants	Faites correspondre le paramètre Mode avec le préfixe de la clé.
"La clé publiable doit commencer par pk_"	Clé incorrecte	Utilisez la clé publiable.
La vérification indique que la connexion a échoué	Clé incorrecte, clé révoquée ou le serveur ne peut pas joindre api.stripe.com	Recolez la clé ; testez avec curl -I https://api.stripe.com depuis le serveur.
Bannière rouge "Missing webhook_secret"	Le secret de signature n'est pas enregistré	Cliquez sur Create webhook ou collez le secret whsec_... depuis le tableau de bord Stripe, puis sur Save.
Paiement effectué mais le solde n'a pas changé	Webhook non délivré ou échec de la signature	Vérifiez que l'URL se termine par /v1/billing/stripe/webhook, que le secret correspond au point de terminaison et réexécutez l'événement dans Gateway events. Dans Stripe, ouvrez le point de terminaison et consultez les tentatives de livraison (une erreur HTTP 400 indique un mauvais secret de signature).
"Create webhook" échoue	L'URL n'est pas en HTTPS ou n'est pas accessible	Utilisez votre domaine public https://.
Statut Apple Pay inactif	Domaine non validé	Cliquez à nouveau sur Register / verify domain après que le fichier d'association de domaine a répondu 200.
Alipay non disponible dans la boîte de dialogue de vérification	Non activé sur Stripe	Activez-le dans le tableau de bord Stripe, puis cliquez sur Check.
Le client ne voit pas le formulaire de carte	Card (Stripe) est désactivé ou aucune clé secrète n'est définie	Activez-le dans Fees & limits et enregistrez les clés.