Comment se connecter

Pour connecter le système de paiement bePaid, vous aurez besoin d'un Store ID, d'une clé secrète et d'une clé publique. Une fois ces informations d'identification reçues, accédez aux paramètres du système de paiement dans MaviBot.

Pour obtenir le Store ID, la clé secrète et la clé publique, contactez le support technique de bePaid.

Dans MaviBot, ouvrez la section Acquiring, sélectionnez bePaid et saisissez les informations d'identification que vous avez reçues.

Remarque : Le dernier champ est un commutateur qui sélectionne le point de terminaison API en fonction du pays d'utilisation : Biélorussie ou Russie.

Comment générer un lien de paiement

Pour générer un lien de paiement, attribuez une valeur à la variable payment_sum (par exemple : 150 ou 100.55 ; utilisez un point comme séparateur décimal).

Une fois la variable payment_sum définie, la variable bepaid_pay_url est créée automatiquement. Vous pouvez afficher cette variable sous forme de lien dans un message ou l'utiliser dans un bouton avec le texte "Payer".

Paramètre de la fonction	Description	Plus d'informations
currency	Monnaie de paiement au format ISO 4217.	Par exemple : USD
language	Langue de la page de paiement. Par défaut : `en`.	Valeurs autorisées : • `en` — Anglais • `es` — Espagnol • `tr` — Turc • `de` — Allemand • `it` — Italien • `ru` — Russe • `zh` — Chinois • `fr` — Français • `da` — Danois • `sv` — Suédois • `no` — Norvégien • `fi` — Finnois • `pl` — Polonais • `ja` — Japonais • `uk` — Ukrainien • `be` — Biélorusse • `ka` — Géorgien • `ro` — Roumain
payment_description	Description du paiement.	—
link_expired	Expiration du lien de paiement. Définissez la date d'expiration au format `jj.mm.aaaa` (par exemple : `25.06.2025`). Par défaut, le paiement doit être effectué dans les 24 heures.	Vous pouvez également utiliser le champ Assign Variables on Redirect : • `link_expired = current_date + 2` — le lien sera valide pendant 2 jours jusqu'à 00:00. • Vous pouvez spécifier une date et une heure d'expiration exactes au format `jj.mm.aaaa hh:mm` (par exemple : `25.06.2025 12:23`). Des variables standard peuvent également être utilisées. Exemple pour un lien valide 30 minutes : `python\ntime = current_time + 30\nlink_expired = "#{current_date} #{time}"\n`
russian_host	Indicateur pour une boutique enregistrée sur l'hôte bePaid russe. Définissez ce paramètre sur `1` si votre boutique est enregistrée sur bepaid.tech.	Pour passer à l'hôte biélorusse, définissez ce paramètre sur `""` (valeur vide).
test_payments	Active les paiements de test. Attribuez n'importe quelle valeur à cette variable avant de créer le lien de paiement.	—
bepaid_attempts	Spécifie le nombre de tentatives de paiement. Par défaut, 1 tentative est autorisée.	—
customer_data	Un objet JSON contenant le prénom, le nom et l'email du payeur. Ces informations sont nécessaires pour envoyer le reçu de paiement et peuvent être modifiées sur la page de paiement.	Le paramètre doit être passé sous forme d'objet au format JSON. Exemple : `python\ncustomer_data = {\n \"first_name\": \"Sam\",\n \"last_name\": \"Smith\",\n \"email\": \"[email protected]\"\n}\n`
bepaid_contract (conditionnellement requis)	Objet du paiement pour les paiements par jeton.	Valeurs autorisées : • `recurring` — pour les paiements récurrents avec un calendrier fixe. • `card_on_file` — pour les paiements uniques ou irréguliers, par exemple, facturer le client après la fourniture d'un service.

Exemple de lien de paiement :

https://checkout.bepaid.by/widget/hpp.html?token=a05eabd3f9368725efbc175614c7d469da08f198cc51916b07fb75e53f9a3e1a

Avant d'attribuer une valeur à payment_sum, vous pouvez définir des variables optionnelles supplémentaires pour personnaliser le paiement.

Par défaut, la monnaie de paiement est le rouble biélorusse (BYN). Si vous souhaitez utiliser une autre monnaie, attribuez une valeur à la variable currency.

Après la fin du paiement, la variable bepaid_callback_data est ajoutée au client. Elle contient la réponse du système de paiement pour la transaction effectuée.

Vous pouvez récupérer les valeurs requises de ce dictionnaire à l'aide de la fonction get().

Comment tester les paiements

Pour effectuer un paiement de test, attribuez n'importe quelle valeur à la variable test_payments avant de définir la variable payment_sum.

Important : Supprimez la variable test_payments avant de passer votre bot en mode live.

Cartes de test

Numéro de carte	Résultat
`4200000000000000`	Paiement réussi
`4005550000000019`	Paiement échoué

Exemple de génération d'un lien de paiement

L'exemple suivant génère un lien de paiement pour 100 roubles biélorusses (monnaie par défaut).

Remarque : Attribuez d'abord toutes les variables de configuration supplémentaires, puis attribuez la valeur à payment_sum. Ces variables peuvent également être attribuées plus tôt dans votre flux de travail — elles ne doivent pas nécessairement se trouver dans le même bloc.

Enfin, affichez la variable bepaid_pay_url là où vous le souhaitez. Elle contient le lien de paiement généré.

Gestion des abonnements

L'intégration bePaid vous permet de créer des abonnements pour vos clients.

