Как подключиться

Для подключения платежной системы Stripe вам понадобится секретный API-ключ и ключ вебхука.

Секретный API-ключ можно скопировать, перейдя в раздел Developers → API keys и скопировав Secret key.

Шаг 1. Перейдите в раздел Developers → API keys:

Шаг 2. Найдите и скопируйте Secret key:

Далее необходимо настроить callback-URL. Это позволит боту получать уведомления об оплате.

Перейдите в раздел Webhooks и добавьте URL вебхука.

Появится форма.

Шаг 3. Нажмите "+add destination".

Шаг 4. Выберите события.

Шаг 3. Выберите тип "Webhook endpoint".

Шаг 4. Проверьте тип запроса и нажмите "Continue".

Шаг 5. Введите имя и укажите URL конечной точки.

Установите URL: https://chatter.mavibot.ai/stripe_callback/result

Шаг 6. Будут созданы две конечные точки — вы можете просмотреть настройки перед их добавлением.

Шаг 7. Нажмите кнопку "Add destinations". Вебхуки будут сохранены.

Шаг 8. Нажмите "Done".

Сохраните, и вы будете перенаправлены на страницу с настроенным вебхуком.

Шаг 9. Нажмите на вебхук, в котором вы выбрали все события.

Шаг 10. Найдите Signing key и сохраните его (он понадобится вам позже для подключения к MaviBot).

После получения ключей переходите к подключению в Mavibot.

В Mavibot откройте раздел "Эквайринг" и выберите Stripe.

На странице подключения введите полученные ключи.

Нажмите "Сохранить настройки".

Готово! Вы подключили Stripe.

Как подключить callback статуса транзакции

Чтобы получать дополнительный callback, необходимо добавить второй вебхук рядом с существующим.

Установите URL: https://chatter.mavibot.ai/stripe_callback/<api_key>/charge_status

и выберите следующие события:

  • charge.failed
  • charge.pending
  • charge.succeeded

Подробнее о каждом типе вебхука:

  1. charge.succeeded — содержит информацию об успешно завершенной транзакции (аналогично callback успешного платежа)
  2. charge.pending — "транзакция в обработке", может занимать до 7 дней. Вебхук будет иметь формат {первые 10 символов}{тип вебхука}. Например: sk_test_45LDPJLKT95d_charge.pending
  3. charge.failed — "транзакция не удалась". Вебхук будет иметь формат {первые 10 символов}{тип вебхука}. Например: sk_test_45LDPJLKT95d_charge.failed

Добавьте ключ вебхука, полученный после сохранения, в поле Mavibot — Webhook key2.

stripe_invoice_id — идентификатор транзакции, для которой callback успешного платежа не был получен сразу после оплаты.

Как настроить налоги

Чтобы использовать налоги в платежах, сначала необходимо создать их в панели управления Stripe. Для этого введите "tax rates" в строке поиска:

И нажмите "+ Add tax rates".

Затем введите применимую налоговую ставку.

В открывшемся меню выберите тип налога, регион, к которому он применяется, процентную ставку, а также будет ли налог включен в сумму платежа (Inclusive) или добавлен к ней (Exclusive).

После создания налоговой ставки скопируйте ее ID в переменную stripe_tax_id перед объявлением суммы платежа.

Чтобы избежать ошибок, рекомендуется установить переменную stripe_tax_id в пустую строку ("") после получения ссылки — таким образом вы сможете применять налог только при необходимости.

Если все сделано правильно, в случае налоговой ставки с параметром exclusive вы увидите следующее:

Как получить платежную ссылку

Чтобы сгенерировать платежную ссылку, установите значение переменной payment_sum (например, 150 или 100.55 — используйте точку, а не запятую!). После этого появится переменная stripe_pay_url. Вы можете отобразить эту переменную как ссылку или разместить ее на кнопке с текстом "Оплатить".

Ссылка выглядит так:

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

По умолчанию валюта установлена на USD. Чтобы использовать другую валюту, установите значение переменной currency.

Вы также можете установить следующие необязательные переменные перед установкой значения payment_sum для настройки платежа.

Параметры функции Описание параметра
currency валюта заказа. Допустимые значения здесь — https://stripe.com/docs/currencies
payment_description описание платежа
stripe_tax_id идентификатор налоговой ставки, настроенной в вашей панели управления Stripe.
Инструкции по настройке приведены в разделе "Как настроить налоги".
stripe_invoice_enable флаг для включения сохранения счетов (квитанций). Установите любое значение, чтобы включить эту функцию — все соответствующие документы будут доступны в вашей панели управления Stripe.
stripe_locale

установите язык платежной страницы: en, de и т.д. Все доступные варианты: https://stripe.com/docs/api/checkout/sessions/create#create_checkout_session-locale

