Сайтқа «Kaspi арқылы төлеу» батырмасын қалай жасау керек — үш тәсіл

Қысқаша

Сайттағы «Kaspi арқылы төлеу» батырмасы — не qut.kz/p/<slug> тұрақты төлем бетіне қарапайым сілтеме (кодсыз, бір баға немесе ашық сома үшін жарайды), не серверіңіз Qut Pay API арқылы счёт жасап, сатып алушыны payUrl-ге бағыттайтын батырма (әр тапсырысқа өз сомасы мен нөмірі бар счёт). Екі жағдайда да сатып алушы Kaspi қосымшасында төлейді, ақша сіздің Kaspi Pay-іңізге түседі, ал сайт төлемді invoice.paid webhook-і арқылы біледі. Бұл үшін Kaspi Pay бизнес-аккаунты және қосылған кассир керек — бастау үшін не керек.

Қай тәсілді таңдау

WordPress пен OpenCart-қа батырманы дайын модуль қосады: WooCommerce, OpenCart. Tilda үшін — форма-хук.

1-тәсіл. Кодсыз батырма-сілтеме

1. Кабинетте Сілтемелер бөлімін ашып, сілтеме жасаңыз: адрес (мысалы konsultaciya), атауы, сомасы — бекітілген немесе ашық. Толығырақ: төлем сілтемелері.
2. Сайтқа батырма түрінде безендірілген қарапайым сілтеме қойыңыз:

<a href="https://qut.kz/p/konsultaciya" class="btn">Kaspi арқылы төлеу</a>

Сілтеме әр ашылған сайын жаңа счёт жасалады, сондықтан бір батырманы қанша сатып алушы болса да баса береді. Сілтемені тоқтатып, қайта қосуға болады, адресі өзгермейді.

2-тәсіл. Әр тапсырысқа счёт шығаратын батырма

Батырма сұрауды сіздің серверіңізге жібереді, сервер Qut Pay-де счёт жасап, сатып алушыны төлем бетіне бағыттайды. API кілті бұл кезде серверде қалады — беттің HTML мен JavaScript кодында ол болмауы керек.

Сервер жасайтын сұрау:

curl -X POST https://api.qut.kz/api/v1/invoices \
  -H "X-API-Key: qp_live_…" -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-A-1041" \
  -d '{"amount": 12000, "externalOrderId": "A-1041", "description": "Тапсырыс A-1041", "successUrl": "https://example.kz/thanks"}'

201 жауабында id, payUrl, qrUrl, deepLink, expiresAt келеді. Node.js (Express) нобайы:

app.post('/pay', async (req, res) => {
  const r = await fetch('https://api.qut.kz/api/v1/invoices', {
    method: 'POST',
    headers: { 'X-API-Key': process.env.QUTPAY_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({ amount: 12000, externalOrderId: req.body.orderId, description: 'Тапсырыс ' + req.body.orderId }),
  });
  const invoice = await r.json();
  res.redirect(invoice.payUrl);
});

Беттегі батырма — қарапайым форма: <form method="post" action="/pay"><input type="hidden" name="orderId" value="A-1041"><button>Kaspi арқылы төлеу</button></form>. PHP мен Python-да дәл сол PHP SDK және Python SDK арқылы жасалады; сұраудың барлық өрісі — API арқылы счёт жасау мақаласында.

Телефонда: Kaspi қосымшасын ашу

payUrl qut.kz/pay/<id> бетіне апарады, онда компьютерге арналған QR мен телефонға арналған батырма бар. Өз төлем бетіңізді жасасаңыз, телефонда адресі deepLink болатын батырманы көрсетіңіз — ол Kaspi қосымшасын бірден счётпен ашады, ал QR-ды компьютер экранына қалдырыңыз: QR-ды ол көрсетіліп тұрған телефонның өзімен сканерлеу мүмкін емес. QR шамамен үш минут жарайды (дәл уақыты — expiresAt өрісінде) — QR неге бітеді.

Сатып алушы не көреді

Басқаннан кейін сатып алушы Kaspi қосымшасында сома, счёт сипаттамасы және сіздің кассир нөміріңізді (оны Kaspi-дің өзі көрсетеді) көреді, төлемді растайды — ақша сіздің Kaspi Pay бизнес-шотыңызға түседі. Счётта successUrl көрсетілсе, сатып алушы сол арқылы сайтыңызға қайта оралады. Толығырақ: сатып алушы не көреді.

Сайт төлемді қалай біледі

Сатып алушының «рақмет» бетіне оралуы төлемді растамайды. Тапсырысты HMAC-SHA256 қолтаңбасы тексерілген invoice.paid webhook-і бойынша немесе серверіңізден GET /invoices/{id} сұрауындағы paid күйі бойынша төленді деп белгілеңіз. Webhook адресі кабинеттегі Интеграциялар бөлімінде қосылады — webhook баптау, төлемді автоматты түрде қалай білу. Батырма-сілтеме үшін де webhook келеді, ал төлемдер кабинеттегі Счёттар бөлімінде көрінеді.

Сұрақ-жауап

Батырманы серверсіз, тек JavaScript-пен жасауға бола ма? 2-тәсіл үшін — жоқ: API кілтін бет кодына салуға болмайды. Серверсіз qut.kz/p/<slug> батырма-сілтемесін қолданыңыз.

Батырманы нақты төлемдерге дейін қалай тексеру керек? qp_test_… кілтін жасаңыз: счёт дәл солай жасалады, ал төлемді POST /invoices/{id}/simulate имитациялайды — sandbox.

Сатып алушы батырманы екі рет бассa не болады? Idempotency-Key тақырыбымен қайталанған сұрау сол счётты қайтарады, жаңасы жасалмайды — идемпотенттілік.

Сатып алушыға чек керек пе? Иә, оны сатушы береді; Kaspi Касса қосулы болса, чек сатып алушыға өзі кетеді — фискалдық чек.