Stripe
Як підключити
Щоб підключити платіжну систему Stripe, вам знадобляться секретний API-ключ і ключ вебхука.
Ви можете скопіювати секретний API-ключ, перейшовши в розділ Developers -> API key і скопіювавши Secret key.
Крок 1. Перейдіть у розділ Developers -> API key:
Крок 2. Знайдіть і скопіюйте Secret key:
Далі потрібно налаштувати URL для callback-запитів. Це необхідно для того, щоб бот отримував сповіщення про оплату.
Перейдіть у розділ Webhooks і додайте адресу для вебхуків.
Відкриється форма:
Крок 1. Натисніть "+add destination".
Крок 2. Виберіть події:
Крок 3. Виберіть тип "Webhook endpoint":
Крок 4. Ознайомлюємося з типом запиту і натискаємо "Continue":
Крок 5. Вписуємо назву та вказуємо URL endpoint:
Specify URL - https://chatter.salebot.pro/stripe_callback/result
Крок 6. Буде створено два endpoint-и, ви можете переглянути налаштування перед додаванням:
Крок 7. Далі натисніть кнопку "Add destinations". Після цього вебхуки буде збережено.
Крок 8. Натисніть кнопку "Done".
Зберігаємо це і потрапляємо на сторінку з установленим вебхуком:
Крок 9. Далі натисніть на вебхук, де ви вибрали всі події:
Крок 10. Знаходимо Signig key і зберігаємо його собі (у майбутньому він знадобиться для підключення до Salebot):
Після отримання ключів переходимо до підключення в Mavibot.
У Mavibot відкрийте розділ "Acquiring" і виберіть Stripe.
На сторінці підключення потрібно ввести отримані ключі:
Натисніть "Save Settings".
Готово!
На цьому підключення платіжної системи завершено!
Як підключити callback про статус транзакції
Щоб отримати додатковий callback, нам потрібно підключити вебхук у додаток до наявного.
Specify URL - https://chatter.salebot.pro/stripe_callback/<api_key>/charge_status
і виберіть події:
charge.failedcharge.pendingcharge.succeeded
Детальніше про кожен тип вебхука:
charge.succeeded - містить інформацію про успішне завершення транзакції (аналогічно callback про успішну оплату)
charge.pending - "транзакція виконується", її завершення може тривати до 7 днів. Вебхук матиме вигляд {перші 10 символів }{тип вебхука} Наприклад: sk_test_45LDPJLKT95d_charge.pending
charge.failed - "транзакція не вдалася." Вебхук матиме вигляд {перші 10 символів }{тип вебхука} Наприклад: sk_test_45LDPJLKT95d_charge.failed
Додаємо вебхук, отриманий після збереження, у поле Mavibot - Webhook key2:
stripe_invoice_id - 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. Цю змінну можна відобразити у вигляді посилання або розмістити на кнопці з текстом "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
Це ID ставки податку, налаштоване в особистому кабінеті Stripe. Як його налаштувати, описано в розділі "Як налаштувати податки" посилання "Як підключити податки"
stripe_invoice_enable
Цей параметр вказує на необхідність збереження інвойсів (рахунків, квитанцій). Введіть будь-яке значення — тоді всі необхідні документи будуть доступні у вашому особистому кабінеті Stripe.
stripe_locale
встановити мову платіжного посилання: en, ru, de. Усі доступні мови тут: https://stripe.com/docs/api/checkout/sessions/create#create_checkout_session-locale Якщо stripe_local значення не вказано, за замовчуванням буде використано мову браузера клієнта.
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
ID купона зі знижкою
stripe_expired
це строк дії платіжного посилання. Вказується в секундах. Мінімальний час — 30 хвилин, максимальний — 24 години. За замовчуванням — 24 години
stripe_automatic_tax
увімкнення автоматичного розрахунку та стягнення податків під час оплати. Щоб увімкнути, передайте "1". Детальну інформацію про це налаштування можна знайти в документації Stripe. посилання в документації 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 рублів (за замовчуванням долар)
Зверніть увагу: - Спочатку вказуєте необов'язкові параметри 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, то значення в них ОБОВ'ЯЗКОВО мають бути РІЗНИМИ!
Список значень для 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, яку згодом можна використовувати для перевірки статусу підписки.
Сповіщення (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 - ID підписки stripe_customer_id - ID клієнта в Stripe (необов'язковий параметр)
Як створити купон і отримати ID знижки
Щоб отримати ID знижки, створіть купон у своєму особистому кабінеті в розділі ”coupons”. посилання ”coupons».
Після натискання кнопки “New” відкриється сторінка, де потрібно вказати:
Name — назва знижки;
ID — ідентифікатор, який генерується автоматично.
Type — тип знижки: відсоткова або фіксована сума
Duration — тривалість знижки (одноразова або повторювана, наприклад, для підписок) та інші параметри.
Купон зі знижкою з'явиться в “Product catalog“ у розділі “Coupons”, а переглянути ID знижки можна, перейшовши в меню купона:
Натисніть на купон, щоб скопіювати ID купона:
Як додати знижку до замовлення
Під час генерації платіжного посилання (як для підписок, так і для одноразових платежів).
У калькуляторі блоку перед оголошенням payment_sum змінної встановіть coupon_id змінної, присвоївши їй ID знижки з особистого кабінету Stripe.
Щоб додати до наявної підписки за допомогою 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_subscrition_id параметр (ID підписки).
Після успішного виконання операції функція повертає повідомлення, що містить ID підписки та дату скасування знижки.
Заміна знижки, а також додавання нової здійснюється за допомогою stripe_add_subscription_discount функції. Не забудьте передати їй stripe_subscription_id та coupon_id параметри. Успішний запит оновить купон, прив'язаний до підписки, і поверне повідомлення з актуальною інформацією.
Про те, як отримати ID знижки, можна прочитати в розділі "Як створити купон і отримати ID знижки". посилання "Як створити купон і отримати ID знижки".
Як обробити результат
Після успішної оплати в бот надсилатимуться callback-и, які дадуть вам зрозуміти, що оплата була успішною. Ви бачите ці callback-и в системі як повідомлення від користувача, тому, щоб користувач не міг їх надсилати, вони складаються з перших 20 символів секретного ключа та постскрипту про успіх, наприклад: sk_live_d35gky6d8ers_success
Ці колбеки НЕ ВИДИМІ для користувача, вони відображаються лише оператору.
Тип порівняння має бути "Exact Match"
Також після успішної оплати stripe_payment_completed змінна встановлюється в True.
Наприклад, ви можете обробити успішний платіж у умовному блоці та відобразити відповідне повідомлення користувачеві:
Після завершення платежу stripe_callback_data змінна буде додана до клієнта, міститиме дані відповіді платіжної системи на завершену транзакцію. Ви можете отримати потрібні дані з отриманого словника за допомогою get методу.
Щоб виконати повторний платіж, потрібно скинути payment_sum, попередньо згенероване посилання, а потім знову присвоїти змінну payment_sum, щоб отримати нове посилання. Ви можете вказати попереднє значення.
Як тестувати платежі
Щоб протестувати інтеграцію, ви можете використовувати секретний ключ із тестового середовища. Для цього перемкніться в тестовий режим в особистому кабінеті Stripe за допомогою перемикача в правому меню
Далі виконайте налаштування, описане на початку цього посібника. Введіть тестовий секретний ключ і додайте адресу вебхука до тестового середовища.
Тестовий номер картки
4242 4242 4242 4242 будь-яка дата в майбутньому CVC - будь-які три цифри
Якщо щось не працює, звірте дані з даними на офіційному сайті. посилання на офіційному сайті.
Останнє оновлення