# Stripe ## How to connect To connect Stripe payment system, you will need a secret API key and a webhook key. You can copy the secret API key by going to the Developers -> API key section and copying the Secret key. Step 1. Go to the Developers -> API key section:

Step 2. Find and copy the Secret key:

Next, you need to set the URL for callbacks. This is necessary in order for the bot to receive payment notifications. Go to the Webhooks section and add the address for the webhooks.

The form opens:

Step 1. Click on "+add destination". Step 2. Select events:

Step 3. Select the type of "Webhook endpoint":

Step 4. We get acquainted with the type of request and click "Continue":

Step 5. We write the name and specify the endpoint URL:

Specify URL - Step 6. Two endpoints will be created, you can view the settings before adding:

Step 7. Next, click the "Add destinations" button. Then the webhooks will be saved. Step 8. Click the "Done" button.

We save it and get to the page with the installed webhook:

Step 9. Next, click on the webhook where you have selected all the events:

Step 10. We find the Signig key and save it to ourselves (in the future we will need it to connect to Salebot):

After receiving the keys, we proceed to connect to Mavibot. In Mavibot, open "Acquiring" section and select Stripe.

On the connection page, you need to enter the received keys:

Click "Save Settings". {% hint style="success" %} Done! This completes the connection of the payment system! {% endhint %} ## How to connect a callback about the transaction status To get an additional callback, we will need to connect a webhook in **addition to the existing one.** Specify URL - [https://chatter.salebot.pro/stripe\_callback/\/charge\_status](https://chatter.salebot.pro/stripe_callback//charge_status) and select the events: * `charge.failed` * `charge.pending` * `charge.succeeded`

{% hint style="success" %} **Learn more about each type of webhook:** 1. **charge.succeeded** - contains information about the successful completion of the transaction (similar to a callback about a successful payment) 2. **charge.pending** - "the transaction is in progress", it may take up to 7 days to complete.\ The webhook will look like {first 10 characters }{type of webhook}\ *For example*: *sk\_test\_45LDPJLKT95d\_charge.pending* 3. **charge.failed** *-* "the transaction failed."\ The webhook will look like {first 10 characters }{type of webhook}\ For example: *sk\_test\_45LDPJLKT95d\_charge.failed* {% endhint %} We add the webhook received after saving to Mavibot field - Webhook key2:

**stripe\_invoice\_id** - Transaction ID for which the successful payment callback was not received immediately after the payment. ## How to connect taxes To use taxes in payments, firstly you need to create them in Stripe's personal account. To do this, enter tax rates in the search bar:

And click "+ Add tax rates":

Next, specify the applicable tax rate:

In the opened menu, select the tax type, the region for where it applies, the tax rate, and the option indicating whether this tax should be included in the payment amount 'Inclusive' or will be added in excess of the amount - exclusive:

After creating the tax rate, copy its ID into the **stripe\_tax\_id** variable before setting the payment amount.

To avoid errors, put an empty string ("") in the stripe\_tax\_id variable after receiving the link, so that you can apply the tax only when it is needed. If everything is done correctly, then in the case of the tax rate with the exclusive parameter, you will see the following

Example of a payment with an exclusive tax rate

## **How to get payment link** To generate a payment link, you need to set the value of the **payment\_sum** variable (for example, 150 or 100.55 (separated by a dot!)), and the stripe\_pay\_url variable will appear after that. This variable can be displayed with a link or placed on a button with the text "Pay". The link looks like: `https://checkout.stripe.com/pay/cs_test_a17mskKFFRwEuo3WgBSAUjfk7xaZZIrct9B3Ds2AdODVq1I8aRiqYEBdrU#fidkdWxOYHwnPyd1blpxYHZxWjA0TGFsVzFPVmpmMzJAbVYzUkp1Y0lLYDVgfzR2Q0NxcWZBNUNnTnRSVVRJSGFobEB1UExSczRMMTc8PWRLMGBddl8xalxyPDRoUGhnZm9xXXZANDZyaF0wNTVBVExsPHZyfycpJ2N3amhWYHdzYHcnP3F3cGApJ2lkfGpwcVF8dWAnPyd2bGtiaWBabHFgaCcpJ2BrZGdpYFVpZGZgbWppYWB3dic%2FcXdwYHgl` {% hint style="warning" %} By default, USD (dollar) is set, if you need another currency, you need to set the value of the **currency** variable. {% endhint %} Also, before setting the value of the **payment\_sum** variable, you can set the following optional variables to configure the payment.

