Сома дұрыс емес немесе тиын жоғалып жатыр

Қысқаша

Екі ереже бәрін түсіндіреді. Телефонға шығарылған счёт (kind: "phone") бүтін теңге қабылдайды — тиын жіберсеңіз, amount_must_be_whole_tenge қатесі келеді. QR счёт ең көбі екі ондық белгіні қабылдайды. Валюта әрқашан — KZT, басқасы жоқ.

Демек, дөңгелектеуді өз жағыңызда, счёт жасаудан бұрын істеу керек. Сонда қандай сома есептелгенін өзіңіз білесіз және клиентке көрсете аласыз. Егер дөңгелектеуді бізге қалдырсаңыз, сіздің базаңыздағы сома мен нақты төленген сома бір-біріне сәйкес келмей қалуы мүмкін.

Симптом бойынша себеп

Сома қалай жіберіледі

amount өрісі — сан, теңгемен. Тиынмен емес: 1 000 ₸ жіберу үшін 1000 жазасыз, 100000 емес.

curl -X POST https://api.qut.kz/api/v1/invoices \
  -H "X-API-Key: qp_live_СІЗДІҢ_КІЛТІҢІЗ" \
  -H "Content-Type: application/json" \
  -d '{"amount":1000,"kind":"qr","description":"Тапсырыс №1042"}'

Телефонға счёт:

curl -X POST https://api.qut.kz/api/v1/invoices \
  -H "X-API-Key: qp_live_СІЗДІҢ_КІЛТІҢІЗ" \
  -H "Content-Type: application/json" \
  -d '{"amount":1000,"kind":"phone","customer":{"phone":"77771234567"},"description":"Тапсырыс №1042"}'

Мұнда 1000.50 жіберсеңіз, amount_must_be_whole_tenge қайтады.

Дөңгелектеуді өз жағыңызда істеңіз

Ең жиі кездесетін көрініс: себетте 3 333.33 ₸ тұр, ал клиент 3 333 ₸ төлейді. Айырма кішкентай, бірақ айдың соңында есеп айырысқанда бәрі көрініп қалады.

Сондықтан ретті былай құрыңыз:

// 1. Соманы өз жағыңызда бүтіндеңіз
const total = Math.round(cart.total);   // 3333.33 → 3333

// 2. Сол соманы өз базаңызға жазыңыз
await orders.update(orderId, { chargedAmount: total });

// 3. Дәл сол соманы жіберіңіз
await createInvoice({ amount: total, kind: 'phone', ... });

Үш ұстаным:

• Бір ғана дөңгелектеу нүктесі болсын. Есептің әр жерінде дөңгелектесеңіз, қателік жиналады.
• Дөңгелектелген соманы базаға жазыңыз. Кейін салыстырғанда қай сома нағыз екені белгілі болады.
• Клиентке сол соманы көрсетіңіз. Себетте бір сома, счётта екінші сома тұрса, сұрақ туады.

Math.round жоғары қарай дөңгелектейді (0.5 → жоғары). Егер сіз әрқашан төмен қарай дөңгелектегіңіз келсе, Math.floor қолданыңыз — бірақ таңдағаныңызды бүкіл жүйеде бірдей ұстаңыз.

Жүздік бөлікпен жұмыс

Егер жүйеңізде бағалар тиынмен сақталса (мысалы 333333 = 3 333.33 ₸), айналдыруды бір жерде істеңіз:

const tenge = Math.round(priceInTiyn / 100);

Қалқымалы санмен есептеуден сақ болыңыз: 0.1 + 0.2 көп тілде 0.30000000000000004 береді. Бағаларды бүтін санмен (тиынмен) сақтап, тек соңғы қадамда теңгеге айналдырған сенімді.

Екі счёттың айырмашылығы

Практикада екеуіне де бүтін теңге жіберген ыңғайлы: сонда счёт түрін ауыстырғанда логиканы қайта жазудың қажеті болмайды.

Сома шектеулері

Ең төменгі және ең жоғарғы сома бар, және оларды біз емес, Kaspi жағы да шектейді. Шектен шықсаңыз amount_too_small немесе amount_too_large келеді.

Ірі сомамен жұмыс істейтін болсаңыз (мысалы көтерме сауда), екі нәрсені ескеріңіз:

• Соманы бірнеше счётқа бөлу — жұмыс істейтін тәсіл, бірақ әр счётты бөлек бақылау керек
• Клиенттің өз жағында да лимиттер болуы мүмкін, ол Kaspi-дің баптауы

Сондай-ақ amount_too_large қатесі кодтағы қатеден де келеді: айнымалы тиынмен берілгенде сома жүз есе үлкейіп кетеді. Мұндайда шектен асқан сан әдетте көзге бірден түседі.

Валюта

Валюта тек KZT. Басқа валютаны жіберудің жолы жоқ, currency өрісін іздеудің қажеті жоқ.

Сайтыңыз бірнеше валютада баға көрсетсе, айырбастауды өз жағыңызда, счёт жасаудан бұрын істеңіз. Клиент Kaspi-де әрқашан теңгемен төлейді.

Тексеру реті

1. Қате мәтінін оқыңыз: amount_must_be_whole_tenge па, invalid_amount па
2. Жіберіп жатқан мәннің типін тексеріңіз: сан ба, жол ба
3. Телефонға счёт болса, тиын бар-жоғын қараңыз
4. Өз базаңыздағы сома мен жіберілген сома бірдей ме
5. Дөңгелектеу кодта бір ғана жерде тұр ма

Егер сома дұрыс, бірақ ақша көрінбей жатса, мәселе басқада: Счёт төленді, ақша түспеді.

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

QR счётқа тиын жіберуге бола ма? Екі ондыққа дейін қабылданады. Бірақ практикада бүтін теңге жіберген қарапайым әрі қауіпсіз.

Клиент соманы өзі өзгерте ала ма? Әдеттегі счётта — жоқ, сома бекітілген. Ашық сомалы төлем сілтемесінде клиент өзі енгізеді.

Сома жолмен жіберілсе не болады? Кейбір жағдайда қабылданады, кейбірінде invalid_amount келеді. Әрқашан сан түрінде жіберіңіз.

Дөңгелектегенде айырманы кім төлейді? Бұл сіздің шешіміңіз. Көбі төмен қарай дөңгелектеп, бірнеше тиынды өзі көтереді — клиентке түсіндіру қиынырақ болады.

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