Stripe

Як підключити

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

Секретний API-ключ можна скопіювати, перейшовши в Developers → API keys та скопіювавши Secret key.

Крок 1. Перейдіть в Developers → API keys:

Крок 2. Знайдіть та скопіюйте Secret key:

Далі потрібно встановити 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 відкрийте розділ "Acquiring" та виберіть Stripe.

На сторінці підключення введіть отримані ключі.

Натисніть "Save settings".

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

Як підключити зворотний виклик статусу транзакції

Щоб отримувати додатковий зворотний виклик, потрібно додати другий вебхук поруч із наявним.

Встановіть URL: https://chatter.mavibot.ai/stripe\\_callback/\\<api_key>/charge_status

та виберіть наступні події:

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

Детальніше про кожен тип вебхука:

1. charge.succeeded — містить інформацію про успішно завершену транзакцію (аналогічно зворотному виклику успішного платежу)
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 — ідентифікатор транзакції, для якої не було отримано зворотного виклику успішного платежу одразу після оплати.

Як налаштувати податки

Щоб використовувати податки в платежах, спочатку потрібно створити їх у вашій панелі 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, який згодом можна використовувати для перевірки статусу підписки.

Сповіщення (зворотний виклик) надсилається лише для першого регулярного платежу!

Для наступних платежів зворотного виклику НЕ БУДЕ. Відстеження здійснюється за допомогою функції та 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.

2. До існуючої підписки за допомогою функції 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. Успішний запит оновить купон, прив'язаний до підписки, та поверне повідомлення з оновленими даними.

Як обробити результат

Після успішної оплати бот отримає зворотні виклики, які вказують на успішну транзакцію. У системі ці зворотні виклики відображаються як повідомлення від користувача. Щоб запобігти їх ручному надсиланню користувачами, вони складаються з перших 20 символів секретного ключа, за якими слідує _success, наприклад: sk_live_d35gky6d8ers_success

Ці зворотні виклики НЕ видимі для користувача — вони видимі лише для оператора.

Тип порівняння має бути встановлений як "Точний збіг".

Після успішної оплати також встановлюється змінна stripe_payment_completed у значення True.

Наприклад, ви можете обробити успішний платіж за допомогою умовного блоку та відобразити відповідне повідомлення користувачеві.

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

Щоб обробити повторний платіж, спочатку потрібно скинути payment_sum та раніше згенероване посилання, і лише потім знову призначити змінну payment_sum, щоб отримати нове посилання. Ви можете використовувати попереднє значення.

Як тестувати платежі

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

Потім виконайте кроки налаштування, описані на початку цього посібника. Введіть тестовий секретний ключ та додайте URL вебхука в тестовому середовищі.

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