Function parameters	Parameters description
currency	is the order currency. Acceptable values -https://stripe.com/docs/currencies
payment_description	order description
stripe_tax_id	This is the tax rate ID, set up in Stripe's personal account. How to set it up is described in the section "How to set taxes" ссылка "Как подключить налоги"
stripe_invoice_enable	This parameter indicates the need to save invoices (invoices,receipts). Enter any value — all necessary documents will then be available in your Stripe personal account.
stripe_locale	set language of the payment link: en, ru, de. All available languages are here: https://stripe.com/docs/api/checkout/sessions/create#create_checkout_session-locale If the stripe_local value is not provided, the client’s browser language will be used by default.
stripe_payment_method_type	is the payment method, the default payment is by card. You can replace it with other payment methods available for Stripe. The available methods are listed below For example, `stripe_payment_method_type = "customer_balance"`
stripe_additional_payment_method_type	is to add an additional payment method. The available methods are listed below for example, `stripe_additional_payment_method_type = "sepa_debit"`
coupon_id	discount coupon ID
stripe_expired	is the lifetime of the payment link. Specified in seconds. The minimum time is 30 minutes, the maximum is 24 hours. The default is 24 hours
stripe_automatic_tax	enabling automatic taxes calculation and collection during payment. To enable it, pass "1". Detailed information about this setting can be found in the Stripe documentation. ссылка в документации Stripe

{% hint style="warning" %} Attention! If you use both ***stripe\_payment\_method\_type** and **stripe\_additional\_payment\_method\_type*** variavles***, then 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

