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. Entrez 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, entrez 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. 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 — Webhook key2.

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".

Ensuite, entrez 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 !). Ensuite, 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 définie sur USD. Pour utiliser une autre devise, définissez la valeur de la variable currency.

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

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

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

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 :

— Spécifiez d'abord 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.

Ensuite, affichez 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.

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 — 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'

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

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 facturé après 1 mois.

Exemple à copier :

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

Pour facturer le paiement de l'abonnement une fois tous les deux, trois ou quatre mois, transmettez 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, qui est 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 (rappel) n'est envoyée que pour le premier paiement récurrent !

Il n'y aura AUCUN rappel 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 frais supplémentaire ne sera facturé 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 optionnel)

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 sous la section "Coupons". ”coupons”.

Cliquer sur le bouton "Nouveau" ouvrira une page où vous devez 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 pouvez voir 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 transmettez l'identifiant de réduction de votre tableau de bord Stripe.

2. À un abonnement existant en utilisant 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 transmettant les paramètres stripe_subscription_id (ID d'abonnement) et coupon_id (ID de réduction du coupon). La réduction sera appliquée aux paiements d'abonnement suivants.

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 d'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 transmettant le paramètre stripe_subscription_id (ID d'abonnement).

Si l'opération réussit, la fonction renverra un message contenant l'ID d'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 transmettre 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 rappels indiquant une transaction réussie. Dans le système, ces rappels apparaissent comme des messages de l'utilisateur. Pour empêcher les utilisateurs de les envoyer manuellement, ils sont composés des 20 premiers caractères de la clé secrète suivis de _success, par exemple : sk_live_d35gky6d8ers_success

Ces rappels ne sont PAS visibles pour l'utilisateur — ils ne sont visibles que 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 à droite.

Ensuite, suivez les étapes de configuration décrites au début de ce guide. Entrez 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).