Shopify Payments Gateway Integration

Shopify Payments Gateway Integration

Shopify provides three integration levels for payment systems: built-in Shopify Payments (Stripe underneath), third-party providers via Shopify Payment Provider API, and manual redirect via external_payment_gateway. Choice depends on jurisdiction and provider requirements.

Shopify Payments

Shopify Payments available in USA, UK, EU, Australia and some other countries. For CIS businesses unavailable. If store in supported country — simplest option: enabled in settings, requires no code.

Third-Party Providers

For providers not in official Shopify list, two paths.

Hosted payment (redirect) — customer redirected to provider page. Implemented via Payment App API (requires Shopify Partner account and 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
  }
}

Via script in theme — simpler but unofficial: add custom payment method via checkout.liquid (only on Shopify Plus). For regular Shopify plan — unavailable.

Integration via Shopify Payment App API

Full provider registered as Shopify App with type 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"

Payment creation 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',
    });
});

After payment — callback to confirmation_callback_url, where status confirmed back to 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

On Shopify Plus available checkout.liquid — checkout theme. Can add custom payment option via JavaScript. Violates standard flow and complicates theme updates, but sometimes only option for specific providers.

Refunds

Refunds in Shopify auto call refund_session_url of provider. Handler must initiate refund in payment system and return status:

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' });
});

Limitations

Shopify charges additional commission (0.5–2%) when using third-party provider instead of Shopify Payments. On Shopify Plus commission reduced. Must account when choosing provider for stores in supported countries.