Подробнее про каждый из методов и для каких стран они доступны можно узнать в документации Stripe: [посмотреть на сайте ](https://stripe.com/docs/api/payment_methods/object#payment_method_object-type) ### **Пример формирования ссылки на оплату** Создадим ссылку на оплату в размере 1000 рублей (по умолчанию доллар)

{% hint style="warning" %} **Обратите внимание:** \ \- Сначала указываете необязательные параметры **first\_name, payment\_description** и т.д.\ \- И последней присваиваем значение переменной **payment\_sum** Переменные можно задать и ранее в цепочке, а не в одном блоке, это пример. {% endhint %} Далее в нужном месте выводим переменную **stripe\_pay\_url**, в которой содержится ссылка в блоке либо в кнопке: Пример 1. Выводим ссылку на оплату прямо в сообщении:

Тестирование в боте:

Пример 2. Добавляем ссылку на оплату в кнопку:

Пример 3. Добавляем ссылку в качестве вложения к сообщению:

Тестирование в боте:

{% hint style="success" %} Допустимы все три варианта для направления ссылки на оплату в боте. {% endhint %} При клике на кнопку или при переходе по ссылке, вашего плательщика переадресует на платежную страницу:

В примере видно, что параметры, которые мы указывали в калькуляторе в настройках блока были применены: описание заказа, валюта и сумма. Если передадите параметр налоговой ставки (**stripe\_tax\_id)** в блоке:

То также будет отображена налоговая ставка в форме оплаты:

Пример кода для копирования

`payment_description = 'Тестовая оплата в Страйп'` \ `currency = 'RUB'` \ `stripe_tax_id = 'скопируйте сюда ваш tax ID'` \ `payment_sum = 1000` Где найти tax ID:

## **Как настроить рекуррентные платежи** Для рекуррентных платежей (подписки) нужно до объявления переменной **payment\_sum** объявить переменную **stripe\_subscription** и присвоить ей название подписки. Также можно добавить следующие переменные: \ **interval** – продолжительность интервала подписки, в эту переменную нужно передать значение **‘day’** - для дней, **‘week’** - недель, **‘month’** - месяцев, **‘year’** - лет. \ Если переменная не объявлена, то ***по умолчанию*** будет передан параметр **‘month’.** {% hint style="warning" %} **Важно!** Продолжительность одного цикла подписки не может быть более 1 года (для параметра ‘year’), более 12 месяцев (для параметра ‘month’), более 52 недель (для параметра ‘week’). {% endhint %}

**interval\_count** – количество указанных интервалов, сколько дней, недель или месяцев будет в подписке за указанную сумму. ***По умолчанию*** будет передан параметр, равный единице (**1**); **stripe\_payment\_method\_type** - метод оплаты, по умолчанию стоит оплата картой (card). Можно заменить на другие доступные для Stripe методы оплаты. Ниже указаны доступные методы. Например, `stripe_payment_method_type = 'customer_balance'` **stripe\_additional\_payment\_method\_type** - добавить дополнительный метод оплаты. Ниже указаны доступные методы Например, `stripe_additional_payment_method_type = 'sepa_debit'` {% hint style="warning" %} Важно! Если используете обе переменные ***stripe\_payment\_method\_type** и **stripe\_additional\_payment\_method\_type, то значения в них ОБЯЗАТЕЛЬНО должны быть РАЗНЫМИ!*** {% endhint %}

List of values for stripe_payment_method_type и stripe_additional_payment_method_type:

{% hint style="info" %} For more information about each of the methods and for which countries they are available, see the Stripe documentation: see the website ссылка [посмотреть на сайте ](https://stripe.com/docs/api/payment_methods/object#payment_method_object-type) {% endhint %} {% hint style="warning" %} **Attention!** The subscription duration cannot exceed 1 year (for the ‘year’ parameter), more than 12 months (for the ‘month’ parameter), more than 52 weeks (for the ‘week’ parameter). {% endhint %} In this example, a subscription named 'My\_subscription' will be created with a price of 90 USD for 3 months and a repeat payment will be made with the same amount after these 1 month:

An example to copy: `stripe_subscription = 'My_subscription'` \ `interval = 'month'` \ `interval_count = 3` \ `payment_sum = 90` After payment, the client will have **stripe\_subscription\_id** variables in the deal variables, which will be required 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 received only at the first recurring payment! THERE WILL BE NO callback for repeat calls. The control goes through the function and the stripe\_customer\_id. [через функцию](#proverka-statusa-podpiski) ссылка {% endhint %}

### Returning to regular payments settings To return to regular payments, assign the subscription variable an empty string **stripe\_subscription = "**. In this case, the interval and interval\_count variables will not affect the creation of the link.

### **Cancelling subscription settings** To cancel a subscription in the calculator, use the **stripe\_remove\_subscription(stripe\_subscription\_id)** method, where **stripe\_subscription\_id** is the identifier that was saved in the deal information after payment. This will allow you to keep your paid subscription active until the end of the current paid period, but further charges won't happen, and the subscription will be canceled after the expiration date:

answer = stripe\_remove\_subscription('#{stripe\_subscription\_id}') stripe\_remove\_subscription - On success, you will receive a response with information about the date on which the cancelled subscription remains valid. In this example, the result of the function execution will be placed in the answer variable and it will be possible to check the result of the execution. ### Checking the subscription status **stripe\_check\_subscription(subscription\_id, customer\_id)**, where **stripe\_subscription\_id** - subscription ID \ **stripe\_customer\_id** - client ID in Stripe (optional parameter)

## How to create a coupon and get a discount ID To receive the discount ID, create a coupon in your personal account in the ”coupons” section. ссылка ”[coupons](https://dashboard.stripe.com/coupons)”.

After clicking the “New” button, a page opens where you need to specify: 1. Name — discount name; 2. ID — identifier that is generated automatically. 3. Type — type of discount: percentage or fixed amount 4. Duration — The duration of the discount (one-time or recurring, for example, for subscriptions) and other parameters.

The discount coupon will appear in the “Product catalog“ in the “Coupons” section, and you can view the discount ID by going to the coupon menu:

Click on the coupon to copy the coupon ID:

### How to add a discount to order 1. When generating a payment link (for both subscriptions and one-time payments). In the block’s calculator, before declaring the **payment\_sum** variable, set the **coupon\_id** variable by assigning it the discount ID from Stripe personal account.

2. To add to an existing subscription using the **stripe\_add\_subscription\_discount** function. Set the conditions for triggering the block and call the specified function in the calculator, giving the parameters stripe\_subscription\_id (subscription id) and coupon\_id (discount coupon id) to it. The discount will be applied for subsequent subscription payments.

Пример кода для копирования

`stripe_subscription = 'Подписка премиум'` \ `interval = 'month'` \ `payment_description = 'Тестовая оплата в Страйп'` \ `currency = 'USD'` \ `coupon_id = 'ID вашего купона'` \ `stripe_add_subscription_discount(stripe_subscription_id, coupon_id)` \ `stripe_tax_id = 'ID налога'` \ `payment_sum = 90`

Upon successful addition, the function returns a message indicating the subscription ID, type, amount, or percentage of the discount and also its expiration date.

{% hint style="info" %} For more information about creating a subscription, see the section "How to set up recurring payments" ссылка "[Как настроить рекуррентные платежи](#kak-nastroit-rekurrentnye-platezhi)" {% endhint %} ### How to delete/change the subscription discount The discount attached to the subscription can be deleted or replaced with another discount. If you want to terminate the discount, set a condition for the block to be triggered and call the **stripe\_remove\_subscription\_discount** function in the calculator, giving the **stripe\_subscrition\_id** parameter (subscription id) to it.

Upon successful completion of the operation, the function returns a message containing the subscription ID and the date of cancellation of the discount. The discount replacing, as well as adding a new one is made by using **stripe\_add\_subscription\_discount** function. Don't forget to pass the **stripe\_subscription\_id** and **coupon\_id** parameters to it.\ A successful request will update the coupon attached to the subscription and return a message with current information. {% hint style="info" %} You can read how to get a discount ID in the section "How to create a coupon and get a discount ID". ссылка "[Как создать купон и получить ID скидки](#kak-sozdat-kupon-i-poluchit-id-skidki)". {% endhint %} ## How to process the result After a successful payment, callbacks will be sent to the bot, which will let you know that the payment was successful. You see these callbacks in the system as messages from the user, so that the user cannot send them, they consist of the first 20 characters of the secret key and the success postscript, for example: **sk\_live\_d35gky6d8ers\_success**

These callbacks are NOT VISIBLE TO the user, they are displayed only to the operator. The type of comparison should be "**Exact Match"** Also, after successful payment, the **stripe\_payment\_completed** variable is set to **True.** For example, you can process a successful payment in a conditional block and display the corresponding message to the user:

After the payment is completed, the **stripe\_callback\_data** variable will be added to the client, containing the data of the payment system's response to the completed transaction. You can extract the necessary data from the resulting dictionary using the **get** method. {% hint style="warning" %} To make a repeat payment, you need to reset the payment\_sum, the previously generated link, and then reassign the payment\_sum variable to get a new link. You can specify 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 test mode in Stripe personal account using the toggle in the right menu ![](https://lh5.googleusercontent.com/r-tuJboMES8alkTUpKwA4HKrmL_epNtSXdENrv12EyR9dGCtvRLBK6qw4UGcr59GA3unxc1cV1otCu80nqHEw9VhbEK05ovPQ1Ad8chBv50LAWPO16nEPC2hFhCAsCe3khtBJrob=s0) Next, perform the configuration described at the beginning of this guide. Enter the test secret key and add the webhook address to the testing environment. The test card number 4242 4242 4242 4242\ any date in the future\ CVC - any three numbers If something doesn't work, compare the data with the data on the official website. ссылка[ на официальном сайте.](https://stripe.com/docs/testing#regulatory-cards) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.mavibot.ai/payment/stripe.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.