Тест кассасы, xapi_test_… тест кілттері және төлем нәтижесін имитациялау (төленді, бас тартылды, мерзімі өтті, қате): интеграция мен вебхуктарды Kaspi-сіз баптаңыз.
Sandbox — xpayment-тің тест режимі: сол API v2 сұраныстары, сол күйлер және сол вебхуктар, бірақ нақты Kaspi-сіз және нақты ақшасыз. Шот шығарып, оны бір түймемен немесе бір сұраныспен «төлеп», бас тартуды, мерзімнің өтуін және қатені тексеріп, вебхук өңдеушіңіздің әр нәтижеге дұрыс әрекет ететініне көз жеткізе аласыз.
Sandbox мыналар үшін қажет:
Тест деректері боевой деректерден бөлек сақталады: sandbox сіздің нақты төлемдеріңізге, теңгеріміңізге немесе вебхуктарыңызға тиіспейді. Кабинетте Песочница (Sandbox) бөлімі бар; режим серверде уақытша өшірулі болса, кабинет sandbox қолжетімсіз екенін хабарлайды.
| Боевой режим | Sandbox |
|---|---|
| Касса — сіздің Kaspi Pay кассиріңіз | Бір тест кассасы: API атауы test, атауы «Тестовая касса» |
API v2 кілті xapi_… |
Тест кілті xapi_test_… |
API v1 касса кілті xdev_… |
Тест кілті xdev_test_… |
| Төлемді Kaspi өңдейді | Нәтижені сіз анықтайсыз |
| Вебхуктар сіздің жазылымдарыңызға | Вебхуктар тест жазылымдарына, денесінде "environment": "sandbox" |
API мекенжайы сол: https://api.xpayment.kz/v2. Қандай сұраныс боевой, қандайы тест екенін кілт анықтайды: тест кілті әрдайым sandbox-қа, боевой кілт боевой режимге түседі. Сондықтан режимдер арасында баптауларда кілт пен касса атауын ауыстыру арқылы ауыса аласыз.
Sandbox-тың қалғаны боевой режимдегідей жұмыс істейді: төлем сол кезеңдерден (PENDING, WAITING_FOR_PAYER, түпкілікті күй) өтеді, вебхуктарға дәл солай қол қойылады, қайтарымдар сол жолмен жүреді.
Кабинетте Песочница (Sandbox) бөлімін ашыңыз. Онда төрт бөлім бар: касса, кілттер, вебхуктар және төлемдер.
Алғаш рет қолданғанда xpayment сізге тест кассасын жасайды: API атауы test, атауы «Тестовая касса». Ол әр пайдаланушыға біреу; Kaspi кассирін де, SMS-кодты да қажет етпейді, жойылмайды және қайта аталмайды. Оны API арқылы да көруге болады:
curl https://api.xpayment.kz/v2/devices \
-H "Authorization: Bearer xapi_test_СІЗДІҢ_ТЕСТ_КІЛТІҢІЗ"
Тест кілтімен тізімде тек test кассасы болады.
«Ключи» (Кілттер) бөлімінде API v2 тест кілтін xapi_test_… жасаңыз. Боевой кілт сияқты, ол бір рет көрсетіледі, ал тізімде оның алғашқы таңбалары көрінеді. Белсенді тест кілттері ең көбі 10 болуы мүмкін. API v1 кілті (xdev_test_…) сол жерде шығарылады және test кассасында жұмыс істейді.
Боевой кілт sandbox-та жұмыс істемейді, ал тест кілті боевой деректерде жұмыс істемейді. Тест және боевой кілттерді әртүрлі орта айнымалыларында сақтаған жөн.
Sandbox-тың «Вебхуки» (Вебхуктар) бөлімінде тест жазылымын жасаңыз: өңдеушіңіздің мекенжайы, оқиғалар және secret. Бұл жазылымдар ұйымға емес, сізге жеке тиесілі және тек тест төлемдерінің оқиғаларын алады. Қолтаңба боевой режимдегідей: Вебхук қолтаңбасын тексеру. Байланысты «Тест» түймесімен немесе тест кілтімен POST /v2/webhook-simulate сұранысымен тексеруге болады: оқиға "environment": "sandbox" деп сіздің тест жазылымдарыңызға кетеді.
Төлемді боевой режимдегідей жасаңыз, бірақ тест кілтімен және test кассасымен:
curl -X POST https://api.xpayment.kz/v2/payments/link \
-H "Authorization: Bearer xapi_test_СІЗДІҢ_ТЕСТ_КІЛТІҢІЗ" \
-H "Content-Type: application/json" \
-d '{"device_name": "test", "amount": 1500, "merchant_order_id": "order-42"}'
Төлем sandbox-тың «Платежи» (Төлемдер) бөлімінде пайда болады. Телефонға шот та жұмыс істейді (POST /v2/payments). Дәл сол төлемдерді кабинеттен Выставить тестовый счёт (Тест шотын шығару; телефонға шот) және Тестовая ссылка (Тест сілтемесі) түймелерімен шығаруға болады.
Тест сілтемесі …/sandbox/qr/{id} түріндегі xpayment бетіне апарады және қысқа мерзімді боевой сілтеме сияқты 5 минут әрекет етеді. Бет соманы мен күйді көрсетеді және өздігінен жаңарады, бірақ онда төлеу мүмкін емес: нәтижені sandbox түймелерімен немесе simulate сұранысымен орнатасыз (келесі бөлім).
Тест төлемі өздігінен аяқталмайды: нәтижені сіз таңдайсыз. Екі жолы бар.
Sandbox-тың «Платежи» (Төлемдер) бөлімінде аяқталмаған төлемде Оплачено (Төленді), Клиент отклонил (Клиент бас тартты), Истёк (Мерзімі өтті) және Ошибка (Қате) түймелері бар.
curl -X POST https://api.xpayment.kz/v2/sandbox/payments/PAYMENT_ID/simulate \
-H "Authorization: Bearer xapi_test_СІЗДІҢ_ТЕСТ_КІЛТІҢІЗ" \
-H "Content-Type: application/json" \
-d '{"outcome": "paid"}'
outcome |
Түпкілікті күй | Вебхук |
|---|---|---|
paid |
COMPLETED |
payment.completed |
declined |
CANCELLED |
payment.cancelled |
expired |
EXPIRED |
payment.expired |
failed |
FAILED |
payment.failed |
Төлем нәтижені бірден, боевой төлеммен бірдей ережелермен қолданады: күй өзгереді, ал вебхук сіздің тест жазылымдарыңызға кетеді. API v1 үшін мекенжай — xdev_test_… кілтімен POST /v1/sandbox/payments/{id}/simulate.
Ережелер мен қателер:
PENDING, WAITING_FOR_PAYER, QR_TOKEN_CREATED);409 SANDBOX_OUTCOME_NOT_ALLOWED қайтарады;403 SANDBOX_ONLY алады;outcome — 400 VALIDATION_ERROR; бөтен немесе жоқ төлем — 404 PAYMENT_NOT_FOUND.Есіңізде болсын: xpayment-те
failedбоевой режимде де түпкілікті күй емес: Төлем күйлері мен қайтарымдар.
paid → вебхук қайта келсе де, тапсырысыңыз бір рет орындалады.declined, expired → резерв алынады, сатып алушыға жаңа әрекет ұсынылады.failed → тапсырыс бірден есептен шығарылмайды, GET /v2/payments/{payment_id} арқылы тексересіз.Sandbox-тағы кейбір мәндер әрдайым бірдей қате береді, сондықтан Kaspi бас тартуларын өңдеуіңізді тексере аласыз.
| Не істеу керек | Нәтиже |
|---|---|
POST /v2/payments телефонға шот, нөмір 7000000001 деп аяқталады |
422 KASPI_CLIENT_NOT_FOUND: Kaspi мұндай клиентті білмейді |
Телефонға шот, нөмір 7000000002 деп аяқталады |
422 KASPI_ERROR: Kaspi қатесі |
| Дәл 13.13 ₸ қайтарым | Қайтарым қабылданбайды: күйі FAILED, вебхук payment.refund_failed |
Sandbox-тағы қайтарымдар боевой режимдегідей жұмыс істейді: POST /v2/payments/{id}/refund арқылы жасалады, фонда өңделеді және payment.refunded немесе payment.refund_failed вебхугімен аяқталады. Толығырақ: Төлем күйлері мен қайтарымдар.
GET /v2/static-qr-payments/{orderNumber} 404 NOT_AVAILABLE_IN_SANDBOX қайтарады.test.Sandbox-та дерек жасайтын сұраныстар (төлем, сілтеме, қайтарым және нәтижені имитациялау) шектелген: пайдаланушыға минутына 60 және тәулігіне 1000. Асып кетсе, API Retry-After тақырыбымен 429 RATE_LIMITED жауап береді. Дәл сол сұраныстар боевой кілтпен бұл лимитке есептелмейді.
Бәрі жұмыс істегенде:
xapi_… кілтін жасаңыз.device_name: "test" мәнін боевойға ауыстырыңыз.Бірдеңе дұрыс болмаса, төлем күйлерін және вебхук қолтаңбасын тексеріңіз.