Stripe

Comment se connecter

Pour connecter le système de paiement Stripe, vous aurez besoin d'une clé API secrète et d'une clé de webhook.

La clé API secrète peut être copiée en allant dans Développeurs → Clés API et en copiant la clé secrète.

Étape 1. Allez dans Développeurs → Clés API :

Étape 2. Trouvez et copiez la clé secrète :

Ensuite, vous devez définir une URL de rappel. Cela permet au bot de recevoir les notifications de paiement.

Allez dans la section Webhooks et ajoutez l'URL du webhook.

Un formulaire apparaîtra.

Étape 3. Cliquez sur "+ ajouter une destination".

Étape 4. Sélectionnez les événements.

Étape 3. Sélectionnez le type "Point de terminaison Webhook".

Étape 4. Vérifiez le type de requête et cliquez sur "Continuer".

Étape 5. Saisissez un nom et spécifiez l'URL du point de terminaison.

Définissez l'URL sur : https://chatter.mavibot.ai/stripe_callback/result

Étape 6. Deux points de terminaison seront créés — vous pouvez vérifier les paramètres avant de les ajouter.

Étape 7. Cliquez sur le bouton "Ajouter des destinations". Les webhooks seront enregistrés.

Étape 8. Cliquez sur "Terminé".

Enregistrez et vous serez redirigé vers la page avec le webhook configuré.

Étape 9. Cliquez sur le webhook où vous avez sélectionné tous les événements.

Étape 10. Trouvez la clé de signature et enregistrez-la (vous en aurez besoin plus tard pour vous connecter à MaviBot).

Une fois que vous avez les clés, procédez à la connexion dans Mavibot.

Dans Mavibot, ouvrez la section "Acquiring" et sélectionnez Stripe.

Sur la page de connexion, saisissez les clés que vous avez obtenues.

Cliquez sur "Enregistrer les paramètres".

Terminé ! Vous avez connecté Stripe.

Comment connecter un rappel de statut de transaction

Pour recevoir un rappel supplémentaire, vous devez ajouter un deuxième webhook en plus de celui existant.

Définissez l'URL sur : https://chatter.mavibot.ai/stripe_callback/<api_key>/charge_status

et sélectionnez les événements suivants :

• charge.failed
• charge.pending
• charge.succeeded

Plus de détails sur chaque type de webhook :

1. charge.succeeded — contient des informations sur une transaction réussie (similaire au rappel de paiement réussi)
2. charge.pending — "transaction en cours", peut prendre jusqu'à 7 jours pour se terminer. Le webhook aura le format {10 premiers caractères}{type de webhook} Par exemple : sk_test_45LDPJLKT95d_charge.pending
3. charge.failed — "transaction échouée". Le webhook aura le format {10 premiers caractères}{type de webhook} Par exemple : sk_test_45LDPJLKT95d_charge.failed

Ajoutez la clé de webhook obtenue après l'enregistrement dans le champ Mavibot — Clé de webhook2.

stripe_invoice_id — l'identifiant de la transaction pour laquelle un rappel de paiement réussi n'a pas été reçu immédiatement après le paiement.

Comment configurer les taxes

Pour utiliser les taxes dans les paiements, vous devez d'abord les créer dans votre tableau de bord Stripe. Pour ce faire, tapez "tax rates" dans la barre de recherche :

Et cliquez sur "+ Ajouter des taux de taxe".

Saisissez ensuite le taux de taxe applicable.

Dans le menu qui s'ouvre, sélectionnez le type de taxe, la région à laquelle elle s'applique, le taux en pourcentage et si la taxe sera incluse dans le montant du paiement (Inclusive) ou ajoutée en sus (Exclusive).

Après avoir créé le taux de taxe, copiez son ID dans la variable stripe_tax_id avant de déclarer le montant du paiement.

Pour éviter les erreurs, il est recommandé de définir la variable stripe_tax_id sur une chaîne vide ("") après avoir reçu le lien — ainsi vous pouvez appliquer la taxe uniquement lorsque nécessaire.

Si cela est fait correctement, dans le cas d'un taux de taxe avec le paramètre exclusif, vous verrez ce qui suit :

Comment obtenir un lien de paiement

Pour générer un lien de paiement, définissez la valeur de la variable payment_sum (par exemple 150 ou 100.55 — utilisez un point, pas une virgule !). Après cela, la variable stripe_pay_url apparaîtra. Vous pouvez afficher cette variable sous forme de lien ou la placer sur un bouton avec le texte "Payer".

Le lien ressemble à ceci :

