Stripe

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

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

Ви можете скопіювати секретний API-ключ, перейшовши до розділу Developers -> API key та скопіювавши Secret key.

Крок 1. Перейдіть до розділу Developers -> API key:

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

Далі потрібно встановити URL для зворотних викликів. Це необхідно для того, щоб бот отримував сповіщення про оплату.

Перейдіть до розділу Webhooks та додайте адресу для вебхуків.

Відкривається форма:

Крок 1. Натисніть "+add destination".

Крок 2. Виберіть події:

Крок 3. Виберіть тип "Webhook endpoint":

Крок 4. Ознайомтеся з типом запиту та натисніть "Continue":

Крок 5. Вкажіть назву та вкажіть URL кінцевої точки:

Вкажіть URL - https://chatter.salebot.pro/stripe_callback/result

Крок 6. Буде створено дві кінцеві точки, ви можете переглянути налаштування перед додаванням:

Крок 7. Далі натисніть кнопку "Add destinations". Після цього вебхуки будуть збережені.

Крок 8. Натисніть кнопку "Done".

Зберігаємо та потрапляємо на сторінку з встановленим вебхуком:

Крок 9. Далі натисніть на вебхук, де ви вибрали всі події:

Крок 10. Знаходимо ключ підпису (Signing key) та зберігаємо його (у майбутньому він знадобиться для підключення до Mavibot):

Після отримання ключів переходимо до підключення до Mavibot.

У Mavibot відкрийте розділ "Acquiring" та виберіть Stripe.

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

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

Готово!

На цьому підключення платіжної системи завершено!

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

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

Вкажіть URL - https://chatter.salebot.pro/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 - 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 рублів (за замовчуванням долар)

Зверніть увагу:
- Спочатку вказуєте необов'язкові параметри first_name, payment_description тощо.
- І останньою присвоюємо значення змінної payment_sum

Змінні можна задати і раніше в ланцюжку, а не в одному блоці, це приклад.

Далі в потрібному місці виводимо змінну stripe_pay_url, яка містить посилання в блоці або в кнопці:

Приклад 1. Виводимо посилання на оплату прямо в повідомленні:

Тестування в боті:

Приклад 2. Додаємо посилання на оплату в кнопку:

Приклад 3. Додаємо посилання як вкладення до повідомлення:

Тестування в боті:

Допустимі всі три варіанти для надсилання посилання на оплату в боті.

При натисканні на кнопку або переході за посиланням вашого платника буде перенаправлено на платіжну сторінку:

У прикладі видно, що параметри, які ми вказували в калькуляторі в налаштуваннях блоку, були застосовані: опис замовлення, валюта та сума.

Якщо передасте параметр податкової ставки (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’.

Важливо! Тривалість одного циклу підписки не може перевищувати 1 рік (для параметра ‘year’), більше 12 місяців (для параметра ‘month’), більше 52 тижнів (для параметра ‘week’).

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'

Важливо! Якщо використовуєте обидві змінні 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' з ціною 90 USD на 3 місяці, і повторний платіж буде здійснено на ту ж суму після цих 1 місяця:

Приклад для копіювання:

stripe_subscription = 'My_subscription'
interval = 'month'
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 - ID підписки
stripe_customer_id - ID клієнта в Stripe (необов'язковий параметр)

Як створити купон та отримати ID знижки

Щоб отримати ID знижки, створіть купон у своєму особистому кабінеті в розділі "coupons". coupons.

Після натискання кнопки "New" відкривається сторінка, де потрібно вказати:

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

Купон на знижку з'явиться в "Product catalog" у розділі "Coupons", і ви можете переглянути ID знижки, перейшовши в меню купона:

Натисніть на купон, щоб скопіювати ID купона:

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

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

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

2. Щоб додати до існуючої підписки за допомогою функції stripe_add_subscription_discount.

Встановіть умови для спрацьовування блоку та викличте вказану функцію в калькуляторі, передавши їй параметри stripe_subscription_id (id підписки) та coupon_id (id купона на знижку). Знижка буде застосована для наступних платежів за підпискою.

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

Після успішного додавання функція повертає повідомлення із зазначенням ID підписки, типу, суми або відсотка знижки, а також дати її закінчення.

Докладніше про створення підписки дивіться в розділі "Як налаштувати рекурентні платежі" Як налаштувати рекурентні платежі

Як видалити/змінити знижку на підписку

Знижку, прикріплену до підписки, можна видалити або замінити іншою знижкою.

Якщо ви хочете припинити дію знижки, встановіть умову для спрацьовування блоку та викличте функцію stripe_remove_subscription_discount у калькуляторі, передавши їй параметр stripe_subscription_id (id підписки).

Після успішного завершення операції функція повертає повідомлення, що містить ID підписки та дату скасування знижки.

Заміна знижки, а також додавання нової здійснюється за допомогою функції stripe_add_subscription_discount. Не забудьте передати їй параметри stripe_subscription_id та coupon_id.
Успішний запит оновить купон, прикріплений до підписки, та поверне повідомлення з актуальною інформацією.

Про те, як отримати ID знижки, можна прочитати в розділі "Як створити купон та отримати ID знижки". Як створити купон та отримати ID знижки.

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

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

Ці зворотні виклики НЕ ВИДНІ користувачеві, вони відображаються лише оператору.

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

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

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

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

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

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

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

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

Номер тестової картки

4242 4242 4242 4242
будь-яка дата в майбутньому
CVC - будь-які три цифри

Якщо щось не працює, порівняйте дані з даними на офіційному сайті. на офіційному сайті.