Интеграция платёжных шлюзов 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%.
Свяжитесь с нами для оценки вашего проекта. Мы предложим оптимальное решение и рассчитаем сроки интеграции — от двух недель до месяца в зависимости от сложности. Получите консультацию бесплатно.