How to Connect Prodamus

To connect Prodamus, you need the payment form URL and a secret key.

The payment form URL is provided after registration. Example:

demo.payform.ru

You can obtain the secret key in your Prodamus account. You also need to specify the URL where payment notifications will be sent.

Detailed instructions on how to configure this

Notification URL:
https://chatter.mavibot.ai/prodamus_callback/result

This URL must be specified in two places in the settings.

On the main settings page, you can select the payment form operating mode:

  • Demo mode without real payments
  • Live mode for accepting payments

The notification URL must be specified in two sections of the payment system settings:

  • In the Form Settings tab for one-time payments
  • In the Subscriptions tab for subscription payments

Notification URL:
https://chatter.mavibot.ai/prodamus_callback/result

To configure subscription payments, open the Subscriptions tab and enter the notification URL:

https://chatter.mavibot.ai/prodamus_callback/result

Important: After entering the URL, make sure to click Save.

To connect Prodamus in Mavibot, open the Acquiring section.

Then enter the payment form URL and secret key in the corresponding fields.

Important: Do not include https:// when entering the payment form URL.

The connection is now complete. Next, let us look at how to use this functionality.

Creating a Payment Link

Payment Button

A payment link can be generated using a button with the Payment function.

See the guide on creating a payment button:
/docs/chatbot-builder-buttons-payment-button

The sections below describe all available button settings.

Required Parameters

To generate a payment link, the following fields are required:

  • Amount
  • Product Name
  • Products for Receipt (required only if you do not have your own online cash register and want Prodamus to generate fiscal receipts)

When the customer opens the payment page, the product information and price are already filled in. The customer only needs to enter their contact details.

If the customer's email and/or phone number are specified in the button settings, they will also be pre-filled on the payment page.

Button Settings

Text – The text displayed on the payment button.

Function – Select Payment to generate a payment link.

Payment System – Displays the payment systems connected to the project.

If no payment system is connected, this button type is unavailable.

Product Name (required) – Specify the exact product name.

For example, instead of:

Phone

use:

Xiaomi Smartphone, Model ...

