Stripe

How to connect

To connect the Stripe payment system, you will need a secret API key and a webhook key.

The secret API key can be copied by going to Developers → API keys and copying the Secret key.

Step 1. Go to Developers → API keys:

Step 2. Find and copy the Secret key:

Next, you need to set a callback URL. This allows the bot to receive payment notifications.

Go to the Webhooks section and add the webhook URL.

A form will appear.

Step 3. Click "+add destination".

Step 4. Select events.

Step 3. Select the "Webhook endpoint" type.

Step 4. Review the request type and click "Continue".

Step 5. Enter a name and specify the endpoint URL.

Set the URL to: https://chatter.mavibot.ai/stripe\\_callback/result

Step 6. Two endpoints will be created — you can review the settings before adding them.

Step 7. Click the "Add destinations" button. The webhooks will be saved.

Step 8. Click "Done".

Save and you will be taken to the page with the webhook configured.

Step 9. Click on the webhook where you selected all events.

Step 10. Find the Signing key and save it (you will need it later to connect to MaviBot).

Once you have the keys, proceed to connect in Mavibot.

In Mavibot, open the "Acquiring" section and select Stripe.

On the connection page, enter the keys you obtained.

Click "Save settings".

Done! You have connected Stripe.

How to connect a transaction status callback

To receive an additional callback, you need to add a second webhook alongside the existing one.

Set the URL to: https://chatter.mavibot.ai/stripe\\_callback/\\<api_key>/charge_status

and select the following events:

charge.failed
charge.pending
charge.succeeded

More details on each webhook type:

charge.succeeded — contains information about a successfully completed transaction (similar to the successful payment callback)

charge.pending — "transaction in progress", may take up to 7 days to complete. The webhook will have the format {first 10 characters}{webhook type} For example: sk_test_45LDPJLKT95d_charge.pending

charge.failed — "transaction failed". The webhook will have the format {first 10 characters}{webhook type} For example: sk_test_45LDPJLKT95d_charge.failed

Add the webhook key obtained after saving to the Mavibot field — Webhook key2.

stripe_invoice_id — the transaction identifier for which a successful payment callback was not received immediately after the payment.

How to set up taxes

To use taxes in payments, you first need to create them in your Stripe dashboard. To do this, type "tax rates" in the search bar:

And click "+ Add tax rates".

Then enter the applicable tax rate.

In the menu that opens, select the tax type, the region it applies to, the percentage rate, and whether the tax will be included in the payment amount (Inclusive) or added on top of it (Exclusive).

After creating the tax rate, copy its ID into the stripe_tax_id variable before declaring the payment amount.

To avoid errors, it is recommended to set the stripe_tax_id variable to an empty string ("") after receiving the link — this way you can apply the tax only when needed.

If done correctly, in the case of a tax rate with the exclusive parameter, you will see the following:

How to get a payment link

To generate a payment link, set the value of the payment_sum variable (e.g. 150 or 100.55 — use a dot, not a comma!). After that, the stripe_pay_url variable will appear. You can display this variable as a link or place it on a button with the text "Pay".

The link looks like this:

https://checkout.stripe.com/pay/cs_test_a17mskKFFRwEuo3WgBSAUjfk7xaZZIrct9B3Ds2AdODVq1I8aRiqYEBdrU#fidkdWxOYHwnPyd1blpxYHZxWjA0TGFsVzFPVmpmMzJAbVYzUkp1Y0lLYDVgfzR2Q0NxcWZBNUNnTnRSVVRJSGFobEB1UExSczRMMTc8PWRLMGBddl8xalxyPDRoUGhnZm9xXXZANDZyaF0wNTVBVExsPHZyfycpJ2N3amhWYHdzYHcnP3F3cGApJ2lkfGpwcVF8dWAnPyd2bGtiaWBabHFgaCcpJ2BrZGdpYFVpZGZgbWppYWB3dic%2FcXdwYHgl

By default, the currency is set to USD. To use a different currency, set the value of the currency variable.

You can also set the following optional variables before setting the payment_sum value to configure the payment.

Important! If you use both stripe_payment_method_type and stripe_additional_payment_method_type variables, the values in them must be different!

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

For more details on each method and the countries where they are available, refer to the Stripe documentation

Payment link generation example

Let's create a payment link for 1000 AED (the default currency is USD).

Note:

— First, specify the optional parameters such as first_name, payment_description, etc.

— Then, assign the value to the payment_sum variable last.

The variables can also be set earlier in the chain, not necessarily in the same block — this is just an example.

Then display the stripe_pay_url variable, which contains the link, at the desired point — either in a message block or on a button:

Example 1. Display the payment link directly in a message:

Example 2. Add the payment link to a button.

When the button is clicked or the link is followed, your payer will be redirected to the payment page.

The example shows that the parameters we specified in the calculator in the block settings were applied: order description, currency, and amount.

If you pass the tax rate parameter (stripe_tax_id) in the block.

The tax rate will also be displayed in the payment form.

payment_description = "test payment"

currency = 'AED'

stripe_tax_id = 'enter_your_stripe_id_tax'

payment_sum = 1000

Where to find the tax ID.

How to set up recurring payments

For recurring payments (subscriptions), declare the stripe_subscription variable before the payment_sum variable and assign it the subscription name.

You can also add the following variables: interval — the subscription interval duration. Pass 'day' for days, 'week' for weeks, 'month' for months, or 'year' for years. If the variable is not set, 'month' will be used by default.

Important!

