Інтеграція платіжних шлюзів 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 аккаунту та затвердження):

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 комісія знижена. Це потрібно враховувати при виборі провайдера для магазинів у підтримуваних країнах.