https://checkout.stripe.com/pay/cs_test_a17mskKFFRwEuo3WgBSAUjfk7xaZZIrct9B3Ds2AdODVq1I8aRiqYEBdrU#fidkdWxOYHwnPyd1blpxYHZxWjA0TGFsVzFPVmpmMzJAbVYzUkp1Y0lLYDVgfzR2Q0NxcWZBNUNnTnRSVVRJSGFobEB1UExSczRMMTc8PWRLMGBddl8xalxyPDRoUGhnZm9xXXZANDZyaF0wNTVBVExsPHZyfycpJ2N3amhWYHdzYHcnP3F3cGApJ2lkfGpwcVF8dWAnPyd2bGtiaWBabHFgaCcpJ2BrZGdpYFVpZGZgbWppYWB3dic%2FcXdwYHgl

Par défaut, la devise est USD. Pour utiliser une devise différente, définissez la valeur de la variable currency.

Vous pouvez également définir les variables optionnelles suivantes avant de définir la valeur payment_sum pour configurer le paiement.

Paramètres de la fonction	Description du paramètre
currency	devise de la commande. Les valeurs autorisées sont ici —https://stripe.com/docs/currencies
payment_description	description du paiement
stripe_tax_id	identifiant du taux de taxe configuré dans votre tableau de bord Stripe. Les instructions de configuration sont fournies dans la section "Comment configurer les taxes".
stripe_invoice_enable	indicateur pour activer la sauvegarde des factures (reçus). Définissez n'importe quelle valeur pour activer cette option — tous les documents pertinents seront disponibles dans votre tableau de bord Stripe.
stripe_locale	définir la langue de la page de paiement : en, de, etc. Toutes les options disponibles : https://stripe.com/docs/api/checkout/sessions/create#create_checkout_session-locale Si stripe_locale n'est pas défini, la langue du navigateur du client sera utilisée.
stripe_payment_method_type	méthode de paiement ; par défaut, paiement par carte. Peut être remplacé par d'autres méthodes de paiement disponibles dans Stripe. Les méthodes disponibles sont listées ci-dessous. Par exemple, stripe_payment_method_type = "customer_balance"
stripe_additional_payment_method_type	ajouter une méthode de paiement supplémentaire. Les méthodes disponibles sont listées ci-dessous. Par exemple, stripe_additional_payment_method_type = "sepa_debit"
coupon_id	identifiant du coupon de réduction
stripe_expired	délai d'expiration du lien de paiement. Spécifié en secondes. Minimum 30 minutes, maximum 24 heures. Par défaut 24 heures.
stripe_automatic_tax	activer le calcul et la collecte automatiques des taxes lors du paiement. Passez "1" pour activer. Pour plus de détails, reportez-vous aux articles Stripe.

Important ! Si vous utilisez à la fois les variables stripe_payment_method_type et stripe_additional_payment_method_type, les valeurs qu'elles contiennent doivent être différentes !

Liste des valeurs pour stripe_payment_method_type et stripe_additional_payment_method_type

card
acss_debit
affirm
afterpay_clearpay
alipay
au_becs_debit
bacs_debit
bancontact
blik
boleto
cashapp
customer_balance
eps
fpx
giropay
grabpay
ideal
klarna
konbini
link
oxxo
p24
paynow
paypal
pix
promptpay
sepa_debit
sofort
us_bank_account
wechat_pay zip

Pour plus de détails sur chaque méthode et les pays où elles sont disponibles, reportez-vous à la documentation Stripe

Exemple de génération de lien de paiement

Créons un lien de paiement pour 1000 AED (la devise par défaut est USD).

Remarque :

— D'abord, spécifiez les paramètres optionnels tels que first_name, payment_description, etc.

— Ensuite, attribuez la valeur à la variable payment_sum en dernier.

Les variables peuvent également être définies plus tôt dans la chaîne, pas nécessairement dans le même bloc — ceci n'est qu'un exemple.

Affichez ensuite la variable stripe_pay_url, qui contient le lien, à l'endroit souhaité — soit dans un bloc de message, soit sur un bouton :

Exemple 1. Afficher le lien de paiement directement dans un message :

Exemple 2. Ajouter le lien de paiement à un bouton.

Lorsque le bouton est cliqué ou que le lien est suivi, votre payeur sera redirigé vers la page de paiement.

L'exemple montre que les paramètres que nous avons spécifiés dans le calculateur dans les paramètres du bloc ont été appliqués : description de la commande, devise et montant.

Si vous transmettez le paramètre de taux de taxe (stripe_tax_id) dans le bloc.

Le taux de taxe sera également affiché dans le formulaire de paiement.

Exemple de code à copier

payment_description = "test payment"

currency = 'AED'

stripe_tax_id = 'enter_your_stripe_id_tax'

payment_sum = 1000

Où trouver l'ID de taxe.

Comment configurer les paiements récurrents