Note: Double quotation marks (") are not allowed in the product name. Remove them or replace them with single quotation marks.

Amount (required) – The payment amount.

Additional Parameters

Click Additional Information to configure optional fields:

  • Order description
  • Discount (RUB)
  • Customer email variable
  • Customer phone variable
  • Link expiration date
  • Subscription product ID
  • Products for receipt

Notify on Click – Enable this option if you want to receive a notification in the customer conversation when they click the payment button.

This notification can be used to build additional chatbot logic.

Many payment providers support cloud cash registers required for tax compliance. Check your payment provider's documentation for information about receipt generation and fiscalization.

The payment page opened by the button looks like this:

Order Description – The text entered in this field is displayed on the payment page in the Additional Information section.

Discount – Specify the discount amount in RUB. Decimal values are supported using a period as the separator (for example, 50.99).

On the payment page, the discount is applied automatically. The original price is crossed out, and the discounted amount is displayed as the total payment.

Customer Email Variable (optional if a phone number is provided) – The customer's email address or a variable containing it, for example:

#{email}

Customer Phone Variable (optional if an email address is provided) – A variable containing the customer's phone number in the format:

79000000000

For example:

#{phone}

Either an email address or a phone number must be provided.

Link Expiration Date – Specify the expiration date in the format:

dd.MM.yyyy HH:mm

Example:

25.01.2021 11:00

You can also use a variable, for example:

#{link_expired}

Subscription Product ID – Enter the subscription product ID to create a recurring payment.

For information about creating subscription products, see the Prodamus documentation.

If a subscription product ID is specified:

  • the payment amount is ignored;
  • product information is loaded from the subscription product in Prodamus;
  • the customer's phone number is required for subscription management;
  • the callback contains the subscription product ID after a successful payment.

Products for Receipt (conditionally required) – Required for payment fiscalization through Prodamus if you do not use your own online cash register.

Specify the product description, price, and a link to the purchased content.

Example:

Course "Advanced Photography", price 3000 RUB,
https://example.com/course

If you specify a link expiration date, the payment button behaves differently depending on whether the link is still valid.

If the customer opens the payment link after it has expired, the payment cannot be completed, and they will see the following message:

Note: The expiration date must be later than the current date. Otherwise, the customer will not be able to complete the payment.

Inactive Payment Button

If the customer requests the payment button after the link has already expired, the button is not displayed.

Instead, the following customer variable is created:

error_payment_button

Value:

Error: The link expiration date must be later than the current date.

We recommend handling this situation in your chatbot flow.

Create a condition that checks:

error_payment_button == "Error: The link expiration date must be later than the current date."

If the condition is met, send a message such as:

Sorry, you were unable to complete the payment in time. The payment link has expired.

Customer Variables Created by the Payment Button

When a customer receives a message containing a Payment button, Mavibot automatically creates the following variables.

__payments

A system variable that stores the payment amount and the generated payment link identifier. It is used to match callbacks received from the payment system.

Important: Do not modify or delete the __payments system variable.

error_payment_button

This variable is created automatically if an error occurs while generating the payment button.

It contains either the error message generated by Mavibot or the error returned by the payment system.

Variable values become available after the chatbot moves to the next block.

Processing Payment Results

Successful Payment

After a successful payment, Mavibot automatically receives the following callback:

<first_10_characters_of_secret_key>_success <payment_amount>

Example:

ovg58keefc_success 44

Where:

  • ovg58keefc — the first 10 characters of the Prodamus secret key.
  • _success — indicates a successful payment.
  • 44 — the payment amount.

Customers never see payment callbacks. They are visible only in the Customers section and can be used to build chatbot logic.

Example

Step 1

Create a block containing the Payment button.

Step 2

Create a Trigger block or configure an arrow leading to the next block.

Paste the payment callback into the trigger or matching condition.

The same callback can also be configured in the Initial Condition block if your chatbot requires global payment processing.

Important: Use either Exact match or Contains keywords as the matching type.

Note: If you process callbacks on a specific arrow, make sure the customer is still in the block containing that arrow when the callback arrives. Otherwise, the transition will not occur. For chatbot flows where customers can move between blocks, it is recommended to process callbacks in the Initial Condition block instead.

Successful Subscription Payment

For subscription products, the callback format is:

<first_10_characters_of_secret_key>_success <subscription_product_id>

Example:

214009eefc_success 618117

Where:

  • 214009eefc — the first 10 characters of the secret key.
  • _success — successful payment.
  • 618117 — the subscription product ID.

Failed Payment

If the payment fails, Mavibot receives the following callback:

<first_10_characters_of_secret_key>_fail <payment_amount>

Example:

ovg58keefc_fail 44

Where:

  • ovg58keefc — the first 10 characters of the secret key.
  • _fail — payment failed.
  • 44 — the payment amount.

Note: Not all payment providers send callbacks for failed payments.

Payment Amount Mismatch

If the amount paid differs from the amount specified in the payment button, Mavibot receives the following callback:

<first_10_characters_of_secret_key>_different_amounts <payment_id>

Example:

ovg58keefc_different_amounts 123456

Where:

  • ovg58keefc — the first 10 characters of the secret key.
  • _different_amounts — indicates that the paid amount differs from the expected amount.
  • 123456 — the unique payment ID.

get_prodamus_payment_url Calculator Function

You can generate a payment link using the get_prodamus_payment_url function in the Calculator block.

Assign the function result to any variable.

You can choose any variable name. The screenshots below use example variable names.

The generated payment link is stored in the variable and can be used in a message or attached to a button.

Example payment link:

https://payform.ru/7p3JR8/

Example

Function Syntax

your_variable = get_prodamus_payment_url(
    amount,
    product_name,
    expired,
    customer_phone,
    customer_email,
    discount,
    description,
    extra_params,
    products_for_receipt
)

Parameters

Parameter Description
amount Required. Payment amount. Accepts integers or decimal values (for example, 25 or 52.5).
product_name Required. Product name.
expired Payment link expiration date. Supported formats: dd.MM.yyyy or dd.MM.yyyy HH:mm. You can also use variables or expressions such as current_date + 2. Pass '', "", or None to skip this parameter.
customer_phone Customer phone number. Optional if customer_email is provided. Pass '' or "" to skip.
customer_email Customer email address. Optional if customer_phone is provided. Pass '' or "" to skip.
discount Discount amount. Accepts integers or decimal values (for example, 25 or 63.5). Pass '' or "" to skip.
description Product description. If omitted, Prodamus automatically uses Payment for order order_id. Pass '' or "" to skip.
extra_params Additional Prodamus API parameters not included in the function arguments. Pass '', "", or None to skip.
products_for_receipt Receipt data in the format "product description - price - purchased content URL". Required if you use Prodamus fiscalization without your own online cash register.

Expiration Date Examples

Expire after two days:

expired = current_date + 2

Expire in 30 minutes:

time = current_time + 30
expired = "#{current_date} #{time}"

Example extra_params 

extra_params = {
    "payments_limit": "3",
    "payment_method": "vsegdada_installment_0_0_6"
}

See the Prodamus REST API documentation for the full list of supported parameters.

Example

extra_params = {
    "payments_limit": "3"
}

products_for_receipt = "Photography Course, price 4999 RUB, https://example.com/course"

payment_link = get_prodamus_payment_url(4999, "Photography Course", "27.03.2023 17:00", "79167777771", "[email protected]", 20, "The best photography course", extra_params, products_for_receipt)

In this example:

  • extra_params contains additional payment parameters.
  • products_for_receipt contains fiscal receipt information.
  • payment_link stores the generated payment URL.

If multiple payment link functions are used in the same Calculator block and one of them fails, the error is written to the error_payment_func variable. Only the last function error is stored.

Generating a Payment Link Using payment_sum

Note: The value of payment_sum is applied after all optional variables such as payment_description, product_name, and others.

Instead of calling get_prodamus_payment_url(), you can generate a payment link simply by assigning a value to the payment_sum variable in the Calculator block.

After payment_sum is assigned, Mavibot automatically creates the prodamus_pay_url variable containing the payment link.

Example:

https://payform.ru/7p3JR8/

You can display this variable in a message or use it as the URL of a button.

Optional Variables

The following variables can be defined before assigning payment_sum.

Variable Description
product_name Product name. If omitted, the default value is Payment for order order_id.
payment_description Product description shown on the payment page.
discount_value Discount amount. Example: 25 or 50.25.
customer_phone Customer phone number.
customer_email Customer email address.
link_expired Payment link expiration date.
currency Payment currency. Supported values: rub, usd, eur, kzt. Must be lowercase.
payment_title Payment title (up to 127 characters). Defaults to Payment payment_id.
locale Payment page language (for example, ru-RU, en-US, fr-FR).
products_for_receipt Receipt information. Required if you use Prodamus fiscalization without your own online cash register.
payment_sum Required. Payment amount.

You can specify the expiration date in several ways.

Specific date:

25.01.2021

Specific date and time:

25.01.2021 12:23

Using variables:

time = current_time + 30
link_expired = "#{current_date} #{time}"

Or:

link_expired = current_date + 2

Example

First, set the payment amount.

Then use the generated prodamus_pay_url variable wherever you need to send the payment link.

Available Payment Methods

The prodamus_available_payment_methods variable must be defined before payment_sum.

Supported values include:

Value Description
AC Russian bank cards
ACkz Kazakhstan bank cards
ACf CIS bank cards (excluding Russia)
ACEURNMBX EUR cards (excluding Russia and Belarus)
SBP Faster Payments System (Russia)
QW QIWI Wallet
PC YooMoney
GP Payment terminal
sbol Sberbank Online
invoice Invoice payment
installment Prodamus installments
credit T-Bank credit
monetaworld International cards (excluding Russia)

Several payment methods can be specified by separating them with a vertical bar (|).

Example:

prodamus_available_payment_methods = "AC|PC|QW"

Currency

You can specify the payment currency using the prodamus_currency variable.

Supported values:

  • kzt
  • usd
  • eur

The generated payment page will display the amount in the selected currency.

When processing the payment_callback callback, pay attention to the following fields:

  • currency
  • currency_sum

These contain the payment currency and the paid amount.

If no payment methods are specified, the payment page will not display any available payment methods. Enable the required payment methods in your Prodamus account first.

Processing Payment Results

Payment Callbacks

After a successful or failed payment, Mavibot receives callbacks that can be used to determine the payment status.

Callbacks appear in the conversation as system messages. Customers never see or send these messages.

Examples:

Successful payment:

453e8fba8b7cef9ce58dc6e18e25b39ad5a05748175a3f205f2b084acbfc3b66_success

Failed payment:

453e8fba8b7cef9ce58dc6e18e25b39ad5a05748175a3f205f2b084acbfc3b66_fail

After a successful payment, the following customer variable is automatically created:

prodamus_payment_completed = True

Note: Callbacks are received with a slight delay. After sending the payment link, it is recommended to notify the customer that payment confirmation may take a few moments.

Example message:

After completing the payment, please wait for the payment confirmation.

Callback Format

Payment links generated by either the Payment button or the get_prodamus_payment_url() function return the following callback after a successful payment:

<secret_key>_success

Example:

ovg58keefc_success

Where:

  • <secret_key> is your Prodamus secret key.
  • _success indicates a successful payment.

Example

Create a trigger or conditional block that waits for the callback and then continues the chatbot flow.

Important: Use Exact match as the matching type.

If you want to generate another payment link after a successful payment, first reset the existing payment information.

Set:

payment_sum = 0

Then assign a new value to payment_sum to generate a new payment link.

Subscription Callbacks

Prodamus also sends callbacks related to subscription status.

Examples include:

  • Subscription cancelled by the customer
  • Subscription reactivated by the customer
  • Subscription deactivated after several failed payment attempts

Subscription Cancelled

Sent when the customer manually cancels their subscription.

The current paid billing period may still remain active.

You can use this callback to:

  • ignore the event;
  • notify your team;
  • send a retention message to the customer.

Subscription Reactivated

Sent when the customer restores a previously cancelled subscription.

Depending on your business logic, you can ignore this callback or remove the customer from a retention workflow.

Subscription Deactivated

Sent after several unsuccessful recurring payment attempts.

Saving Callback Data

After a successful payment, the full callback payload is stored in the following variable:

payment_callback

It contains all payment information returned by Prodamus.

Example:

{
  "date": "2021-03-30T11:44:43+03:00",
  "order_id": "757679",
  "sum": "14.50",
  "customer_phone": "+77777777777",
  "customer_extra": "Product",
  "payment_status": "success"
}

If you specified product_name and payment_description while generating the payment link, you can retrieve them from the callback.

Example:

product = get(payment_callback, "products[0][name]")
description = get(payment_callback, "customer_extra")

Retrieve the payment amount:

amount = get(payment_callback, "sum")

Note: The value of payment_sum is always assigned after optional variables such as payment_description and product_name.

Available Callbacks

In addition to successful payment callbacks, Prodamus sends various system callbacks that can be used to automate your chatbot.

Subscription Events

  • Subscription cancelled by the customer
  • Subscription reactivated by the customer
  • Subscription expired

Payment Failure Events

Depending on the payment provider, you may receive callbacks with the failure reason, for example:

  • Payment failed – Insufficient funds
  • Payment failed – Card expired
  • Payment failed – Card limit exceeded
  • Payment failed – Card reported lost
  • Payment failed – System error
  • Payment failed – Transaction declined by the issuing bank
  • Payment failed – Transaction declined by the bank

Other Events

  • Upcoming recurring payment notification
  • Installment application approved
  • Installment application cancelled
  • Installment application rejected

You can create chatbot flows that react to any of these callbacks.

For example, you can automatically notify customers when a recurring payment fails.

To process a specific failure reason, create a trigger that matches the corresponding callback.

To process all failed payments regardless of the reason, use a condition that checks whether the callback contains:

Payment failed

Any callback containing the text Payment failed will trigger the configured chatbot action.

Subscription Payments

Creating a Subscription

Before accepting subscription payments, create a subscription product in your Prodamus account.

For detailed instructions, see the Prodamus documentation.

After creating the subscription product, copy its Subscription Product ID.

Assign the Subscription Product ID to the following variable:

prodamus_subscription

Mavibot automatically generates the following variable:

prodamus_pay_url

The generated URL can be displayed in a message or attached to a button.

Example:

https://payform.kz/7p3JR8/

Subscription payments are processed exactly the same way as one-time payments.

After a successful subscription payment, the customer's phone number is automatically saved in the customer_phone variable.

If customer_email is not provided, customer_phone is required for subscription management.

get_prodamus_subscription_url

You can also generate subscription payment links using the Calculator.

Function:

get_prodamus_subscription_url(
    subscription_id,
    product_name,
    expired,
    customer_phone,
    customer_email,
    discount,
    description,
    extra_params,
    products_for_receipt
)

Example

Parameters

Parameter Description
subscription_id Required. Subscription Product ID from your Prodamus account.
product_name Required. Product name.
expired Payment link expiration date. Supports dd.MM.yyyy or dd.MM.yyyy HH:mm. Variables are also supported.
customer_phone Customer phone number. Optional if customer_email is specified.
customer_email Customer email address. Optional if customer_phone is specified.
discount Discount amount.
description Product description.
extra_params Additional Prodamus API parameters.
products_for_receipt Receipt information. Required when using Prodamus fiscalization without your own online cash register.

Example

extra_params = {
    "payments_limit": "3"
}

products_for_receipt = "Photography Course subscription, 2000 RUB/month, https://example.com/course"

subscription_link = get_prodamus_subscription_url(618988, "Photography Course", "27.03.2023 17:02", "79167777771", "[email protected]", 20, "Premium subscription", extra_params, products_for_receipt)

If multiple payment link functions are executed in the same Calculator block and one of them fails, the error is stored in the error_payment_func variable.

Managing Subscription Status

Subscription management is available only for active subscriptions. It is not supported in demo mode because no payment card is linked.

To manage a subscription, at least one of the following parameters must be available:

  • customer_phone
  • customer_email

To cancel or reactivate a subscription, use the following function:

delete_subscription_prodamus

Example parameters:

{
  "customer_phone": "#{customer_phone}",
  "id_subscription": "#{prodamus_subscription}",
  "url": "https://demo.payform.ru/",
  "secret_key": "453e8fba8b7cef9ce58dc6e18e25b39ad5a05748175a3f205f2b084acbfc3b66",
  "switcher": "0",
  "profile_id": "12345"
}

Parameters

Parameter Description
url Payment form URL configured in Mavibot.
secret_key Your Prodamus secret key.
id_subscription Subscription Product ID.
customer_phone Subscriber's phone number.
switcher Subscription action: 0 – deactivate, 1 – reactivate.
profile_id Customer profile ID in Prodamus.

If a profile ID is returned by Prodamus, it is automatically saved in the profile_id variable. You can use this variable instead of customer_phone or customer_email when managing subscriptions.

Example:

The function returns a status value.

If the operation succeeds:

status = ok

prodamus_subscription_switch_status

You can also manage subscriptions using the Calculator.

prodamus_subscription_switch_status(
    subscription_id,
    switcher,
    customer_phone,
    customer_email,
    profile_id
)

Parameters

Parameter Description
subscription_id Subscription Product ID.
switcher 0 – deactivate the subscription, 1 – reactivate the subscription.
customer_phone Customer phone number. Optional if customer_email is provided.
customer_email Customer email address. Optional if customer_phone is provided.
profile_id Customer profile ID in Prodamus.

Example 1

Deactivate a subscription using the customer's phone number.

status = prodamus_subscription_switch_status(
    "618117",
    "0",
    "75431312321"
)

Example 2

Deactivate a subscription using the customer's email address.

status = prodamus_subscription_switch_status(
    "618117",
    "0",
    "",
    "[email protected]"
)

The function returns ok if the operation succeeds. Otherwise, it returns an error message.

Managing Subscription Discounts

Use the following function to apply a discount to future recurring payments.

The discount can be applied for a limited number of payments or indefinitely.

prodamus_subscription_discount(
    subscription_id,
    discount,
    customer_phone,
    num,
    profile_id
)

Parameters

Parameter Description
subscription_id Subscription ID.
discount Discount amount. Must be greater than zero and not exceed the subscription price.
customer_phone Customer phone number. Optional if available from customer_phone.
num Number of future payments to which the discount should be applied. If omitted, the discount is permanent.
profile_id Customer profile ID in Prodamus.

If successful, the function returns:

ok

Otherwise, it returns an error description.

Updating the discount or payment count requires calling the function again with the new values.

Examples

Permanent discount

Apply a discount of 1 to all future subscription payments.

result = prodamus_subscription_discount(
    "624034",
    "1"
)

Discount for the next three payments

result = prodamus_subscription_discount(
    "624034",
    "2",
    "",
    "3"
)

Decimal discount

result = prodamus_subscription_discount(
    #{prodamus_subscription},
    10.25,
    #{customer_phone},
    3
)

Changing the Next Subscription Payment Date

You can postpone the next recurring payment by changing its scheduled date.

The new payment date must always be later than the currently scheduled payment date.

This feature can be used, for example, to extend a customer's subscription period as a bonus.

Use the following function:

prodamus_subscription_payment_date(
    subscription_id,
    date,
    customer_phone,
    profile_id
)

Parameters

Parameter Description
subscription_id Subscription ID.
date New payment date in the format dd.MM.yyyy or dd.MM.yyyy HH:mm. If no time is specified, 00:00 is used.
customer_phone Customer phone number. Optional. If omitted, the value is taken from the customer_phone variable.
profile_id Customer profile ID in Prodamus.

Passing Additional Parameters to Prodamus

You can send additional parameters supported by Prodamus (such as subscription start dates or installment settings) when generating a payment link.

Simply create a variable whose name starts with the prodamus_ prefix.

Example:

prodamus_some_parameter

When a payment link is generated, all variables with the prodamus_ prefix are automatically included in the request sent to Prodamus.

Testing Payments

Only the payment process is simulated.

While configuring your integration and chatbot flows, you can use Prodamus test cards to avoid charging real funds.

First, switch your payment page to Demo mode.

Don't forget to click Save after changing the mode.

Test Cards

MIR

Field Value
Card Number 2202 2050 0001 2424
Expiration Date 05/35
CVV 669

Mastercard

Field Value
Card Number 5469 9801 0004 8525
Expiration Date 05/26
CVV 041
3-D Secure Code 111111

Visa

Field Value
Card Number 4006 8009 0096 2514
Expiration Date 05/26
CVV 941
3-D Secure Code 111111

Important: Test cards trigger the same chatbot logic, callbacks, automations, and integrations as real payments.

Once testing is complete, switch the payment page back to Live mode to start accepting real payments.

The demo mode toggle must be turned off (red switch disabled).