How to Connect

To connect the bePaid payment system, you will need a Store ID, secret key, and public key. Once you receive these credentials, proceed to the payment system settings in MaviBot.

To obtain the Store ID, secret key, and public key, contact bePaid technical support.

In MaviBot, open the Acquiring section, select bePaid, and enter the credentials you received.

Note: The last field is a switch that selects the API endpoint depending on the country of use: Belarus or Russia.

To generate a payment link, assign a value to the payment_sum variable (for example: 150 or 100.55; use a dot as the decimal separator).

Once the payment_sum variable is set, the bepaid_pay_url variable is created automatically. You can display this variable as a link in a message or use it in a button with the text "Pay".

Function Parameter Description More Information
currency Payment currency in ISO 4217 format. For example: USD
language Payment page language. Default: en. Allowed values:
• en — English
• es — Spanish
• tr — Turkish
• de — German
• it — Italian
• ru — Russian
• zh — Chinese
• fr — French
• da — Danish
• sv — Swedish
• no — Norwegian
• fi — Finnish
• pl — Polish
• ja — Japanese
• uk — Ukrainian
• be — Belarusian
• ka — Georgian
• ro — Romanian
payment_description Payment description. —
link_expired Payment Link Expiration. Set the expiration date in the format dd.mm.yyyy (for example: 25.06.2025). By default, the payment must be completed within 24 hours. You can also use the Assign Variables on Redirect field:

• link_expired = current_date + 2 — the link will be valid for 2 days until 00:00.

• You can specify an exact expiration date and time in the format dd.mm.yyyy hh:mm (for example: 25.06.2025 12:23).

Standard variables can also be used. Example for a link valid for 30 minutes:

python\ntime = current_time + 30\nlink_expired = "#{current_date} #{time}"\n
russian_host Indicator for a store registered on the Russian bePaid host. Set this parameter to 1 if your store is registered on bepaid.tech. To switch to the Belarus host, set this parameter to "" (empty value).
test_payments Enables test payments. Assign any value to this variable before creating the payment link. —
bepaid_attempts Specifies the number of payment attempts. By default, 1 attempt is allowed. —
customer_data A JSON object containing the payer's first_name, last_name, and email. This information is required to send the payment receipt and can be edited on the payment page. The parameter must be passed as a JSON-formatted object.

Example:

python\ncustomer_data = {\n \"first_name\": \"Sam\",\n \"last_name\": \"Smith\",\n \"email\": \"[email protected]\"\n}\n
bepaid_contract (conditionally required) Payment purpose for token-based payments. Allowed values:

• recurring — for recurring payments with a fixed schedule.
• card_on_file — for one-time or irregular payments, for example, charging the customer after a service has been provided.

Example payment link:

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

Before assigning a value to payment_sum, you can define additional optional variables to customize the payment.

By default, the payment currency is Belarusian ruble (BYN). If you want to use another currency, assign a value to the currency variable.

After the payment is completed, the bepaid_callback_data variable is added to the customer. It contains the payment system response for the completed transaction.

You can retrieve the required values from this dictionary using the get() function.

How to Test Payments

To perform a test payment, assign any value to the test_payments variable before setting the payment_sum variable.

Important: Remove the test_payments variable before switching your bot to live mode.

Test Cards

Card Number Result
4200000000000000 Successful payment
4005550000000019 Failed payment

The following example generates a payment link for 100 Belarusian rubles (default currency).

Note: First assign any additional configuration variables, then assign the value to payment_sum. These variables can also be assigned earlier in your workflow—they do not have to be in the same block.

Finally, display the bepaid_pay_url variable where needed. It contains the generated payment link.

Subscription Management

The bePaid integration allows you to create subscriptions for your customers.

Before using this functionality in MaviBot, create a subscription plan in your bePaid account.

If the Plans and Subscriptions sections are not available in your account, contact your account manager.

Use the get_bepaid_subscription_url function and pass the plan_id parameter.

The function creates a subscription and returns a payment link.

Send the generated link to the customer and wait for the payment to be completed.

After a successful payment:

  • the subscription is activated;
  • the deal receives the variables:
    • bepaid_subscription_id;
    • bepaid_subscription_status;
  • a callback is sent to the bot (see How to Handle the Result).

Retrieving Subscription Information

To retrieve the current subscription information, use the get_bepaid_subscription_info function.

Pass the subscription_id parameter. Its value can be taken from the bepaid_subscription_id variable.

Cancelling a Subscription

To cancel a subscription, use the cancel_bepaid_subscription function.

The function accepts a single parameter:

  • subscription_id — the value can be taken from the bepaid_subscription_id variable.

After a successful cancellation:

  • the bepaid_subscription_status variable is set to "canceled";
  • a callback is sent to the bot (see How to Handle the Result).

Subscription Statuses

Status Description
trial Active or canceled trial period subscription.
active Active subscription with payment made on time.
failed Failed subscription. bePaid was unable to process the next payment.
error An error occurred while bePaid was attempting to process the payment.
canceled Subscription has been canceled and is no longer active.

Recurring Payments

You can also set up recurring payments without creating a subscription plan in your bePaid account.

To do this, you need the customer's card token.

Getting a Card Token

To obtain the customer's card token, the customer must complete an initial payment using a payment link generated with the payment_sum variable.

Before assigning a value to payment_sum, set the bepaid_contract variable to define the purpose of future token-based payments.

Supported values:

  • recurring — for recurring payments with a predefined schedule.
  • card_on_file — for one-time or irregular payments, for example, charging the customer after a service has been provided.

Note: The card_on_file option is not supported by all acquiring banks. Contact your account manager if you plan to use this option.

After a successful payment, the bepaid_client_card_token variable is added to the deal. It stores the customer's card token, which can be used for future payments without customer interaction.

Next, configure your workflow, define the required date or condition for charging the customer, and call the make_bepaid_token_payment function.

The parameters must be passed in the following order:

amount → currency → description → contract

Parameter Descriptions

The value of the contract parameter must exactly match the value specified when generating the initial payment link.

Parameter Description
amount (required) Payment amount. The value must be an integer or decimal number, for example: 100 or 100.5.
currency (required) Payment currency in ISO 4217 format, for example: USD.
description (required) Payment description, for example: "Weekly subscription payment for participation in the hobby club".
contract (required) Payment purpose by token. Allowed values: recurring or card_on_file.

If the payment is successful:

  • the function returns the message "Successful charge via bePaid token";
  • the bot receives a successful payment callback;
  • the bepaid_token_payment_completed variable is set to True.

If the payment fails:

  • the function returns a message describing the failure reason;
  • the bot receives a callback with the _fail suffix;
  • the bepaid_token_payment_completed variable is set to False.

If the bank requires additional customer verification, the function returns a link where the customer can complete 3-D Secure authentication.

How to Handle the Result

In response to customer actions, the bot receives callbacks consisting of the first 20 characters of the secret key followed by a suffix indicating the operation type and result.

The callback appears in the system as a user message, but it is not visible to the customer.

Payment Callbacks

For one-time payments, the bot receives one of the following callbacks:

  • keyNumber_success — successful payment.
  • keyNumber_fail — failed payment.

You can also track the payment result using the following variables:

  • bepaid_payment_completed — payment completed by the customer.
  • bepaid_token_payment_completed — automatic payment completed using the customer's card token.

Subscription Callbacks

After a subscription is successfully activated, either during the initial payment or a recurring payment, the bot receives:

keyNumber_success

If the subscription is canceled, the bot receives:

keyNumber_canceled

If a subscription payment fails, the bot receives:

keyNumber_fail