Қайтару API — толық және ішінара қайтару

Қысқаша

Ақшаны қайтару — бір ғана әдіс:

POST /api/v1/invoices/{id}/refund
X-API-Key: qp_live_…
Content-Type: application/json

{ "amount": 1500, "reason": "Тауар қайтарылды" }

amount жазбасаңыз — счёт толық қайтарылады. Жазсаңыз — сол сома ғана қайтады, счёт partially_refunded күйіне өтеді.

Екі нәрсені бірден есте ұстаңыз: кілтте refunds:write құқығы болуы керек, ал refund_unknown немесе refund_pending_unknown қатесі келсе сұрауды қайталамау керек — оның орнына счёт күйін оқисыз.

Сұрау өрістері

Жол параметрі {id} — счёттың id мәні (inv_…). externalOrderId бойынша қайтару жоқ: алдымен GET /api/v1/invoices?externalOrderId=… арқылы счётты тауып, содан соң оның id мәнін қолданыңыз.

Қайтару қандай счётқа жасалады

Ақша біздің шотымыздан емес, сіздің Kaspi шотыңыздан кетеді. Біз ақшаны ешқашан ұстамаймыз, сондықтан қайтаруды да Kaspi орындайды. Шотта қалдық жеткіліксіз болса, операция өтпейді.

Толық және ішінара қайтару

Толық қайтару — денесі бос немесе тек reason бар сұрау:

curl -X POST https://api.qut.kz/api/v1/invoices/inv_7Kd2/refund \
  -H "X-API-Key: $QUTPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Клиент бас тартты"}'

Ішінара қайтару — amount көрсетілген сұрау. Бірнеше рет ішінара қайтаруға болады, бірақ ереже қатаң:

Барлық қайтарулардың қосындысы төленген сомадан аспауы керек.

Мысалы, 10 000 ₸ счёт бойынша 3 000 және 4 000 қайтарсаңыз, үшінші рет ең көбі 3 000 қайтара аласыз. Одан асырсаңыз invalid_refund_amount келеді. Соңғы қалдықты қайтарғаныңызда счёт refunded күйіне өтеді.

Кезекті қайтарудан бұрын ағымдағы қалдықты GET /api/v1/invoices/{id} арқылы оқып алу дұрыс — жауапта счёт бойынша жасалған қайтарулар тізімі де болады.

Қате кодтары

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

Нәтижесі белгісіз болғанда

refund_unknown — Kaspi сұрауға жауап бермеді. Ақша кетті ме, жоқ па — бұл сәтте біз де білмейміз. refund_pending_unknown — алдыңғы қайтару әлі анықталмағандықтан жаңа сұрау қабылданбайды.

Екі жағдайда да реті бірдей:

1. Сұрауды қайталамаңыз. Қайтару әдісінде идемпоттылық кепілдігі жоқ — екінші сұрау екінші қайтаруға айналуы мүмкін.
2. Бірнеше секунд, қажет болса бір минут күтіңіз.
3. GET /api/v1/invoices/{id} арқылы күйді оқыңыз.
4. Күй refunded немесе partially_refunded болса — қайтару өтті, қайталаудың қажеті жоқ.
5. Күй әлі paid, ал қайтарулар тізімі бос болса — сонда ғана қайталаңыз.

Клиентке «ақша қайтарылды» деп счёт күйінен көрмей тұрып айтпаңыз.

async function refundOnce(id, amount) {
  const r = await fetch(`${API}/invoices/${id}/refund`, {
    method: 'POST',
    headers: { 'X-API-Key': KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({ amount, reason: 'Қайтару' }),
  });
  if (r.ok) return 'done';

  const { error } = await r.json();
  if (error === 'refund_unknown' || error === 'refund_pending_unknown') {
    // қайталамаймыз — күйді оқып барып шешеміз
    return 'check_status';
  }
  if (error === 'refund_failed') return 'retry_later';
  throw new Error(error);
}

Оқиғалар

Қайтару өткен соң webhook келеді:

Автоматты есеп жүргізсеңіз, күйді сұрап отырғаннан гөрі осы оқиғаларға сүйенген ыңғайлы. Webhook өңдеуіңіз идемпотентті болсын: бір қайтару туралы екі рет хабар келгенде бухгалтерияда екі жазба пайда болмауы керек.

Құқық және кассир

• Кілтте refunds:write құқығы болуы керек, әйтпесе insufficient_scope. Толығы: Құқықтар (scopes).
• Қайтару да Kaspi-дегі «Кассир» рөлі арқылы жүреді, сондықтан кассир байланысы белсенді болуы шарт. Байланыс үзілсе қайтару да, счёт жасау да өтпейді.
• Кілт нақты кассирге байланған болса, ол басқа кассирдің счёттарын көрмейді — сондай счётқа қайтару жіберсеңіз invoice_not_found келеді.

Мерзім

Қайтару мәңгі қолжетімді емес: белгілі бір уақыттан кейін Kaspi ескі операция бойынша қайтаруға рұқсат бермейді. Мерзімді Kaspi белгілейді, біз оны ұзарта алмаймыз. Мерзімі өткен счётқа invoice_not_refundable келеді.

Sandbox режимінде бүкіл циклді қауіпсіз сынап көруге болады: счёт жасап, төлемді симуляциялап, содан кейін қайтаруды жіберіңіз.

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

Қайтаруды кері қайтаруға бола ма? Жоқ. Өткен қайтару кері оралмайды — клиенттен қайта төлеуді сұрауға тура келеді.

Комиссия қайтарыла ма? Kaspi өз комиссиясын өзі анықтайды, оны Kaspi қолдауынан сұраңыз. Біз транзакциядан пайыз алмаймыз, сондықтан бізден қайтаратын ештеңе жоқ.

Клиентке ақша қашан жетеді? Оны Kaspi шешеді, мерзімге біз әсер ете алмаймыз.

Қайтаруды кабинеттен жасауға бола ма? Иә, Счёттар бөлімінде счётты ашып, қайтару батырмасын басасыз. API мен кабинет бір операцияны орындайды.

Қате кодтарының толық тізімі қайда? Қателер каталогы бетінде. Қайтару өтпей жатқанда себебін іздеу реті: Қайтару өтпей жатыр.