Если stripe_locale не установлен, будет использоваться язык браузера клиента.
stripe_payment_method_type способ оплаты; по умолчанию используется оплата картой. Может быть заменен на другие способы оплаты, доступные в Stripe. Доступные методы перечислены ниже. Например, stripe_payment_method_type = "customer_balance"
stripe_additional_payment_method_type добавить дополнительный способ оплаты. Доступные методы перечислены ниже. Например, stripe_additional_payment_method_type = "sepa_debit"
coupon_id идентификатор купона на скидку
stripe_expired время истечения платежной ссылки. Указывается в секундах. Минимум — 30 минут, максимум — 24 часа. По умолчанию — 24 часа.
stripe_automatic_tax включить автоматический расчет и сбор налога при оформлении заказа. Передайте "1", чтобы включить. Для получения дополнительной информации обратитесь к статьям Stripe.

Важно! Если вы используете обе переменные stripe_payment_method_type и stripe_additional_payment_method_type, значения в них должны быть разными!

Список значений для stripe_payment_method_type и 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

Пример генерации платежной ссылки

Давайте создадим платежную ссылку на 1000 AED (валюта по умолчанию — USD).

Примечание:

— Сначала укажите необязательные параметры, такие как first_name, payment_description и т.д.

— Затем присвойте значение переменной payment_sum последней.

Переменные также могут быть установлены ранее в цепочке, не обязательно в том же блоке — это всего лишь пример.

Затем отобразите переменную stripe_pay_url, содержащую ссылку, в нужном месте — либо в блоке сообщения, либо на кнопке:

Пример 1. Отображение платежной ссылки непосредственно в сообщении:

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

При нажатии на кнопку или переходе по ссылке ваш плательщик будет перенаправлен на страницу оплаты.

Пример показывает, что параметры, которые мы указали в калькуляторе в настройках блока, были применены: описание заказа, валюта и сумма.

Если вы передаете параметр налоговой ставки (stripe_tax_id) в блоке.

Налоговая ставка также будет отображаться в платежной форме.

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

payment_description = "test payment"

currency = 'AED'

stripe_tax_id = 'enter_your_stripe_id_tax'

payment_sum = 1000

Где найти идентификатор налога.

Как настроить регулярные платежи

Для регулярных платежей (подписок) объявите переменную stripe_subscription перед переменной payment_sum и присвойте ей название подписки.

Вы также можете добавить следующие переменные: interval — продолжительность интервала подписки. Передайте 'day' для дней, 'week' для недель, 'month' для месяцев или 'year' для лет. Если переменная не установлена, по умолчанию будет использоваться 'month'.

Важно!

Продолжительность одного цикла подписки не может превышать 1 год (для параметра 'year'), 12 месяцев (для параметра 'month') или 52 недели (для параметра 'week').

interval_count — количество указанных интервалов: сколько дней, недель или месяцев включено в подписку за данную сумму. По умолчанию — 1.

stripe_payment_method_type — способ оплаты; по умолчанию используется оплата картой. Может быть заменен на другие способы оплаты, доступные в Stripe. Доступные методы перечислены ниже.

Например, stripe_payment_method_type = 'customer_balance'

stripe_additional_payment_method_type — добавление дополнительного способа оплаты. Доступные способы перечислены ниже.

Например, stripe_additional_payment_method_type = 'sepa_debit'

Важно! Если вы используете обе переменные stripe_payment_method_type и stripe_additional_payment_method_type, значения в них ДОЛЖНЫ быть РАЗНЫМИ!

Список значений для stripe_payment_method_type и 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.

Важно!

Продолжительность одного цикла подписки не может превышать 1 год (для параметра 'year'), 12 месяцев (для параметра 'month') или 52 недели (для параметра 'week').

В этом примере будет создана подписка с именем 'My_subscription' по цене 1000 AED за 1 месяц, и через 1 месяц будет списан регулярный платеж на ту же сумму.

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

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

Чтобы списывать платеж по подписке раз в два, три или четыре месяца, передайте параметр interval_count:

stripe_subscription = 'My_subscription'

interval = 'month'

interval_count = 3

payment_sum = 90

Чтобы изменить интервал платежей по подписке с ежемесячного на еженедельный, передайте слово week в параметре interval:

stripe_subscription = 'My_subscription'

interval = 'week'

interval_count = 3

payment_sum = 90

После оплаты в переменные транзакции клиента будут добавлены stripe_subscription_id, необходимый для настройки отмены подписки, и stripe_customer_id, который впоследствии можно использовать для проверки статуса подписки.

Уведомление (callback) отправляется только для первого регулярного платежа!

Для последующих платежей callback НЕ будет. Отслеживание осуществляется с помощью функции и stripe_customer_id.

Настройки для возврата к обычным платежам

