Счёт жасау: барлық өрістер

Қысқаша

Счёт жасау — бір ғана сұрау:

POST https://api.qut.kz/api/v1/invoices
X-API-Key: qp_live_…
Content-Type: application/json

Жауапта 201 күйі және payUrl келеді — клиентті сол адреске жіберіңіз. Міндетті өріс біреу ғана: amount.

Ескі жол POST /api/v1/orders да қабылданады, ол дәл осы эндпоинттің alias-ы.

Сұраудың өрістері

Тақырыптар:

Idempotency-Key жіберсеңіз, сол кілтпен екінші рет сұрау жаңа счёт жасамайды: бұрынғысы қайтады, HTTP 200 және жауапта idempotentReplay: true болады. Толығырақ: Идемпоттылық.

qr мен phone айырмашылығы

Толық салыстыру: QR счёт пен телефонға счёт.

Жауап

HTTP 201 және мынандай дене:

QR-дың сканерлеу терезесі шамамен үш минут, оны Kaspi белгілейді. Оны кодыңызда тұрақты сан деп жазбаңыз — әрқашан expiresAt өрісінен алыңыз.

curl мысалы

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-1001' \
  -d '{
    "amount": 2500,
    "kind": "qr",
    "description": "Тапсырыс №1001",
    "externalOrderId": "1001",
    "customer": { "name": "Айгүл", "phone": "77010000000" },
    "successUrl": "https://site.kz/ok",
    "failUrl": "https://site.kz/fail",
    "metadata": { "branch": "almaty-1", "cart": 17 }
  }'

Node мысалы

const res = await fetch('https://api.qut.kz/api/v1/invoices', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.QUTPAY_API_KEY,
    'Content-Type': 'application/json',
    'Idempotency-Key': `order-${order.id}`,
  },
  body: JSON.stringify({
    amount: order.total,
    kind: 'qr',
    description: `Тапсырыс №${order.id}`,
    externalOrderId: String(order.id),
    successUrl: 'https://site.kz/ok',
    metadata: { orderId: order.id },
  }),
});

if (!res.ok) {
  const err = await res.json();
  console.error('qutpay', res.status, err.error, err.message);
  throw new Error(err.error);
}

const invoice = await res.json();
redirect(invoice.payUrl);

Қате болғанда error кодына қараңыз, message мәтініне емес: мәтін өзгеруі мүмкін, код өзгермейді.

/orders alias

Ескі интеграциялар үшін POST /api/v1/orders жолы сақталған. Онда merchantRef (яғни externalOrderId) және method: "invoice" өрістері де қабылданады. Жаңа код жазып жатсаңыз, /api/v1/invoices қолданыңыз.

Жиі кездесетін қателер

Толық тізім: Қателер каталогы.

Шекті жағдайлар

• Тиын. QR счёт екі ондықты қабылдайды, ал телефонға счёт бүтін теңгені ғана. Сомаңызда тиын болса, kind: phone алдында дөңгелектеңіз.
• Ұзын сипаттама. Шектен асқан мәтін клиентте қиылып көрінуі мүмкін, сондықтан QR үшін 100, phone үшін 60 таңбадан асырмаңыз.
• Бірнеше счёт бір тапсырысқа. Клиент «төлеу» батырмасын екі рет бассаңыз екі счёт жасалады. Idempotency-Key қойыңыз.
• Көп счёт бірден керек. 100-ге дейін счётты бір сұраумен жасауға болады: Топтап счёт жасау.
• Жауапты күтіп қалдыңыз. Таймаут болса счёт жасалған да болуы мүмкін. Сол Idempotency-Key мен қайталаңыз — жаңасы жасалмайды.

Жиі қойылатын сұрақтар

payUrl мен deepLink айырмашылығы неде? payUrl — браузерде ашылатын төлем беті, кез келген құрылғыда жұмыс істейді. deepLink — Kaspi қосымшасын тікелей ашады, телефонда ыңғайлы.

Счёттың күйін қалай білемін? Webhook арқылы немесе GET /api/v1/invoices/{id} сұрауымен. Қайсысын қашан: Webhook пен күйді сұрау.

metadata ішіне не жазуға болады? Кез келген JSON: нүкте нөмірі, себет идентификаторы, ұяшық нөмірі. Ол webhook-та да, күй сұрауында да сол күйінде қайтады.

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

Sandbox-та да осы өрістер жүре ме? Иә, бірдей. Айырмашылығы — Kaspi шақырылмайды, төлемді өзіңіз симуляциялайсыз.