Avant d'utiliser cette fonctionnalité dans MaviBot, créez un plan d'abonnement dans votre compte bePaid.

Si les sections Plans et Abonnements ne sont pas disponibles dans votre compte, contactez votre gestionnaire de compte.

Création d'un abonnement et génération d'un lien de paiement

Utilisez la fonction get_bepaid_subscription_url et transmettez le paramètre plan_id.

La fonction crée un abonnement et renvoie un lien de paiement.

Envoyez le lien généré au client et attendez que le paiement soit effectué.

Après un paiement réussi :

l'abonnement est activé ;
l'affaire reçoit les variables :
- bepaid_subscription_id ;
- bepaid_subscription_status ;
un callback est envoyé au bot (voir Comment gérer le résultat).

Récupération des informations d'abonnement

Pour récupérer les informations actuelles de l'abonnement, utilisez la fonction get_bepaid_subscription_info.

Transmettez le paramètre subscription_id. Sa valeur peut être extraite de la variable bepaid_subscription_id.

Annulation d'un abonnement

Pour annuler un abonnement, utilisez la fonction cancel_bepaid_subscription.

La fonction accepte un seul paramètre :

subscription_id — la valeur peut être extraite de la variable bepaid_subscription_id.

Après une annulation réussie :

la variable bepaid_subscription_status est définie sur "canceled" ;
un callback est envoyé au bot (voir Comment gérer le résultat).

Statuts d'abonnement

Statut	Description
trial	Abonnement période d'essai actif ou annulé.
active	Abonnement actif avec paiement effectué à temps.
failed	Abonnement échoué. bePaid n'a pas pu traiter le prochain paiement.
error	Une erreur s'est produite lors de la tentative de traitement du paiement par bePaid.
canceled	L'abonnement a été annulé et n'est plus actif.

Paiements récurrents

Vous pouvez également configurer des paiements récurrents sans créer de plan d'abonnement dans votre compte bePaid.

Pour ce faire, vous avez besoin du jeton de carte du client.

Obtention d'un jeton de carte

Pour obtenir le jeton de carte du client, le client doit effectuer un paiement initial en utilisant un lien de paiement généré avec la variable payment_sum.

Avant d'attribuer une valeur à payment_sum, définissez la variable bepaid_contract pour définir l'objectif des futurs paiements par jeton.

Valeurs prises en charge :

recurring — pour les paiements récurrents avec un calendrier prédéfini.
card_on_file — pour les paiements uniques ou irréguliers, par exemple, facturer le client après la fourniture d'un service.

Remarque : L'option card_on_file n'est pas prise en charge par toutes les banques acquéreuses. Contactez votre gestionnaire de compte si vous prévoyez d'utiliser cette option.

Après un paiement réussi, la variable bepaid_client_card_token est ajoutée à l'affaire. Elle stocke le jeton de carte du client, qui peut être utilisé pour les paiements futurs sans interaction du client.

Ensuite, configurez votre flux de travail, définissez la date ou la condition requise pour facturer le client, et appelez la fonction make_bepaid_token_payment.

Les paramètres doivent être transmis dans l'ordre suivant :

amount → currency → description → contract

Descriptions des paramètres

La valeur du paramètre contract doit correspondre exactement à la valeur spécifiée lors de la génération du lien de paiement initial.

Paramètre	Description
amount (obligatoire)	Montant du paiement. La valeur doit être un nombre entier ou décimal, par exemple : `100` ou `100.5`.
currency (obligatoire)	Monnaie de paiement au format ISO 4217, par exemple : `USD`.
description (obligatoire)	Description du paiement, par exemple : `"Paiement hebdomadaire de l'abonnement pour la participation au club de loisirs"`.
contract (obligatoire)	Objet du paiement par jeton. Valeurs autorisées : `recurring` ou `card_on_file`.

Si le paiement est réussi :

la fonction renvoie le message "Successful charge via bePaid token" ;
le bot reçoit un callback de paiement réussi ;
la variable bepaid_token_payment_completed est définie sur True.

Si le paiement échoue :

la fonction renvoie un message décrivant la raison de l'échec ;
le bot reçoit un callback avec le suffixe _fail ;
la variable bepaid_token_payment_completed est définie sur False.

Si la banque nécessite une vérification supplémentaire du client, la fonction renvoie un lien où le client peut effectuer l'authentification 3-D Secure.

Comment gérer le résultat

En réponse aux actions du client, le bot reçoit des callbacks composés des 20 premiers caractères de la clé secrète suivis d'un suffixe indiquant le type d'opération et le résultat.

Le callback apparaît dans le système comme un message utilisateur, mais il n'est pas visible pour le client.

Callbacks de paiement

Pour les paiements uniques, le bot reçoit l'un des callbacks suivants :

keyNumber_success — paiement réussi.
keyNumber_fail — paiement échoué.

Vous pouvez également suivre le résultat du paiement à l'aide des variables suivantes :

bepaid_payment_completed — paiement effectué par le client.
bepaid_token_payment_completed — paiement automatique effectué à l'aide du jeton de carte du client.

Callbacks d'abonnement

Après l'activation réussie d'un abonnement, que ce soit lors du paiement initial ou d'un paiement récurrent, le bot reçoit :

keyNumber_success

Si l'abonnement est annulé, le bot reçoit :

keyNumber_canceled

Si un paiement d'abonnement échoue, le bot reçoit :

keyNumber_fail

Bepaid