Pour les paiements récurrents (abonnements), déclarez la variable stripe_subscription avant la variable payment_sum et attribuez-lui le nom de l'abonnement.

Vous pouvez également ajouter les variables suivantes : interval — la durée de l'intervalle d'abonnement. Passez 'day' pour les jours, 'week' pour les semaines, 'month' pour les mois ou 'year' pour les années. Si la variable n'est pas définie, 'month' sera utilisé par défaut.

Important !

La durée d'un cycle d'abonnement ne peut pas dépasser 1 an (pour le paramètre 'year'), 12 mois (pour le paramètre 'month') ou 52 semaines (pour le paramètre 'week').

interval_count — le nombre d'intervalles spécifiés : combien de jours, semaines ou mois sont inclus dans l'abonnement pour le montant donné. Par défaut, 1.

stripe_payment_method_type — la méthode de paiement ; par défaut, paiement par carte. Peut être remplacé par d'autres méthodes de paiement disponibles dans Stripe. Les méthodes disponibles sont listées ci-dessous.

Par exemple, stripe_payment_method_type = 'customer_balance'

stripe_additional_payment_method_type — ajoute un moyen de paiement supplémentaire. Les méthodes disponibles sont listées ci-dessous.

Par exemple, stripe_additional_payment_method_type = 'sepa_debit'

Important ! Si vous utilisez à la fois les variables stripe_payment_method_type et stripe_additional_payment_method_type, les valeurs qu'elles contiennent DOIVENT ÊTRE DIFFÉRENTES !

Liste des valeurs pour stripe_payment_method_type et stripe_additional_payment_method_type :

card
acss_debit
affirm
afterpay_clearpay
alipay
au_becs_debit
bacs_debit
bancontact
blik
boleto
cashapp
customer_balance
eps
fpx
giropay
grabpay
ideal
klarna
konbini
link
oxxo
p24
paynow
paypal
pix
promptpay
sepa_debit
sofort
us_bank_account
wechat_pay zip

Pour plus de détails sur chaque méthode et les pays où elles sont disponibles, consultez la documentation Stripe.

Important !

La durée d'un cycle d'abonnement ne peut pas dépasser 1 an (pour le paramètre 'year'), 12 mois (pour le paramètre 'month') ou 52 semaines (pour le paramètre 'week').

Dans cet exemple, un abonnement nommé 'My_subscription' sera créé avec un prix de 1000 AED par mois, et un paiement récurrent du même montant sera prélevé après 1 mois.

Copier l'exemple :

stripe_subscription = 'My_subscription' interval = 'month' payment_sum = 90

Pour prélever le paiement de l'abonnement une fois tous les deux, trois ou quatre mois, passez le paramètre interval_count :

stripe_subscription = 'My_subscription'

interval = 'month'

interval_count = 3

payment_sum = 90

Pour modifier l'intervalle de paiement de l'abonnement de mensuel à hebdomadaire, passez le mot week dans le paramètre interval :

stripe_subscription = 'My_subscription'

interval = 'week'

interval_count = 3

payment_sum = 90

Après le paiement, les variables de transaction du client incluront stripe_subscription_id, nécessaire pour configurer l'annulation de l'abonnement, et stripe_customer_id, qui peut ensuite être utilisé pour vérifier le statut de l'abonnement.

La notification (callback) n'est envoyée que pour le premier paiement récurrent !

Il n'y aura AUCUN callback pour les paiements suivants. Le suivi se fait via la fonction et stripe_customer_id.

Paramètres pour revenir aux paiements réguliers

Pour revenir aux paiements réguliers, attribuez une chaîne vide à la variable d'abonnement : stripe_subscription = ''. Dans ce cas, les variables interval et interval_count n'affecteront pas la génération du lien.

Paramètres pour annuler un abonnement

Pour annuler un abonnement dans le calculateur, utilisez la méthode stripe_remove_subscription(stripe_subscription_id), où stripe_subscription_id est l'identifiant enregistré dans les variables de transaction après le paiement.

Cela maintiendra l'abonnement payé actif jusqu'à la fin de la période de facturation en cours, mais aucun prélèvement supplémentaire n'aura lieu, et l'abonnement sera annulé une fois la période expirée.

answer = stripe_remove_subscription('#{stripe_subscription_id}')

stripe_remove_subscription — en cas de succès, renvoie une réponse avec des informations sur la date jusqu'à laquelle l'abonnement annulé restera actif.

Dans cet exemple, le résultat de la fonction sera stocké dans la variable answer, vous permettant de vérifier le résultat.

Vérification du statut de l'abonnement

stripe_check_subscription(subscription_id, customer_id), où

stripe_subscription_id — identifiant de l'abonnement stripe_customer_id — identifiant du client dans Stripe (paramètre facultatif)

