> For the complete documentation index, see [llms.txt](https://docs.mavibot.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mavibot.ai/integrations/payment/stripe.md). # 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: 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". {% hint style="success" %} Done! You have connected Stripe. {% endhint %} ## 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: \/charge\_status and select the following events: * `charge.failed` * `charge.pending` * `charge.succeeded`

{% hint style="success" %} More details on each webhook type: 1. `charge.succeeded` — contains information about a successfully completed transaction (similar to the successful payment callback) 2. `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 3. `charge.failed` — "transaction failed". The webhook will have the format {first 10 characters}{webhook type} For example: sk\_test\_45LDPJLKT95d\_charge.failed {% endhint %} 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` {% hint style="warning" %} By default, the currency is set to USD. To use a different currency, set the value of the currency variable. {% endhint %} You can also set the following optional variables before setting the payment\_sum value to configure the payment.

Параметры функции	Описание паараметра
currency	order currency. Allowed values are here —https://stripe.com/docs/currencies
payment_description	payment description
stripe_tax_id	tax rate identifier configured in your Stripe dashboard. Setup instructions are provided in the "How to set up taxes" section.
stripe_invoice_enable	flag to enable saving invoices (receipts). Set any value to enable this — all relevant documents will be available in your Stripe dashboard.
stripe_locale	set the language of the payment page: en, de, etc. All available options: https://stripe.com/docs/api/checkout/sessions/create#create_checkout_session-locale If stripe_locale is not set, the customer's browser language will be used.
stripe_payment_method_type	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"`
coupon_id	discount coupon identifier
stripe_expired	payment link expiration time. Specified in seconds. Minimum is 30 minutes, maximum is 24 hours. Default is 24 hours.
stripe_automatic_tax	enable automatic tax calculation and collection at checkout. Pass "1" to enable. For more details, refer to the Stripe articles.

{% hint style="warning" %} Important! If you use both stripe\_payment\_method\_type and stripe\_additional\_payment\_method\_type variables, the values in them must be different! {% endhint %}

List of values for stripe_payment_method_type and stripe_additional_payment_method_type

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

{% hint style="info" %} [For more details on each method and the countries where they are available, refer to the Stripe documentation](https://stripe.com/docs/api/payment_methods/object#payment_method_object-type) {% endhint %} ### Payment link generation example Let's create a payment link for 1000 AED (the default currency is USD).

{% hint style="warning" %} 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. {% endhint %} 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.

Code example to copy

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. {% hint style="warning" %} 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). {% endhint %}

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'` {% hint style="warning" %} Important! If you use both stripe\_payment\_method\_type and stripe\_additional\_payment\_method\_type variables, the values in them MUST be DIFFERENT! {% endhint %}

List of values for stripe_payment_method_type and stripe_additional_payment_method_type:

{% hint style="info" %} [For more details on each method and the countries where they are available, refer to the Stripe documentation](https://stripe.com/docs/api/payment_methods/object#payment_method_object-type). {% endhint %} {% hint style="warning" %} 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). {% endhint %} 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. {% hint style="warning" %} 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. {% endhint %}

## 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](https://dashboard.stripe.com/coupons)”.

Clicking the "New" button will open a page where you need to specify: 1. Name — the discount name; 2. ID — the identifier, generated automatically; 3. Type — the discount type: percentage or fixed amount; 4. 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 1. 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.

2. 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.

Code example to copy

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. {% hint style="warning" %} 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. {% endhint %} ## 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. ![](https://lh5.googleusercontent.com/r-tuJboMES8alkTUpKwA4HKrmL_epNtSXdENrv12EyR9dGCtvRLBK6qw4UGcr59GA3unxc1cV1otCu80nqHEw9VhbEK05ovPQ1Ad8chBv50LAWPO16nEPC2hFhCAsCe3khtBJrob=s0) 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](https://stripe.com/docs/testing#regulatory-cards)).