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

Для подключения платежной системы 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 для настройки платежа.

Важно! Если вы используете обе переменные 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

Где найти ID налога.

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

Для регулярных платежей (подписок) объявите переменную 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, значения в них ДОЛЖНЫ быть РАЗНЫМИ!

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.

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

Чтобы вернуться к обычным платежам, присвойте переменной подписки пустую строку: 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 (необязательный параметр)

Как создать купон и получить ID скидки

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

Нажатие кнопки "New" откроет страницу, где необходимо указать:

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

Купон на скидку появится в "Product catalogue" в разделе "Coupons", и вы можете просмотреть ID скидки, открыв меню купона.

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

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

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

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

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

Установите условия триггера для блока и вызовите указанную функцию в калькуляторе, передав параметры stripe_subscription_id (ID подписки) и coupon_id (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

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

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

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

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

Если операция выполнена успешно, функция вернет сообщение, содержащее 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).