Интеграция платёжных шлюзов Shopify Payments

Интеграция платёжных шлюзов Shopify Payments

Shopify предоставляет три уровня интеграции платёжных систем: встроенный Shopify Payments (Stripe под капотом), сторонние провайдеры через Shopify Payment Provider API, и ручной редирект через external_payment_gateway. Выбор зависит от юрисдикции и требований провайдера.

Shopify Payments

Shopify Payments доступен в США, Великобритании, ЕС, Австралии и ряде других стран. Для бизнеса из СНГ недоступен. Если магазин находится в поддерживаемой стране — это самый простой вариант: включается в настройках, не требует кода.

Сторонние провайдеры

Для провайдеров, которых нет в официальном списке Shopify, есть два пути.

Hosted payment (редирект) — покупатель редиректится на страницу провайдера. Реализуется через Payment App API (требует Shopify Partner аккаунт и approval):

POST /admin/api/2024-04/payment_sessions.json
{
  "payment_session": {
    "gid": "gid://shopify/PaymentSession/...",
    "payment_method": { "data": { ... } },
    "amount": "150.00",
    "currency": "USD",
    "test": false
  }
}

Через скрипт в теме — более простой, но неофициальный способ: добавить кастомный payment метод через checkout.liquid (доступно только на Shopify Plus). Для обычного плана Shopify — недоступно.

Интеграция через Shopify Payment App API

Полноценный провайдер регистрируется как Shopify App с типом payment:

# 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 Plus: checkout.liquid

На Shopify Plus доступен checkout.liquid — тема checkout. Можно добавить кастомный 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' });
});

Ограничения

Shopify взимает дополнительную комиссию (0.5–2%) при использовании стороннего провайдера вместо Shopify Payments. На Shopify Plus комиссия снижена. Это нужно учитывать при выборе провайдера для магазинов в поддерживаемых странах.