Comment créer un coupon et obtenir un ID de réduction

Pour obtenir un identifiant de réduction, créez un coupon dans votre tableau de bord, dans la section « Coupons ». »coupons ».

En cliquant sur le bouton « Nouveau », une page s'ouvrira où vous devrez spécifier :

1. Nom — le nom de la réduction ;
2. ID — l'identifiant, généré automatiquement ;
3. Type — le type de réduction : pourcentage ou montant fixe ;
4. Durée — la durée de la réduction (unique ou continue, par exemple pour les abonnements) et d'autres paramètres.

Le coupon de réduction apparaîtra dans le « Catalogue de produits » sous la section « Coupons », et vous pourrez consulter l'ID de réduction en ouvrant le menu du coupon.

Cliquez sur le coupon pour copier l'ID du coupon.

Comment appliquer une réduction à une commande

1. Lors de la génération d'un lien de paiement (fonctionne à la fois pour les abonnements et les paiements uniques).

Dans le calculateur de bloc, avant de déclarer la variable payment_sum, définissez la variable coupon_id et passez l'identifiant de réduction depuis votre tableau de bord Stripe.

2. À un abonnement existant à l'aide de la fonction stripe_add_subscription_discount.

Définissez les conditions de déclenchement du bloc et appelez la fonction spécifiée dans le calculateur, en passant les paramètres stripe_subscription_id (ID de l'abonnement) et coupon_id (ID du coupon de réduction). La réduction sera appliquée aux paiements d'abonnement suivants.

Exemple de code à copier

stripe_subscription = 'test subscription'

interval = 'month'

payment_description = 'test payment'

currency = 'AED'

coupon_id = 'BD8VIwi8' stripe_add_subscription_discount(stripe_subscription_id, coupon_id)

stripe_tax_id = 'Qfkiwiki29jcs'

payment_sum = 90

Si la réduction est appliquée avec succès, la fonction renverra un message avec l'ID de l'abonnement, le type de réduction, le montant ou le pourcentage, et la date d'expiration.

Comment supprimer ou modifier une réduction pour un abonnement

Une réduction attachée à un abonnement peut être supprimée ou remplacée par une autre réduction.

Pour arrêter une réduction, définissez les conditions de déclenchement du bloc et appelez la fonction stripe_remove_subscription_discount dans le calculateur, en passant le paramètre stripe_subscription_id (ID de l'abonnement).

Si l'opération réussit, la fonction renverra un message contenant l'ID de l'abonnement et la date d'annulation de la réduction.

Le remplacement d'une réduction, comme l'ajout d'une nouvelle, se fait à l'aide de la fonction stripe_add_subscription_discount. Assurez-vous de passer les paramètres stripe_subscription_id et coupon_id. Une requête réussie mettra à jour le coupon attaché à l'abonnement et renverra un message avec les détails mis à jour.

Comment gérer le résultat

Après un paiement réussi, le bot recevra des callbacks qui indiquent une transaction réussie. Dans le système, ces callbacks apparaissent comme des messages de l'utilisateur. Pour empêcher les utilisateurs de les envoyer manuellement, ils sont constitués des 20 premiers caractères de la clé secrète suivis de _success, par exemple : sk_live_d35gky6d8ers_success

Ces callbacks NE sont PAS visibles pour l'utilisateur — ils sont uniquement visibles pour l'opérateur.

Le type de comparaison doit être défini sur « Correspondance exacte ».

Après un paiement réussi, la variable stripe_payment_completed est également définie sur True.

Par exemple, vous pouvez gérer un paiement réussi à l'aide d'un bloc conditionnel et afficher le message approprié à l'utilisateur.

Une fois le paiement terminé, la variable stripe_callback_data sera ajoutée aux données du client, contenant la réponse du système de paiement pour la transaction terminée. Les données requises peuvent être extraites du dictionnaire résultant à l'aide de la méthode get.

Pour traiter un paiement répété, vous devez d'abord réinitialiser payment_sum et le lien précédemment généré, puis seulement réattribuer la variable payment_sum pour obtenir un nouveau lien. Vous pouvez utiliser la valeur précédente.

Comment tester les paiements

Pour tester l'intégration, vous pouvez utiliser la clé secrète de l'environnement de test. Pour ce faire, passez à l'environnement de test dans le tableau de bord Stripe à l'aide du menu de droite.

Suivez ensuite les étapes de configuration décrites au début de ce guide. Saisissez la clé secrète de test et ajoutez l'URL du webhook dans l'environnement de test.

Pour les tests, utilisez un numéro de carte de paiement de test (vous pouvez trouver le numéro de carte pour votre pays sur le site officiel de Stripe).