Создание счёта: все поля

Коротко

Создание счёта — это один запрос:

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

В ответе приходит статус 201 и payUrl — отправьте покупателя по этому адресу. Обязательное поле всего одно: amount.

Старый путь POST /api/v1/orders тоже принимается, это алиас того же эндпоинта.

Поля запроса

Заголовки:

Если передать 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

Для старых интеграций сохранён путь POST /api/v1/orders. Там дополнительно принимаются поля merchantRef (то же, что externalOrderId) и method: "invoice". Если пишете новый код, используйте /api/v1/invoices.

Частые ошибки

Полный список: Каталог ошибок.

Пограничные случаи

• Тиыны. QR-счёт принимает два знака после запятой, счёт по телефону — только целые тенге. Если в сумме есть тиыны, округлите до отправки с kind: phone.
• Длинное описание. Текст сверх лимита у покупателя может обрезаться, поэтому не превышайте 100 символов для QR и 60 для phone.
• Несколько счетов на один заказ. Двойное нажатие кнопки «оплатить» создаст два счёта. Ставьте Idempotency-Key.
• Нужно много счетов сразу. До 100 счетов можно создать одним запросом: Массовое создание счетов.
• Не дождались ответа. При таймауте счёт мог быть создан. Повторите с тем же Idempotency-Key — новый не появится.

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

Чем payUrl отличается от deepLink? payUrl — страница оплаты в браузере, работает на любом устройстве. deepLink открывает приложение Kaspi напрямую, удобен на телефоне.

Как узнать статус счёта? Через вебхук или запросом GET /api/v1/invoices/{id}. Что когда: Вебхук или опрос статуса.

Что можно класть в metadata? Любой JSON: номер точки, идентификатор корзины, номер ячейки. Он возвращается и в вебхуке, и в ответе на запрос статуса.

Можно изменить сумму уже созданного счёта? Нет. Отмените счёт и создайте новый.

В песочнице те же поля? Да, полностью. Разница только в том, что Kaspi не вызывается и оплату вы симулируете сами.