Bepaid (ru)
Comment connecter
Pour connecter le système de paiement bePaid, vous aurez besoin de l’ID du magasin, de la clé secrète et de la clé publique. Une fois obtenues, passons aux paramètres dans MaviBot.
Dans MaviBot, ouvrez la section "Encaissement", choisissez bePaid. Vous devez saisir les données obtenues.
Veuillez noter que le dernier champ est un commutateur d’hébergement API selon le pays d’utilisation : Biélorussie ou Russie.
Comment générer un lien de paiement
Pour générer un lien de paiement, vous devez définir la valeur de la variable payment_sum (par exemple 150 ou 100.55 (avec un point !)), après quoi la variable bepaid_pay_url apparaîtra. Cette variable peut être affichée sous forme de lien ou placée sur un bouton avec le texte "Payer".
Le lien ressemble à ceci : https://checkout.bepaid.by/widget/hpp.html?token=a05eabd3f9368725efbc175614c7d469da08f198cc51916b07fb75e53f9a3e1a
Avant de définir la valeur de la variable payment_sum, vous pouvez également définir les variables optionnelles suivantes pour configurer le paiement.
Par défaut, le rouble biélorusse est défini ; si une autre devise est nécessaire, il faut définir la valeur de la variable currency
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
durée de validité du lien de paiement, 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, dans le champ "Affectation des variables lors du passage" indiquer : link_expired = current_date + 2 (le lien sera valable 2 jours jusqu’à 00:00)
link_expired vous pouvez aussi indiquer une date avec une heure précise, séparée par un espace, au format jj.mm.aaaa hh:mm (par exemple : 25.06.2025 12:23). Par défaut, le paiement doit être effectué dans les 24 heures
Vous pouvez aussi utiliser des variables standard, par exemple définissons la durée de validité du lien à 30 minutes :
time = current_time + 30
link_expired = "#{current_date} #{time}"
russian_host
indicateur d’enregistrement du magasin sur l’hôte russe de bePaid. Indiquez ce paramètre avec la valeur 1 si votre magasin est enregistré sur le site bepaid.tech
Si vous devez passer l’hôte en biélorusse, indiquez le paramètre avec la valeur ''
test_payments
la variable est nécessaire pour les paiements de test ; si un paiement de test est requis, ajoutez-la avec n’importe quelle valeur.
bepaid_attempts
indique le nombre de tentatives pour effectuer le paiement ; par défaut, 1 tentative est accordée.
сustomer_data
un tableau contenant first_name, last_name et email du payeur. Ces données sont nécessaires pour envoyer le reçu par e-mail au payeur et sont disponibles pour modification sur la page de paiement.
Le paramètre doit être transmis sous forme de liste au format JSON, composée de paires clé-valeur
par exemple:
customer_data = ‘{“first_name”: “Vladimir”, “last_name”: “Popov”, “email”: “[email protected]” }’
bepaid_contract (conditionnellement obligatoire)
destination du paiement par jeton.
Valeurs attendues : “recurring” (pour les paiements récurrents à fréquence définie) ou “card_on_file” (pour les paiements non récurrents, par exemple un paiement différé pour un service rendu)
Après l’achèvement du paiement, la variable suivante sera ajoutée au client bepaid_callback_data, contenant les données de réponse du système de paiement pour l’opération effectuée. À partir du dictionnaire reçu, vous pouvez extraire les données nécessaires à l’aide de la méthode get.
Comment tester les paiements
Pour effectuer un paiement de test avant d’indiquer la variable payment_sum, vous devez définir la variable test_payments avec n’importe quelle valeur.
N’oubliez pas de la supprimer lors du lancement du bot en mode production !
Cartes pour les tests :
4200000000000000 succès
4005550000000019 échec
Si quelque chose ne fonctionne pas, comparez les données avec celles du site officiel : https://docs.bepaid.by/ru/test-integration#test-card-number
Exemple de génération d’un lien de paiement
Créons un lien de paiement d’un montant de 100 roubles biélorusses (devise par défaut)
Veuillez noter qu’au début, nous définissons les variables supplémentaires pour les paramètres, puis payment_sum. Les variables peuvent également être définies plus tôt dans la chaîne, et pas dans un seul bloc ; c’est un exemple.
Ensuite, à l’endroit voulu, nous affichons la variable bepaid_pay_url, qui contient le lien
Gestion des abonnements
L’intégration du système de paiement offre la possibilité de créer des abonnements pour vos clients.
Avant d’utiliser les fonctionnalités de MaviBot, créez un plan d’abonnement dans votre espace personnel bePaid.
Si le menu “Plans” et “Abonnements” ne s’affiche pas dans l’espace personnel, contactez votre gestionnaire.
Création d’un abonnement et obtention du lien de paiement
Utilisez la fonction get_bepaid_subscription_urlen lui transmettant le paramètre plan_id, où
plan_id
est l’identifiant du plan dans le système bePaid.
En résultat, la fonction créera un abonnement et renverra le lien pour son paiement.
Envoyez le lien au client et attendez la fin du paiement.
En cas de paiement réussi, l’abonnement sera activé, les variables bepaid_subscription_id et bepaid_subscription_status seront ajoutées à la transaction, et un callback arrivera dans le bot (voir la section “Comment traiter le résultat”).
Obtention d’informations sur l’abonnement
Pour obtenir les données de l’abonnement actuel du client, appelez la fonction get_bepaid_subscription_info en lui transmettant le paramètre subscription_id (la valeur peut être prise de la variable bepaid_subscription_id).
Annulation de l’abonnement
Pour annuler l’abonnement, utilisez la fonction cancel_bepaid_subscription.
Cette fonction ne prend qu’un seul paramètre subscription_id (la valeur peut être prise de la variable bepaid_subscription_id).
En cas d’annulation réussie, la variable bepaid_subscription_status prendra la valeur “canceled”, et un callback arrivera dans le bot (voir la section “Comment traiter le résultat”).
Statuts des abonnements
trial
Abonnement actif ou annulé de la période d’essai.
active
Abonnement actif dont le paiement a été effectué dans les délais.
failed
Abonnement échoué. bePaid n’a pas pu effectuer le paiement suivant.
error
Une erreur s’est produite lors de la tentative de bePaid d’effectuer le paiement.
canceled
L’abonnement est annulé et n’est plus en vigueur.
Paiements récurrents
Vous pouvez également organiser un système d’abonnements sans créer de plan dans l’espace personnel bePaid.
Pour cela, vous aurez besoin du jeton de la carte du client.
Pour obtenir le jeton de la carte, le client doit effectuer un paiement initial via le lien généré à l’aide de payment_sum.
Avant de définir la valeur de payment_sum, définissez la variable bepaid_contract, dans laquelle indiquez l’objectif des futurs paiements par jeton : “recurring” pour les paiements récurrents à fréquence définie ou “card_on_file” pour les paiements non récurrents (par exemple, un paiement différé pour un service rendu).
L’option “card_on_file” n’est pas prise en charge par tous les acquéreurs. Si vous souhaitez l’utiliser, contactez votre responsable de compte.
Après un paiement réussi, la variable bepaid_client_card_token sera ajoutée à la transaction, et le jeton de la carte du client y sera enregistré. Ce jeton permet de débiter la carte du client sans sa participation.
Ensuite, configurez le tunnel et définissez une date ou une condition pour le débit automatique, puis appelez la fonction du calculateur make_bepaid_token_payment en lui transmettant les paramètres nécessaires.
Ordre des paramètres:
amount -> currency -> description -> contract
Description des paramètres :
amount (obligatoire)
montant du paiement, valeur attendue - nombre entier ou décimal, par exemple 100 ou 100.5;
currency (obligatoire)
devise de paiement en ISO-4217 format, par exemple “USD”
description (obligatoire)
description de la raison du débit, par exemple, “Paiement de l’abonnement hebdomadaire pour participer à un club d’intérêts”;
contract (obligatoire)
destination du paiement par jeton. Valeurs attendues : “recurring” ou “card_on_file”.
La valeur contract doit obligatoirement correspondre à la valeur indiquée lors de la création du lien pour le paiement initial !
Si le paiement a réussi, la fonction renverra le message “Débit réussi via le jeton bePaid“, vous recevrez un callback de paiement réussi, et la variable de transaction bepaid_token_payment_completed prendra la valeur “True”.
Si le paiement n’a pas abouti, la fonction renverra un message indiquant la raison de l’échec du paiement, un callback avec le suffixe “_fail” arrivera dans le bot, et la variable de transaction bepaid_token_payment_completed prendra la valeur “False”.
La banque peut demander la finalisation du paiement par le client. Dans ce cas, la fonction renverra un lien demandant la validation de l’authentification 3-D Secure.
Comment traiter le résultat
En réponse aux actions du client, des callbacks arriveront dans le bot, composés des 20 premiers caractères de la clé secrète et d’un suffixe dépendant du type et du résultat de l’opération.
Dans le système, le callback ressemble à un message de l’utilisateur, mais l’utilisateur lui-même ne le voit pas.
Pour les paiements
À la suite d’un paiement ne relevant pas d’un abonnement, vous recevrez l’un des messages suivants :
numeroCle_success - en cas de paiement réussi ;
numeroCle_fail - en cas d’échec du paiement ;
Le statut du dernier paiement peut également être suivi via les variables bepaid_payment_completed (pour les paiements avec participation du client) et bepaid_token_payment_completed (pour les paiements sans acceptation par token de carte)
Pour les abonnements
Après l’activation réussie d’un abonnement lors du premier paiement ou d’un paiement récurrent, un message arrivera dans le bot numeroCle_success.
Si l’abonnement a été annulé, vous recevrez numeroCle_canceled.
En cas d’échec du paiement de l’abonnement, vous recevrez un message numeroCle_fail.
Mis à jour