The duration of one subscription cycle cannot exceed 1 year (for the 'year' parameter), 12 months (for the 'month' parameter), or 52 weeks (for the 'week' parameter).

interval_count — the number of specified intervals: how many days, weeks, or months are included in the subscription for the given amount. Defaults to 1.

stripe_payment_method_type — the payment method; defaults to card payment. Can be replaced with other payment methods available in Stripe. Available methods are listed below.

For example, stripe_payment_method_type = 'customer_balance'

stripe_additional_payment_method_type — add an additional payment method. Available methods are listed below.

For example, stripe_additional_payment_method_type = 'sepa_debit'

Important! If you use both stripe_payment_method_type and stripe_additional_payment_method_type variables, the values in them MUST be DIFFERENT!

For more details on each method and the countries where they are available, refer to the Stripe documentation.

Important!

The duration of one subscription cycle cannot exceed 1 year (for the 'year' parameter), 12 months (for the 'month' parameter), or 52 weeks (for the 'week' parameter).

In this example, a subscription named 'My_subscription' will be created with a price of 1000 AED per 1 month, and a recurring payment of the same amount will be charged after 1 month.

Copy example:

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

To charge the subscription payment once every two, three, or four months, pass the interval_count parameter:

stripe_subscription = 'My_subscription'

interval = 'month'

interval_count = 3

payment_sum = 90

To change the subscription payment interval from monthly to weekly, pass the word week in the interval parameter:

stripe_subscription = 'My_subscription'

interval = 'week'

interval_count = 3

payment_sum = 90

After payment, the customer's transaction variables will include stripe_subscription_id, which is needed to configure subscription cancellation, and stripe_customer_id, which can later be used to check the subscription status.

The notification (callback) is only sent for the first recurring payment!

There will be NO callback for subsequent payments. Tracking is done via the function and stripe_customer_id.

Settings to return to regular payments

To return to regular payments, assign an empty string to the subscription variable: stripe_subscription = ''. In this case, the interval and interval_count variables will not affect the link generation.

Settings to cancel a subscription

To cancel a subscription in the calculator, use the method stripe_remove_subscription(stripe_subscription_id), where stripe_subscription_id is the identifier saved in the transaction variables after payment.

This will keep the paid subscription active until the end of the current billing period, but no further charges will occur, and the subscription will be cancelled once the period expires.

answer = stripe_remove_subscription('#{stripe_subscription_id}')

stripe_remove_subscription — on success, returns a response with information about the date until which the cancelled subscription will remain active.

In this example, the result of the function will be stored in the answer variable, allowing you to verify the outcome.

Checking subscription status

stripe_check_subscription(subscription_id, customer_id), where

stripe_subscription_id — subscription identifier stripe_customer_id — customer identifier in Stripe (optional parameter)

How to create a coupon and get a discount ID

To get a discount identifier, create a coupon in your dashboard under the "Coupons" section. ”coupons”.

Clicking the "New" button will open a page where you need to specify:

Name — the discount name;
ID — the identifier, generated automatically;
Type — the discount type: percentage or fixed amount;
Duration — the discount duration (one-time or ongoing, e.g. for subscriptions) and other parameters.

The discount coupon will appear in the "Product catalogue" under the "Coupons" section, and you can view the discount ID by opening the coupon menu.

Click on the coupon to copy the coupon ID.

How to apply a discount to an order

When generating a payment link (works for both subscriptions and one-time payments).

In the block calculator, before declaring the payment_sum variable, set the coupon_id variable and pass the discount identifier from your Stripe dashboard.

To an existing subscription using the stripe_add_subscription_discount function.

Set the trigger conditions for the block and call the specified function in the calculator, passing the stripe_subscription_id (subscription ID) and coupon_id (coupon discount ID) parameters. The discount will be applied to subsequent subscription payments.

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

If the discount is applied successfully, the function will return a message with the subscription ID, discount type, amount or percentage, and expiration date.

How to remove or change a discount for a subscription

A discount attached to a subscription can be removed or replaced with another discount.

To stop a discount, set the trigger conditions for the block and call the stripe_remove_subscription_discount function in the calculator, passing the stripe_subscription_id (subscription ID) parameter.

If the operation is successful, the function will return a message containing the subscription ID and the discount cancellation date.

Replacing a discount, like adding a new one, is done using the stripe_add_subscription_discount function. Make sure to pass the stripe_subscription_id and coupon_id parameters. A successful request will update the coupon attached to the subscription and return a message with the updated details.

How to handle the result

After a successful payment, the bot will receive callbacks that indicate a successful transaction. In the system, these callbacks appear as messages from the user. To prevent users from sending them manually, they consist of the first 20 characters of the secret key followed by _success, for example: sk_live_d35gky6d8ers_success

These callbacks are NOT visible to the user — they are only visible to the operator.

The comparison type must be set to "Exact match".

After a successful payment, the stripe_payment_completed variable is also set to True.

For example, you can handle a successful payment using a conditional block and display the appropriate message to the user.

After the payment is completed, the stripe_callback_data variable will be added to the customer's data, containing the payment system response for the completed transaction. The required data can be extracted from the resulting dictionary using the get method.

To process a repeat payment, you must first reset payment_sum and the previously generated link, and only then reassign the payment_sum variable to get a fresh link. You can use the previous value.

How to test payments

To test the integration, you can use the secret key from the test environment. To do this, switch to the test environment in the Stripe dashboard using the menu on the right.

Then follow the setup steps described at the beginning of this guide. Enter the test secret key and add the webhook URL in the test environment.

For testing, use a test payment card number (you can find the card number for your country on the official Stripe website).