Інтеграція платіжних шлюзів Shopify
При виборі платіжного шлюзу для Shopify-магазину часто виникає дилема: вбудований Shopify Payments не підтримує потрібну країну, а сторонні провайдери вимагають складної інтеграції та спричиняють додаткову комісію до 2%. Ми вирішували це завдання для 50+ магазинів — від локальних брендів до enterprise-проєктів. У цій статті розберемо всі рівні інтеграції, порівняємо їх за складністю та витратами, а також покажемо реальний приклад підключення кастомного шлюзу.
Чому варто обирати Shopify Payments?
Shopify Payments — вбудоване рішення на базі Stripe. Воно доступне в США, Великобританії, ЄС, Австралії та ряді інших країн, але недоступне для бізнесу з СНД. Якщо ваш магазин зареєстрований у підтримуваній країні, це найпростіший варіант: вмикається в налаштуваннях однією галочкою, не вимагає коду та не спричиняє додаткових комісій. Комісія за транзакцію стандартна — близько 2.9% + фіксована сума (наприклад, $0.30).
Як інтегрувати сторонній платіжний шлюз?
Для провайдерів, яких немає в офіційному списку Shopify, є два основні шляхи: hosted-редирект і повноцінна інтеграція через Shopify Payment Provider API. Вибір залежить від вимог до UX та необхідності автоматизації повернень.
Згідно з документацією Shopify, hosted-редирект реалізується через Payment App API та вимагає Shopify Partner акаунта.
Hosted-редирект (швидкий старт)
Покупець редиректиться на сторінку провайдера для оплати. Реалізується через Payment App API. Потрібен Shopify Partner акаунт та approval застосунку. Приклад конфігурації:
# shopify.app.toml [payment_gateway_integration] merchant_label = "MyPay" supports_oversell_protection = false supports_3ds = true confirmation_callback_url = "https://app.example.com/shopify/confirm" payment_session_url = "https://app.example.com/shopify/payment" refund_session_url = "https://app.example.com/shopify/refund" void_session_url = "https://app.example.com/shopify/void" Endpoint створення платежу:
// POST /shopify/payment app.post('/shopify/payment', async (req, res) => { const { id, gid, amount, currency, customer_locale, payment_method } = req.body; const payment = await myPayClient.createPayment({ amount: parseFloat(amount), currency, reference: id, redirect_url: `https://app.example.com/shopify/return?session=${id}`, }); res.json({ payment_method: { data: { payment_method } }, redirect_url: payment.checkout_url, status: 'redirecting', }); }); Після оплати — callback на confirmation_callback_url, де статус підтверджується назад у Shopify:
app.post('/shopify/confirm', async (req, res) => { const session = await getSession(req.body.id); const paymentStatus = await myPayClient.getStatus(session.payment_id); res.json({ status: paymentStatus === 'paid' ? 'success' : 'failure', }); }); Повноцінний кастомний шлюз (Shopify Payment Provider API)
Цей підхід дає повний контроль над процесом оплати та автоматичні повернення. Реєструється як Shopify App з типом payment. Ми використовуємо його для складних інтеграцій з банками, криптовалютними платіжками та локальними системами. Hosted-редирект у 2 рази швидший у реалізації, ніж повноцінний Payment Provider API, але останній забезпечує безшовний UX та автоматичні повернення.
Порівняння варіантів інтеграції
| Критерій | Shopify Payments | Hosted-редирект | Payment Provider API |
|---|---|---|---|
| Складність | Мінімальна | Середня | Висока |
| Комісія Shopify | 0% додаткової | 0.5–2% | 0.5–2% |
| Повернення | Автоматичні | Ручні | Автоматичні |
| Підтримка країн | Обмежена | Будь-яка | Будь-яка |
| Кастомізація | Немає | Обмежена | Повна |
| Час реалізації | 1–2 дні | 1–2 тижні | 2–4 тижні |
Що входить у нашу роботу з інтеграції
- Аналіз вимог: юрисдикція, валюта, необхідні функції (рекурентні платежі, 3DS, множинні валюти)
- Проектування архітектури: вибір підходу, розробка схеми взаємодії з платіжним провайдером
- Реєстрація Shopify Partner акаунта та створення застосунку з типом payment
- Розробка endpoints: створення платежу, підтвердження, повернення, скасування
- Налаштування webhooks та колбеків для синхронізації статусів
- Інтеграція з темою Shopify: кастомні блоки, якщо потрібно (тільки Shopify Plus)
- Тестування у пісочниці та продакшені: 3DS, таймаути, подвійні списання
- Документація для вашої команди та навчання співробітників
- Гарантія підтримки протягом 30 днів після запуску
Типові помилки при інтеграції
- Неправильний формат URL колбеків — Shopify вимагає HTTPS та певні gid
- Відсутність обробки помилок у endpoints — повернення 500 замість коректного статусу failure
- Некоректна конфігурація 3DS: не всі провайдери підтримують, потрібно налаштовувати флаг
supports_3ds - Забувають про void-запити при скасуванні замовлення — це може призвести до блокування коштів
Деталі обробки void-запитів
При скасуванні замовлення до підтвердження платежу Shopify надсилає запит на void_session_url. Обробник має скасувати платіж у платіжній системі, інакше кошти можуть бути заблоковані на кілька днів. Типова помилка — не реалізувати цей endpoint, що призводить до затримок повернення.
Процес роботи з нашою командою
- Аналітика — вивчаємо ваш магазин, аудит поточного рішення, визначаємо вимоги
- Проектування — обираємо шлюз, малюємо схему, погоджуємо терміни
- Реалізація — розробляємо застосунок, endpoints, тестуємо в Staging
- Тестування — проводимо навантажувальне тестування, перевіряємо повернення та 3DS
- Деплой — публікуємо застосунок у Shopify App Store (якщо потрібно), налаштовуємо продакшен
- Підтримка — моніторинг, виправлення багів, консультації. Досвід наших інженерів — 8+ років у веб-розробці
Shopify Plus: checkout.liquid
На Shopify Plus доступний checkout.liquid — можна додати кастомний payment option через JavaScript. Це порушує стандартний flow та ускладнює оновлення теми, але іноді єдиний варіант для специфічних провайдерів. Ми використовуємо цей підхід тільки коли інші варіанти неможливі, і завжди супроводжуємо докладною документацією.
Як автоматизувати повернення?
Повернення в Shopify автоматично викликають refund_session_url провайдера. Обробник має ініціювати повернення в платіжній системі та повернути статус:
app.post('/shopify/refund', async (req, res) => { const { id, payment_id, amount, currency } = req.body; await myPayClient.refund(payment_id, { amount: parseFloat(amount), currency }); res.json({ status: 'success' }); }); При автоматизації повернень час обробки скорочується з 2 днів до 5 хвилин. Це критично для магазинів з високим обсягом повернень. Середня економія на операційних витратах становить до $500 на місяць.
Обмеження та комісії
Shopify стягує додаткову комісію (0.5–2%) при використанні стороннього провайдера замість Shopify Payments. На Shopify Plus комісія знижена. Це потрібно враховувати при виборі провайдера для магазинів у підтримуваних країнах. Якщо Shopify Payments недоступний, комісія неминуча, але ми допомагаємо мінімізувати її правильним вибором провайдера — наприклад, через Stripe Connect, який дозволяє знизити комісію до 1.5%.
Зв'яжіться з нами для оцінки вашого проєкту. Ми запропонуємо оптимальне рішення та розрахуємо терміни інтеграції — від двох тижнів до місяця залежно від складності. Отримайте консультацію безкоштовно.