Чтобы вернуться к обычным платежам, присвойте переменной subscription пустую строку: stripe_subscription = ''. В этом случае переменные interval и interval_count не будут влиять на генерацию ссылки.

Настройки для отмены подписки

Чтобы отменить подписку в калькуляторе, используйте метод stripe_remove_subscription(stripe_subscription_id), где stripe_subscription_id — это идентификатор, сохраненный в переменных транзакции после оплаты.

Это позволит сохранить оплаченную подписку активной до конца текущего расчетного периода, но дальнейших списаний не будет, и подписка будет отменена по истечении этого периода.

answer = stripe_remove_subscription('#{stripe_subscription_id}')

stripe_remove_subscription — в случае успеха возвращает ответ с информацией о дате, до которой отмененная подписка будет оставаться активной.

В этом примере результат функции будет сохранен в переменной answer, что позволит вам проверить результат.

Проверка статуса подписки

stripe_check_subscription(subscription_id, customer_id), где

stripe_subscription_id — идентификатор подписки stripe_customer_id — идентификатор клиента в Stripe (необязательный параметр)

Как создать купон и получить идентификатор скидки

Чтобы получить идентификатор скидки, создайте купон в панели управления в разделе «Купоны». »coupons.

Нажатие кнопки «Новый» откроет страницу, где необходимо указать:

  1. Name — название скидки;
  2. ID — идентификатор, генерируется автоматически;
  3. Type — тип скидки: процентная или фиксированная сумма;
  4. Duration — продолжительность скидки (однократная или постоянная, например, для подписок) и другие параметры.

Купон на скидку появится в «Каталоге продуктов» в разделе «Купоны», и вы сможете просмотреть идентификатор скидки, открыв меню купона.

Нажмите на купон, чтобы скопировать идентификатор купона.

Как применить скидку к заказу

  1. При генерации платежной ссылки (работает как для подписок, так и для разовых платежей).

В калькуляторе блока перед объявлением переменной payment_sum установите переменную coupon_id и передайте идентификатор скидки из панели управления Stripe.

  1. К существующей подписке с помощью функции stripe_add_subscription_discount.

Установите условия срабатывания блока и вызовите указанную функцию в калькуляторе, передав параметры stripe_subscription_id (идентификатор подписки) и coupon_id (идентификатор купона со скидкой). Скидка будет применена к последующим платежам по подписке.

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

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

Если скидка применена успешно, функция вернет сообщение с идентификатором подписки, типом скидки, суммой или процентом и датой истечения срока действия.

Как удалить или изменить скидку для подписки

Скидку, привязанную к подписке, можно удалить или заменить другой скидкой.

Чтобы отменить скидку, установите условия срабатывания блока и вызовите функцию stripe_remove_subscription_discount в калькуляторе, передав параметр stripe_subscription_id (идентификатор подписки).

В случае успеха функция вернет сообщение, содержащее идентификатор подписки и дату отмены скидки.

Замена скидки, как и добавление новой, выполняется с помощью функции stripe_add_subscription_discount. Обязательно передайте параметры stripe_subscription_id и coupon_id. Успешный запрос обновит купон, привязанный к подписке, и вернет сообщение с обновленными данными.

Как обработать результат

После успешной оплаты бот получит callbacks, которые указывают на успешную транзакцию. В системе эти callbacks отображаются как сообщения от пользователя. Чтобы пользователи не могли отправлять их вручную, они состоят из первых 20 символов секретного ключа, за которыми следует _success, например: sk_live_d35gky6d8ers_success

Эти callbacks НЕ видны пользователю — они видны только оператору.

Тип сравнения должен быть установлен на «Точное совпадение».

После успешной оплаты переменная stripe_payment_completed также устанавливается в True.

Например, вы можете обработать успешную оплату с помощью условного блока и отобразить соответствующее сообщение пользователю.

После завершения оплаты в данные клиента будет добавлена переменная stripe_callback_data, содержащая ответ платежной системы о выполненной транзакции. Необходимые данные можно извлечь из полученного словаря с помощью метода get.

Для обработки повторного платежа необходимо сначала сбросить payment_sum и ранее сгенерированную ссылку, и только затем повторно присвоить переменной payment_sum значение, чтобы получить новую ссылку. Вы можете использовать предыдущее значение.

Как тестировать платежи

Для тестирования интеграции вы можете использовать секретный ключ из тестовой среды. Для этого переключитесь на тестовую среду в панели управления Stripe с помощью меню справа.

Затем выполните шаги настройки, описанные в начале этого руководства. Введите тестовый секретный ключ и добавьте URL вебхука в тестовой среде.

Для тестирования используйте номер тестовой платежной карты (номер карты для вашей страны можно найти на официальном сайте Stripe).