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. Ви можете відобразити цю змінну як посилання або розмістити на кнопці з текстом "Pay".

Посилання виглядає так:

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

Де знайти податковий 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, значення в них ПОВИННІ БУТИ РІЗНИМИ!

Список значень для 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. Назва — назва знижки;
2. ID — ідентифікатор, генерується автоматично;
3. Тип — тип знижки: відсоток або фіксована сума;
4. Тривалість — тривалість знижки (одноразова або постійна, наприклад, для підписок) та інші параметри.

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

Натисніть на купон, щоб скопіювати ідентифікатор купона.

Як застосувати знижку до замовлення

1. Під час генерації платіжного посилання (працює як для підписок, так і для одноразових платежів).

У калькуляторі блоку перед оголошенням змінної payment_sum встановіть змінну coupon_id та передайте ідентифікатор знижки з вашої панелі керування Stripe.

2. До існуючої підписки за допомогою функції 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).