API аркылуу Kaspi эсептери

    4 мүн окуу
    ·
    5 көрүү
    ·
    Жаңыртылды: 11/18/2026

    Системаңыздан жөнөтүлгөн Kaspi эсептери

    CRM системаңыз же сайтыңыз кардарга телефон номери боюнча каалаган суммага Kaspi эсебин жөнөтөт. Кардар эсепти Kaspi тиркемесинде алып, төлөйт. Төлөм өткөндө вебхугуңузга kaspi_invoice_paid окуясы келет: анын негизинде буйрутманы жабасыз жана керек болсо, кардарга POST /v1/messages/send аркылуу жазасыз.

    Баштоодон мурун эмне керек

    • Kaspi Pay кассири кабинетте туташтырылган: Жөндөөлөр → Интеграциялар → Kaspi Pay. «Кассир» ролу бар өзүнчө номер керек.
    • Kaspi Pay тарифи иштеп турат: «Старт» (бир кассага айына 150 төлөмгө чейин) же «Чексиз». Тарифти кабинетте төлөсө болот: Коннекторлор → Kaspi Pay. Кассир биринчи жолу туташкандан кийин 7 күндүк сыноо мезгили берилет. WazzaBee CRM системасы иштеп турса (сыноо же төлөнгөн), эсептер акысыз.
    • API ачкычыңыз үчүн Kaspi эсептери күйгүзүлгөн. Аларды сиздин өтүнүчүңүз боюнча WazzaBee колдоо кызматы күйгүзөт, башка ачкычтарда ыкмалар 403 катасын кайтарат.
    • Ачкычтын вебхугу PATCH /v1/webhooks аркылуу жөндөлгөн. Kaspi окуялары ага өзүнчө жазылуусуз келет.

    Ашыкча эсептерден коргоо

    • Бир ачкычка мүнөтүнө 5 эсептен жана суткасына 100 эсептен ашпайт. Көбүрөөк керек болсо, колдоо кызматына жазыңыз.
    • Ошол эле externalId менен кайталанган сурам экинчи эсепти түзбөйт, биринчи эсепти "duplicate": true белгиси менен кайтарат.
    • Акыркы 30 мүнөттө ошол эле номерге ошол эле суммага төлөнбөгөн эсеп болсо, жаңысы түзүлбөйт, жоопто бар эсеп келет.
    • Бир кассирге суткасына бардык жолдор боюнча 300дөн ашпаган эсеп: API, меню-бот жана CRM бүтүмдөрү.
    • Эгер сутка ичинде кардарлар ачкычтын 10 же андан көп эсебин четке какса же төлөбөсө жана бул жабылган эсептердин жарымынан көп болсо, ачкыч үчүн Kaspi эсептери автоматтык түрдө токтотулат (kaspi_auto_stopped катасы). Кайра күйгүзүү үчүн колдоо кызматына жазыңыз.

    POST /v1/kaspi/invoices

    Эсеп жөнөтүү.

    POST https://api.wazzabee.com/api-gateway/v1/kaspi/invoices
    Authorization: Bearer API_АЧКЫЧЫҢЫЗ
    Content-Type: application/json
    ПараметрТүрүМилдеттүүСүрөттөмө
    phonestring✅Кардардын Kaspi'деги номери, Казакстан: +77011234567, 87011234567 же 7011234567
    amountnumber✅Теңге менен сумма, 0дөн көп жана 5 000 000дон ашпайт
    commentstringЖокЭсепке 200 белгиге чейинки комментарий, мисалы буйрутманын номери жана товар. Кардар аны Kaspi'де көрөт
    externalIdstringЖокСистемаңыздагы буйрутманын номери, 100 белгиге чейин. Сурам кайталанганда эки эсептен коргойт
    curl -X POST "https://api.wazzabee.com/api-gateway/v1/kaspi/invoices" \
      -H "Authorization: Bearer API_АЧКЫЧЫҢЫЗ" \
      -H "Content-Type: application/json" \
      -d '{"phone": "+77011234567", "amount": 15000, "comment": "Буйрутма 1024, кап", "externalId": "1024"}'

    Жооп 201 (жаңы эсеп) же 200 (кайталоо, "duplicate": true):

    {
      "success": true,
      "duplicate": false,
      "invoice": {
        "invoiceId": "uuid",
        "externalId": "1024",
        "phone": "+77011234567",
        "amount": 15000,
        "comment": "Буйрутма 1024, кап",
        "status": "pending",
        "createdAt": "2026-11-17T14:00:00.000Z",
        "paidAt": null
      }
    }

    Эсептин статустары: pending (төлөмдү күтүүдө), paid (төлөндү), expired (мөөнөтү өттү), cancelled (жокко чыгарылды), unknown (Kaspi 3 күндүн ичинде жооп берген жок).

    GET /v1/kaspi/invoices/{invoiceId}

    invoiceId боюнча эсеп. Жооп: {"success": true, "invoice": {...}}. Статус мүнөтүнө бир жолу жаңыланат.

    GET /v1/kaspi/invoices

    Ачкычыңыздын эсептери, жаңылары өйдөдө. Сурам сабынын параметрлери: from жана to (ISO 8601 датасы), status (pending, paid, expired, cancelled, unknown), limit (1–200, демейки боюнча 50).

    GET https://api.wazzabee.com/api-gateway/v1/kaspi/invoices?from=2026-11-01T00:00:00Z&status=paid

    POST /v1/kaspi/invoices/{invoiceId}/cancel

    Төлөнбөгөн эсепти жокко чыгаруу. Жооп: {"success": true, "invoice": {..., "status": "cancelled"}}. Өзүңүз жокко чыгарган эсеп үчүн вебхук келбейт, натыйжа дароо жоопто болот.

    Вебхукка келүүчү окуялар

    ОкуяКачан
    kaspi_invoice_paidКардар эсепти төлөдү
    kaspi_invoice_expiredЭсепти төлөө мөөнөтү өттү
    kaspi_invoice_cancelledКардар эсептен баш тартты же аны Kaspi'де жокко чыгарышты
    {
      "event": "kaspi_invoice_paid",
      "invoice": {
        "invoiceId": "uuid",
        "externalId": "1024",
        "phone": "+77011234567",
        "amount": 15000,
        "comment": "Буйрутма 1024, кап",
        "status": "paid",
        "createdAt": "2026-11-17T14:00:00.000Z",
        "paidAt": "2026-11-17T14:03:10.000Z"
      },
      "timestamp": "2026-11-17T14:03:40.000Z"
    }

    Окуя статус өзгөргөндөн кийин бир мүнөттүн ичинде келет, WazzaBee'нин башка вебхуктары сыяктуу кол тамга жана кайталоолор менен. Статусту GET /v1/kaspi/invoices/{invoiceId} аркылуу текшерсеңиз болот.

    Мүмкүн болгон каталар

    КодerrorСебеби
    400bad_phone, bad_amount, bad_external_idНомер, сумма же externalId туура эмес
    402no_tariffИштеп турган Kaspi Pay тарифи жок, сыноо мезгили бүттү. Тарифти төлөңүз: Коннекторлор → Kaspi Pay
    402plan_limitБул айда «Старт» тарифинин төлөм лимити түгөндү
    403kaspi_not_enabledБул ачкыч үчүн Kaspi эсептери күйгүзүлгөн эмес
    403kaspi_auto_stoppedМассалык баш тартуулардан улам ачкычтын эсептери автоматтык түрдө токтотулду, колдоо кызматы кайра күйгүзөт
    404not_foundЭсеп ачкычыңыздын эсептеринин арасынан табылган жок
    409not_connected, needs_reauthКассир туташтырылган эмес же аны кабинетте кайра туташтыруу керек
    409not_cancellableЭсеп мурунтан төлөнгөн же жабылган
    429rate_limit_minute, rate_limit_dayАчкычтын эсеп лимитинен ашып кетти
    429kassa_day_limitКассир бир суткада 300 эсеп чыгарды, эртең кайталаңыз
    502kaspi_errorKaspi сурамды кабыл алган жок, кийинчерээк кайталаңыз