# Kaspi Pay интеграция с Shopify

> Честный разбор: приложения Qut Pay в Shopify App Store нет, и Shopify не даёт магазину добавить произвольный платёжный шлюз. Что работает сегодня — ручной способ оплаты плюс ссылка Qut Pay, свой небольшой бэкенд с webhook и Admin API, и где границы.

## Коротко

Готового приложения Qut Pay для Shopify нет, и «вставить» Kaspi QR в стандартный checkout Shopify нельзя: платформа принимает сторонние шлюзы только через свою программу Payments Apps для одобренных партнёров, а магазину произвольный шлюз добавить не даёт. Что реально работает сегодня: в Shopify включаете **ручной способ оплаты** («Manual payment method», например «Kaspi QR»), а оплату принимаете через Qut Pay — по постоянной ссылке или по счёту, который создаёт ваш небольшой бэкенд. Заказ отмечается оплаченным либо вручную по журналу в кабинете, либо автоматически: webhook `invoice.paid` приходит на ваш бэкенд, и тот закрывает заказ через Shopify Admin API. Автоматический шаг «оплатить Kaspi QR» внутри самого checkout Shopify при этом не появится.

## Что можно и чего нельзя

| Задача | Возможно? | Как |
|---|---|---|
| Кнопка Kaspi QR среди способов оплаты в checkout Shopify | Нет | Только через программу Payments Apps Shopify, в ней Qut Pay не участвует |
| Принять Kaspi QR по заказу из Shopify | Да | Ручной способ оплаты + ссылка или счёт Qut Pay |
| Автоматически пометить заказ оплаченным | Да, с разработчиком | Webhook Qut Pay → ваш бэкенд → Shopify Admin API |
| Продажи вне Shopify checkout | Да | Ссылка на оплату `qut.kz/p/<slug>` в описании товара, в переписке, в Instagram |

## Вариант A — ручной способ оплаты + ссылка (без кода)

1. В админке Shopify: Settings → Payments → Manual payment methods → добавьте способ «Kaspi QR». В инструкции покупателю напишите, что ссылка на оплату придёт после оформления.
2. В кабинете Qut Pay создайте [постоянную ссылку на оплату](/kb/ru/payment-links) с открытой суммой — или выставляйте счёт на каждый заказ вручную.
3. Отправьте покупателю ссылку (письмо подтверждения заказа, WhatsApp). Он платит, деньги приходят на ваш Kaspi Pay.
4. Увидев оплату в кабинете, нажмите «Mark as paid» у заказа в Shopify.

Подходит для небольшого потока заказов. Минус очевиден: между оформлением и оплатой есть ручной шаг, а сумму на ссылке с открытой суммой вводит покупатель — сверяйте её с заказом.

## Вариант B — свой бэкенд (нужен разработчик)

Схема: Shopify создаёт заказ → ваш бэкенд получает его (webhook Shopify `orders/create`) → создаёт счёт Qut Pay на сумму заказа → отправляет покупателю `payUrl` → при оплате Qut Pay присылает `invoice.paid` → бэкенд вызывает Shopify Admin API и отмечает заказ оплаченным.

Создание счёта с бэкенда — обычный запрос к API, ключ хранится только на сервере:

```bash
curl -X POST https://api.qut.kz/api/v1/invoices \
  -H "X-API-Key: qp_test_…" -H "Content-Type: application/json" \
  -H "Idempotency-Key: shopify-1001" \
  -d '{"amount": 12500, "externalOrderId": "1001", "description": "Заказ #1001",
       "successUrl": "https://shop.kz/thanks?order=1001", "metadata": {"shopifyOrderId": 5566778899}}'
```

Ответ содержит `id`, `status`, `payUrl`, `qrUrl`, `deepLink`, `expiresAt` — покупателю нужен `payUrl`. Webhook `invoice.paid` приходит JSON `{ "event", "invoice": { "id", "status", "amount", "externalOrderId", "metadata", … }, "sentAt" }`; проверяйте подпись `X-Webhook-Signature` по сырому телу, сверяйте `amount` с суммой заказа и отвечайте `2xx` в течение 8 секунд — иначе доставка повторится до 11 раз за ~2 часа. Подробно: [настройка вебхуков](/kb/ru/webhook-setup), [как автоматически узнать об оплате](/kb/ru/auto-check-payment). Готовые клиенты: [Node.js](/kb/ru/sdk-node), [PHP](/kb/ru/sdk-php), [Python](/kb/ru/sdk-python); инструкция для ИИ-ассистента, которому можно поручить этот бэкенд: https://api.qut.kz/for-ai.

Ограничения варианта B: QR действует около 3 минут (`expiresAt`), поэтому ссылку лучше открывать сразу после оформления; доступ к Admin API Shopify настраиваете вы сами (custom app с правом на заказы); тариф Qut Pay от 4 990 ₸ в месяц — [тарифы](/kb/ru/tariff-choose).

## Пошагово, с чего начать

1. Зарегистрируйтесь в кабинете https://qut.kz/app, попробуйте всё в песочнице с ключом `qp_test_…` — оплату имитирует `POST /invoices/{id}/simulate` `{"status":"paid"}`.
2. Подключите кассира Kaspi Pay и переключитесь в live — [чек-лист перед запуском](/kb/ru/going-live-checklist).
3. Включите ручной способ оплаты в Shopify и выберите вариант A или B.

## Вопросы и ответы

**Появится ли приложение Qut Pay в Shopify App Store?** Сейчас его нет, и обещать сроки мы не будем: платёжные приложения Shopify проходят отдельную программу партнёрства платформы. Эта статья описывает то, что работает уже сегодня.

**Можно ли обойтись без разработчика?** Да, вариант A: ручной способ оплаты в Shopify и ссылка Qut Pay. Автоматическая пометка заказа оплаченным без кода невозможна.

**Покупатель вернулся на страницу «спасибо» — значит оплатил?** Нет. Переход по `successUrl` не доказательство; оплату подтверждает webhook `invoice.paid` или статус `paid` по `GET /invoices/{id}` с сервера.

**А если у меня не Shopify, а WooCommerce или OpenCart?** Для них есть готовые модули: [WooCommerce](/kb/ru/woocommerce), [OpenCart](/kb/ru/opencart).