Libre-service de facturation Stripe pour les clients connectés

Si vous facturez vos propres clients avec Stripe, votre agent peut répondre à leurs questions de facturation : il montre à un client connecté ses factures récentes et son abonnement, et lui donne un lien vers le portail client de Stripe, où il peut changer d'offre ou de moyen de paiement, ou résilier. L'agent ne modifie jamais rien lui-même dans Stripe. Chaque modification se fait dans le portail de Stripe.

Cela utilise votre propre compte Stripe, connecté avec une clé restreinte que vous créez. Cela n'a rien à voir avec votre abonnement intoCHAT.

Avant de commencer

Il vous faut :

• La vérification d'identité mise en place sur votre site, avec le secret d'identité de l'agent sur votre serveur.
• Le portail client configuré dans Stripe : dans votre Dashboard Stripe, ouvrez Settings, Billing, Customer portal, choisissez ce que les clients peuvent y faire (par exemple mettre à jour leurs moyens de paiement, changer d'offre ou résilier), puis enregistrez. Faites-le en mode live et, si vous testez avec une clé de test, en mode test également.

Créer une clé restreinte

Une clé restreinte ne peut faire que ce que vous lui autorisez. intoCHAT refuse une clé secrète complète (sk_…).

1. Dans votre Dashboard Stripe, ouvrez Developers, API keys, et cliquez sur Create restricted key.
2. Donnez-lui un nom, par exemple « intoCHAT agent ».
3. Définissez ces autorisations et laissez tout le reste sur None :

1. Facultatif : réglez aussi Products sur Read. L'agent désigne alors l'offre par le nom de son produit ; sans cela, il utilise le surnom du prix, ou aucun nom.
2. Cliquez sur Create key et copiez-la. Elle commence par rk_live_, ou par rk_test_ en mode test.

Customer portal: Write permet à intoCHAT d'ouvrir une session du portail pour un client. Cela ne permet pas à intoCHAT de modifier lui-même les abonnements ou les moyens de paiement.

Connecter Stripe

1. Ouvrez votre agent et allez dans l'onglet Actions. La carte Stripe billing se trouve sous Orders.
2. Collez la clé dans Restricted key et cliquez sur Test and connect.

intoCHAT vérifie la clé en lisant l'ID d'un client, d'une facture et d'un abonnement, et vérifie si un portail client est configuré. Aucune donnée client n'est affichée. S'il manque une autorisation, la carte la nomme. Si le portail n'est pas encore configuré, la carte se connecte et vous avertit. Vous pouvez vérifier des clés jusqu'à 10 fois en 10 minutes.

La clé est stockée chiffrée et ne s'affiche plus jamais. La carte affiche ses quatre derniers caractères, s'il s'agit d'une clé live ou de test, et le nom de votre compte Stripe quand la clé peut le lire.

• Test connection effectue la même vérification avec la clé enregistrée.
• Replace key connecte avec une nouvelle clé. Si la carte indique que la clé enregistrée ne peut plus être lue, le bouton s'intitule Reconnect.
• Disconnect supprime la clé enregistrée dans intoCHAT. Pour révoquer la clé elle-même, supprimez-la aussi dans votre Dashboard Stripe.

Connecter, tester et déconnecter nécessitent le rôle Admin ou Owner. Ces opérations apparaissent dans le journal d'audit sous Integration connected et Integration disconnected. Transférer l'agent vers un autre compte déconnecte Stripe.

Indiquer à intoCHAT quel client est un visiteur

La vérification d'identité ne signe que l'ID d'utilisateur du visiteur. L'e-mail et les métadonnées que votre page transmet à côté pourraient être modifiés par un visiteur connecté dans son propre navigateur. Avant d'afficher la moindre donnée de facturation, intoCHAT a donc besoin du client Stripe, ou de l'e-mail, signé par votre serveur pour cet ID d'utilisateur, avec le même secret d'identité.

Transmettez l'une de ces valeurs dans les metadata de IntoChat.identify :

intoCHAT trouve le client ainsi :

1. Avec un stripe_customer_id et un stripe_customer_hash valides, il utilise ce client, s'il existe et n'a pas été supprimé. Rien d'autre n'est essayé.
2. Sinon, avec un email_hash valide, il cherche les clients Stripe ayant exactement cet e-mail (Stripe compare les e-mails tels qu'ils sont écrits). Il n'utilise le client que si un seul correspond.
3. Sinon, il ne trouve rien. L'agent indique au visiteur qu'il n'a pas trouvé de compte de facturation pour son identifiant de connexion et lui demande de vous contacter.

Transmettre l'ID client est le choix fiable. L'e-mail ne fonctionne que tant que l'e-mail de chaque client est unique dans votre compte Stripe.

Node.js :

import { createHmac } from "node:crypto";

const secret = process.env.INTOCHAT_IDENTITY_SECRET;
const sign = (text) => createHmac("sha256", secret).update(text).digest("hex");

const userId = String(user.id);
const identity = {
  userId,
  userHash: sign(userId),
  email: user.email,
  metadata: {
    stripe_customer_id: user.stripeCustomerId,
    stripe_customer_hash: sign(`${userId}:${user.stripeCustomerId}`),
  },
};

PHP :

<?php
$secret = getenv('INTOCHAT_IDENTITY_SECRET');
$userId = (string) $user->id;
$identity = [
    'userId' => $userId,
    'userHash' => hash_hmac('sha256', $userId, $secret),
    'metadata' => [
        'stripe_customer_id' => $user->stripe_customer_id,
        'stripe_customer_hash' => hash_hmac('sha256', $userId . ':' . $user->stripe_customer_id, $secret),
    ],
];

Transmettez le résultat à IntoChat.identify sur la page, comme décrit dans Vérification d'identité. Les métadonnées comptent dans les limites d'identify de 20 clés et 2 Ko.

Ce que les visiteurs peuvent faire

Un visiteur connecté peut demander à l'agent :

• Ses factures. L'agent voit jusqu'à 10 factures récentes, les plus récentes en premier, et peut indiquer pour chacune la date, le numéro, le montant et la devise, le statut, ainsi que les liens vers la page de la facture et son PDF. Les factures en brouillon ne sont pas affichées.
• Son abonnement. L'agent voit, pour chaque abonnement en cours, le nom de l'offre, le statut, la fin de la période en cours (la date de renouvellement, ou la date de fin si une résiliation est programmée) et s'il se termine à la fin de la période.
• À modifier ou résilier quelque chose. L'agent lui ouvre le portail client de Stripe : un bouton Manage billing apparaît sous sa réponse. Le lien fonctionne pendant peu de temps ; s'il expire, le visiteur peut le redemander. Dans le portail, il peut faire ce que vous avez autorisé dans les réglages de votre portail, comme changer d'offre ou de moyen de paiement, mettre à jour ses informations de facturation ou résilier. Une fois qu'il a terminé, le lien de retour du portail le ramène sur le site où se trouve le chat (son adresse sans le chemin), si celui-ci utilise https:// et fait partie de vos domaines autorisés quand vous en avez défini. Sinon, Stripe utilise le lien de retour par défaut des réglages de votre portail, si vous en avez défini un.

Un visiteur qui n'est pas connecté reçoit un court message lui demandant de se connecter d'abord sur votre site, dans la langue du chat. L'agent ne lui demande ni e-mail, ni numéro de client, ni coordonnées bancaires.

L'agent ne peut pas lui-même résilier un abonnement, changer d'offre, rembourser un paiement ni modifier un moyen de paiement. Pour tout cela, il ouvre le portail client.

Les consultations de facturation nécessitent une conversation enregistrée : elles ne sont donc pas proposées dans un chat temporaire. Dans le Playground, une identité de test fonctionne comme une vraie : elle nécessite donc aussi les métadonnées signées ci-dessus ; les consultations y sont de vraies consultations dans votre compte Stripe.

Ce que voit l'agent

De Stripe, l'agent ne reçoit que les champs listés sous Ce que les visiteurs peuvent faire. Il ne reçoit jamais l'ID client, l'adresse e-mail, le nom, l'adresse ou le numéro de téléphone du client, les coordonnées de carte ou bancaires, les numéros fiscaux ni les lignes des factures. intoCHAT copie un par un les champs qu'il transmet : rien d'autre ne parvient à l'agent.

Dans le « Why this answer » de la conversation, une consultation apparaît sous Billing: invoices, Billing: subscription ou Billing: customer portal.

Journal des accès

intoCHAT consigne chaque consultation de facturation et conserve le journal pendant 90 jours. Ouvrez Recent billing lookups dans la carte Stripe billing pour voir les 25 dernières entrées, ou cliquez sur Export CSV pour les obtenir toutes. Tous les membres de votre équipe peuvent le consulter.

Chaque entrée indique l'heure, ce qui a été lu (les factures, l'abonnement, un lien vers le portail client, ou un test de connexion), l'ID client Stripe et s'il a été trouvé grâce à l'ID client signé ou à l'e-mail signé, le résultat, et l'auteur : Visitor, ou la personne de votre compte qui a testé ou connecté Stripe. Le journal ne contient jamais le contenu des factures, les montants, les e-mails ni les coordonnées de carte.

Les résultats vous aident à vérifier votre configuration :

• No signed customer ID or email : le visiteur était connecté, mais votre page n'a pas transmis de stripe_customer_hash ou d'email_hash valide.
• No customer found : la signature était valide, mais le client n'existe pas, a été supprimé, ou aucun client n'a cet e-mail.
• Several customers with this email : plusieurs clients Stripe ont cet e-mail, donc rien n'a été affiché. Transmettez plutôt l'ID client.
• Stripe unavailable : Stripe n'a pas pu être joint, ou la clé a cessé de fonctionner. Lancez Test connection.

Limites

• Un compte Stripe par agent.
• L'agent se contente de lire les données de facturation et d'ouvrir le portail client. Ce qu'un client peut y modifier est déterminé par les réglages de votre portail dans Stripe.
• Jusqu'à 10 factures et 3 abonnements en cours par consultation.
• Après un passage à une offre inférieure à Pro, la clé reste enregistrée, mais l'agent cesse de l'utiliser jusqu'à ce que vous repassiez à une offre supérieure.

Étapes suivantes

• Connectez vos visiteurs : Vérification d'identité.
• Répondez aussi aux questions sur les commandes de votre boutique : Statut des commandes et retours.