xpayment Sandbox: нақты ақшасыз тест төлемдері

Тест кассасы, xapi_test_… тест кілттері және төлем нәтижесін имитациялау (төленді, бас тартылды, мерзімі өтті, қате): интеграция мен вебхуктарды Kaspi-сіз баптаңыз.

Sandbox неге қажет

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) бөлімін ашыңыз. Онда төрт бөлім бар: касса, кілттер, вебхуктар және төлемдер.

1. Тест кассасы

Алғаш рет қолданғанда xpayment сізге тест кассасын жасайды: API атауы test, атауы «Тестовая касса». Ол әр пайдаланушыға біреу; Kaspi кассирін де, SMS-кодты да қажет етпейді, жойылмайды және қайта аталмайды. Оны API арқылы да көруге болады:

curl https://api.xpayment.kz/v2/devices \
  -H "Authorization: Bearer xapi_test_СІЗДІҢ_ТЕСТ_КІЛТІҢІЗ"

Тест кілтімен тізімде тек test кассасы болады.

2. Тест кілті

«Ключи» (Кілттер) бөлімінде API v2 тест кілтін xapi_test_… жасаңыз. Боевой кілт сияқты, ол бір рет көрсетіледі, ал тізімде оның алғашқы таңбалары көрінеді. Белсенді тест кілттері ең көбі 10 болуы мүмкін. API v1 кілті (xdev_test_…) сол жерде шығарылады және test кассасында жұмыс істейді.

Боевой кілт sandbox-та жұмыс істемейді, ал тест кілті боевой деректерде жұмыс істемейді. Тест және боевой кілттерді әртүрлі орта айнымалыларында сақтаған жөн.

3. Тест вебхугі

Sandbox-тың «Вебхуки» (Вебхуктар) бөлімінде тест жазылымын жасаңыз: өңдеушіңіздің мекенжайы, оқиғалар және secret. Бұл жазылымдар ұйымға емес, сізге жеке тиесілі және тек тест төлемдерінің оқиғаларын алады. Қолтаңба боевой режимдегідей: Вебхук қолтаңбасын тексеру. Байланысты «Тест» түймесімен немесе тест кілтімен POST /v2/webhook-simulate сұранысымен тексеруге болады: оқиға "environment": "sandbox" деп сіздің тест жазылымдарыңызға кетеді.

4. Бірінші тест төлемі

Төлемді боевой режимдегідей жасаңыз, бірақ тест кілтімен және 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-тың «Платежи» (Төлемдер) бөлімінде аяқталмаған төлемде Оплачено (Төленді), Клиент отклонил (Клиент бас тартты), Истёк (Мерзімі өтті) және Ошибка (Қате) түймелері бар.

API арқылы

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.

Ережелер мен қателер:

Есіңізде болсын: xpayment-те failed боевой режимде де түпкілікті күй емес: Төлем күйлері мен қайтарымдар.

Нені тексеру керек

  1. Сәттілік: paid → вебхук қайта келсе де, тапсырысыңыз бір рет орындалады.
  2. Бас тарту және мерзімнің өтуі: declined, expired → резерв алынады, сатып алушыға жаңа әрекет ұсынылады.
  3. Қате: failed → тапсырыс бірден есептен шығарылмайды, GET /v2/payments/{payment_id} арқылы тексересіз.
  4. Қолтаңба: қолтаңбасы қате вебхук қабылданбайды, дұрысы қабылданады.
  5. Қайталау: өңдеушіңіз 2xx емес жауап берсе, вебхук қайталанады (үш әрекетке дейін), ал тапсырыс бәрібір бір рет орындалады.

Болжамды қателер

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 вебхугімен аяқталады. Толығырақ: Төлем күйлері мен қайтарымдар.

Шектеулер және тазалау

Sandbox-та не жоқ

Сұраныс лимиттері

Sandbox-та дерек жасайтын сұраныстар (төлем, сілтеме, қайтарым және нәтижені имитациялау) шектелген: пайдаланушыға минутына 60 және тәулігіне 1000. Асып кетсе, API Retry-After тақырыбымен 429 RATE_LIMITED жауап береді. Дәл сол сұраныстар боевой кілтпен бұл лимитке есептелмейді.

Тазалау

Боевой режимге көшу

Бәрі жұмыс істегенде:

  1. Боевой кассаны қосыңыз: Кассаны қосу және API v2 кілті.
  2. Боевой xapi_… кілтін жасаңыз.
  3. Баптауларда тест кілті мен device_name: "test" мәнін боевойға ауыстырыңыз.
  4. Вебхуки (Вебхуктар) бөлімінде боевой вебхук жазылымын жасаңыз.
  5. Шағын соммаға бірінші нақты төлем жасап, оны болдырмаңыз немесе қайтарыңыз.

Бірдеңе дұрыс болмаса, төлем күйлерін және вебхук қолтаңбасын тексеріңіз.