# Kaspi Pay-ді Shopify-ға қосу

> Ашық талдау: Shopify App Store-да Qut Pay қосымшасы жоқ, Shopify дүкенге кез келген төлем шлюзін қосуға рұқсат бермейді. Бүгін не істейді — қолмен төлеу тәсілі мен Qut Pay сілтемесі, webhook және Admin API бар шағын бэкенд, шекаралары қайда.

## Қысқаша

Shopify үшін дайын Qut Pay қосымшасы жоқ, ал Kaspi QR-ды Shopify-дың стандартты checkout-ына «кіргізу» мүмкін емес: платформа бөгде шлюздерді тек мақұлданған серіктестерге арналған өзінің Payments Apps бағдарламасы арқылы қабылдайды, дүкенге кез келген шлюзді қосуға рұқсат бермейді. Бүгін шынымен істейтіні: Shopify-да **қолмен төлеу тәсілін** («Manual payment method», мысалы «Kaspi QR») қосасыз, ал төлемді Qut Pay арқылы қабылдайсыз — тұрақты сілтеме бойынша немесе шағын бэкендіңіз жасайтын счёт бойынша. Тапсырыс не кабинеттегі журнал бойынша қолмен, не автоматты түрде төленді деп белгіленеді: `invoice.paid` webhook-і бэкендіңізге келеді, ол Shopify Admin API арқылы тапсырысты жабады. Shopify checkout-ының өзінде автоматты «Kaspi QR-мен төлеу» қадамы пайда болмайды.

## Не істеуге болады, не болмайды

| Міндет | Мүмкін бе? | Қалай |
|---|---|---|
| Shopify checkout-ындағы төлем тәсілдері арасында Kaspi QR батырмасы | Жоқ | Тек Shopify-дың Payments Apps бағдарламасы арқылы, Qut Pay оған қатыспайды |
| Shopify тапсырысы бойынша Kaspi QR қабылдау | Иә | Қолмен төлеу тәсілі + Qut Pay сілтемесі немесе счёты |
| Тапсырысты автоматты төленді деп белгілеу | Иә, әзірлеушімен | Qut Pay webhook → бэкендіңіз → Shopify Admin API |
| Shopify checkout-ынан тыс сату | Иә | Тауар сипаттамасында, хат алмасуда, Instagram-да `qut.kz/p/<slug>` төлем сілтемесі |

## А нұсқасы — қолмен төлеу тәсілі + сілтеме (кодсыз)

1. Shopify әкімшілігінде: Settings → Payments → Manual payment methods → «Kaspi QR» тәсілін қосыңыз. Сатып алушыға арналған нұсқаулықта төлем сілтемесі рәсімдеуден кейін келетінін жазыңыз.
2. Qut Pay кабинетінде ашық сомалы [тұрақты төлем сілтемесін](/kb/payment-links) жасаңыз — немесе әр тапсырысқа счётты қолмен шығарыңыз.
3. Сілтемені сатып алушыға жіберіңіз (тапсырысты растау хаты, WhatsApp). Ол төлейді, ақша сіздің Kaspi Pay-ге түседі.
4. Кабинетте төлемді көрген соң Shopify-да тапсырыстың «Mark as paid» батырмасын басыңыз.

Тапсырыс ағыны аз болса жарайды. Кемшілігі айқын: рәсімдеу мен төлем арасында қолмен істейтін қадам бар, ал ашық сомалы сілтемеде соманы сатып алушы өзі енгізеді — оны тапсырыспен салыстырыңыз.

## Б нұсқасы — өз бэкендіңіз (әзірлеуші керек)

Схема: Shopify тапсырыс жасайды → бэкендіңіз оны алады (Shopify webhook `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` керек. `invoice.paid` webhook-і JSON күйінде келеді: `{ "event", "invoice": { "id", "status", "amount", "externalOrderId", "metadata", … }, "sentAt" }`; `X-Webhook-Signature` қолтаңбасын шикі дене бойынша тексеріңіз, `amount`-ты тапсырыс сомасымен салыстырыңыз және 8 секунд ішінде `2xx` қайтарыңыз — әйтпесе жеткізу ~2 сағат ішінде 11 ретке дейін қайталанады. Толығырақ: [webhook баптау](/kb/webhook-setup), [төлемді автоматты қалай білуге болады](/kb/auto-check-payment). Дайын клиенттер: [Node.js](/kb/sdk-node), [PHP](/kb/sdk-php), [Python](/kb/sdk-python); осы бэкендті тапсыруға болатын ЖИ-ассистентке арналған нұсқаулық: https://api.qut.kz/for-ai.

Б нұсқасының шектеулері: QR шамамен 3 минут жарамды (`expiresAt`), сондықтан сілтемені рәсімдеуден кейін бірден ашқан дұрыс; Shopify Admin API-ге қолжетімділікті өзіңіз баптайсыз (тапсырыстарға құқығы бар custom app); Qut Pay тарифі айына 4 990 ₸-ден — [тарифтер](/kb/tariff-choose).

## Қадам-қадаммен, неден бастау

1. https://qut.kz/app кабинетінде тіркеліп, бәрін `qp_test_…` кілтімен sandbox-та байқап көріңіз — төлемді `POST /invoices/{id}/simulate` `{"status":"paid"}` имитациялайды.
2. Kaspi Pay кассирін қосып, live режиміне ауысыңыз — [іске қосу алдындағы тексеру тізімі](/kb/going-live-checklist).
3. Shopify-да қолмен төлеу тәсілін қосып, А немесе Б нұсқасын таңдаңыз.

## Сұрақ-жауап

**Shopify App Store-да Qut Pay қосымшасы шыға ма?** Қазір жоқ, мерзім уәде етпейміз: Shopify-дың төлем қосымшалары платформаның бөлек серіктестік бағдарламасынан өтеді. Бұл мақала бүгін істеп тұрғанын сипаттайды.

**Әзірлеушісіз болады ма?** Иә, А нұсқасы: Shopify-да қолмен төлеу тәсілі және Qut Pay сілтемесі. Тапсырысты кодсыз автоматты түрде төленді деп белгілеу мүмкін емес.

**Сатып алушы «рахмет» бетіне оралды — демек төледі ме?** Жоқ. `successUrl` арқылы өту — дәлел емес; төлемді `invoice.paid` webhook-і немесе серверден `GET /invoices/{id}` бойынша `paid` күйі растайды.

**Менде Shopify емес, WooCommerce немесе OpenCart болса ше?** Олар үшін дайын модульдер бар: [WooCommerce](/kb/woocommerce), [OpenCart](/kb/opencart).