Төлем сілтемелері API және API кілттері

Сервер сұрауы дайын сілтемені қайтарады#

POST /api/v1/payments және /api/v1/payment-links бірдей шот түрін жасайды. payments маршрутының атауы төлемді білдірмейді: нәтиже — сақталған шот шарттары және тұтынушыға арналған checkoutUrl.

Authorization: Bearer <key>, Content-Type: application/json және Idempotency-Key жіберіңіз. Идемпотенттік кілттер 16–100 әріптен, цифрдан, дефис немесе астыңғы сызықтан тұрады. Әр логикалық тапсырыс жасау үшін бір кілтті сақтаңыз.

curl 'https://kevmi.maxeevmax1.chatgpt.site/api/v1/payments' \
  -H "Authorization: Bearer $KEVMI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1042-create-v1' \
  --data '{"title":"Design project · order 1042","description":"One-time payment for the agreed design work","amountMinor":500,"currency":"USD","methods":["card","alipay"],"vatCustomerPercent":100,"feeCustomerPercent":0,"orderId":"order-1042","metadata":{"campaign":"autumn"}}'

API кілтінің аумақтары және мерзімі#

Расталған мерчант аккаунтыңыздағы /account#keys мекенжайында кілт жасаңыз. Оның толық мәні бір рет көрсетіледі; тек хэш сақталады. Кілттер әдепкі бойынша 90 күн жарамды, рұқсат етілген қызмет мерзімі 1–365 күн және аккаунтқа он белсенді кілтке дейін.

Тек қажетті аумақтарды беріңіз. Қайтарып алу немесе мерзімнің аяқталуы қолжетімділікті тоқтатады. Кілт аккаунт параметрлері, конечный нүктелерін басқару, қосымшалар немесе модерация үшін браузер сеансын алмастырмайды. Оны виджеттерден, URL мекенжайларынан, жалпыға қолжетімді репозиторийлерден және қолдау хабарламаларынан алыс ұстаңыз.

Веб-сайт /api/payment-links мекенжайын өзінің сеанс cookie, нақты Origin және X-CSRF-Token арқылы пайдаланады. Бұл маршруттар бірдей меншікті шоттармен жұмыс істейді.

Any және нақты API әдістері#

Any — интерфейсті таңдау режимі. Жаңа шоттар әдістерді қабылдайды: USD үшін ["card", "alipay"] немесе бос емес ішкі жиын; RUB үшін ["sbp"]; USDT үшін ["crypto"]. any мәні API төлем әдісі емес.

Интерфейстегі жаңа шот үшін USD карталар мен Alipay ұсынады; RUB SBP ұсынады; USDT криптоны ұсынады. API сондай-ақ үйлесімділік үшін USD + криптоны сақтай алады, бірақ оның тірі крипто төлемі crypto_requires_usdt кодымен бұғатталған. USD және USDT бөлек, автоматты айырбастау немесе болжалған 1:1 бағам жоқ. Крипто төлемі бөлек USDT шотын талап етеді.

Жаңа тірі карта немесе Alipay төлемі үшін ағымдағы шлюз тек feeCustomerPercent=0 және vatCustomerPercent=100 мәндерін қолдайды: сатушы барлық өңдеу комиссиясын жабады, ал ҚҚС клиент үшін толық қосылады. Басқа үлестер шотта сақталып, есептелуі мүмкін, бірақ орындау unsupported_allocation кодымен бұғатталған. Сервер үнсіз сақталған шарттарды өзгертпейді. SBP және USDT крипто төлемдері кез келген өңдеу комиссиясы үлесін қолдайды және ҚҚС жоқ.

Өрістер және сақталған шарттар#

Шот мерчант атауын, бағаны, валютаны, әдістерді, екі шығын үлесін және есептелген котировкаларды сақтайды. Метадеректер иеленушіге және сервер оқиғаларында қайтарылады, бірақ жалпыға қолжетімді checkout арқылы емес. Онда төлем құпияларын сақтамаңыз.

Егер үлестер көрсетілмесе, мерчант комиссияны жабады; ҚҚС vatPayer мәнінен немесе аккаунт параметрінен мұрагерлік алады. Ішінара бөлу vatPayer=shared қайтара алады. Атау, orderId және сипаттама жалпыға қолжетімді.

Желі қатесінен кейін қайта әрекеттену#

Бастапқы жасау 201 кодын replayed=false мәнімен қайтарады. Бірдей кілт және канондық дене 200, бастапқы checkoutUrl және replayed=true қайтарады. Бұл кілт астындағы басқа сұрау 409 IDEMPOTENCY_CONFLICT қайтарады.

Таймауттан кейін басқа кілт жасамаңыз. Бастапқы сұрауды бірдей өрістермен қайталаңыз. Алынып тасталған мәндер өзгертілген параметрлерді қайта мұрагерлік алмайды. orderId тапсырысты корреляциялауға көмектеседі, бірақ Idempotency-Key орнын баспайды және сақтауда бірегей болуы талап етілмейді.

Оқу және беттеу#

GET /api/v1/payments сілтемелер мен nextCursor қайтарады; GET /api/v1/payments/{id} бір меншікті сілтемені қайтарады. invoices:read қажет. Әдепкі бет өлшемі — 30; limit 1–100 қабылдайды.

GET тізімі мен толық сипаттама жауаптары link.payment өрісін қамтиды: байланысты операцияның қысқаша сипаттамасы немесе операция жоқ кезде null. POST/PATCH жауаптары оны алып тастауы мүмкін; қысқаша сипаттама қажет болса шотты қайта оқыңыз. Сілтеме күйі жаңа төлемнің басталу мүмкіндігін бөлек сипаттайды. Карта өрістері мен жеке кілттер ешқашан қосылмайды.

nextCursor мәнін өзгеріссіз URLSearchParams арқылы өткізіңіз. null соңын белгілейді; белгісіз және басқа мерчанттардың ID мәндері 404 қайтарады.

GET /api/v1/payments?limit=30
Authorization: Bearer <server-side key>

Кідірту, жалғастыру және болдырмау#

PATCH /api/v1/payments/{id} invoices:write кілтімен тек {"status":"active"}, {"status":"paused"} немесе {"status":"cancelled"} қабылдайды. Болдырмау түпкілікті. expired мерзімінің аяқталу уақытынан шығарылады; мерзімі аяқталған шотты ұзарту мүмкін емес.

Баға, шығын үлестері, сипаттама, orderId, метадеректер және мерзім өзгермейді. Әртүрлі шарттар үшін басқа шот жасаңыз. Қолжетімділікті өзгерту invoice.updated оқиғасын шығарады, сәтті төлем оқиғасын емес.

Тұтынушы жауабы#

GET /api/checkout/{token}?method=card жалпыға қолжетімді шотты, котировканы, әдістің қолжетімділігін және бар операцияны қайтарады. Иеленуші метадеректері, құпиялар және баланстар көрсетілмейді.

POST /api/checkout/{token}/pay сайт Origin және нақты әдісті талап етеді. Карта деректері тек жабық күйде қабылданады: {intent,jwe}, браузер /card-intent алғаннан кейін. Банк кодтары шифрланып /code арқылы жіберіледі. Крипто сақталған USDT шотын және қолжетімді монета/желі жұбын пайдаланады.

Жаңа төлем және карта ниеті сатушының соңғы веб-сайт шолу өтінімінің мақұлдануын талап етеді. Мақұлдау ғана төлем шлюзін қоспайды. Егер шолу жөнелтілгеннен кейін өзгерсе, бар операция мәртебе оқуы, есеп айырысу және сұралған банк коды үшін қолжетімді болып қалады.

Тірі қосылымның жоқтығы GATEWAY_NOT_CONNECTED қайтарады; үйлесімсіз бөлу ешқашан басқа есептеумен алмастырылмайды. Күй және reconcile қайталанатын төлемсіз бастапқы операцияны оқиды.

Бірнеше дүкен және бір АҚШ доллары базалық бағасы#

Жиынтық аналитика мен операциялар үшін Барлық дүкендерді таңдаңыз немесе жеке жазбалары үшін дүкенді таңдаңыз. Әр дүкеннің жеке storeId, атауы, ҚҚС әдепкі мәні, шоттары, API кілттері, вебхук нүктелері, оқиғалар тарихы және веб-сайт қосымшасы бар. Хабарландырулар мен қолдау билеттері тіркелгіге тиесілі. Тіркелгі 100 дүкенге дейін құра алады. Бар жазбалар оның бірінші дүкенінде қалады.

Жаңа жұмыс кеңістігі шоттары pricingMode="universal" және АҚШ доллары базалық бағасын пайдаланады. Any карта, alipay, sbp және криптоны қамтиды; сатушы ішкі жиынтықты таңдай алады. Карталар мен Alipay АҚШ долларымен есептейді. SBP Ресей Банкінің АҚШ доллары/рубль анықтамалық бағамын пайдаланып рубльмен есептейді. Крипто айқын шот ережесі бойынша USDT-мен есептейді: 1 АҚШ доллары = 1 USDT. Бұл шот айырбастау ережесі, нарықтық USDT котировкасы емес. Шлюз таңдалған монетаның бағамын, нақты аударым сомасын және нұсқауларды аударымға дейін береді.

Анықтамалық бағам және екі сома да құру кезінде мұздатылады. Рубльге айырбастауды қамтитын шоттар 24 сағат ішінде мерзімі аяқталады. Егер анықтамалық бағамды алу мүмкін болмаса, құру FX_UNAVAILABLE қатесімен сәтсіз аяқталады; ойдан шығарылған немесе ескірген қосалқы бағам пайдаланылмайды. Меншік иесінің жауабындағы amountMinor және quotes АҚШ доллары бухгалтерлік валютасын пайдаланады. quotes[method].settlement туынды валютадағы төлем котировкасын қамтиды. Қоғамдық төлем беті таңдалған төлем валютасын currency өрісінде, бастапқы бағаны baseAmountMinor/baseCurrency өрістерінде және анықтамалық бағамды fx өрісінде көрсетеді. Төлем жіберілгеннен кейін оның әдісін өзгерту мүмкін емес; шотта бір шлюз операциясы болады.

Мақсатты дүкен ішінде API кілтін жасаңыз және серверіңізден Authorization: Bearer <key> жіберіңіз. Оның дүкенге байланыстыруы өзгермейді; X-Kevmi-Store оған басқа дүкенге қолжетімділік бере алмайды. Браузер сеанстары X-Kevmi-Store: <storeId> таңдайды; оны алып тастағанда бірінші дүкен таңдалады. all мәні тек GET /api/account/dashboard және GET /api/payment-links сұраулары арқылы қабылданады. Өзгертулер таңдалған дүкенді, Origin және X-CSRF-Token талап етеді. Тіркелгі идентификаторлары мен дүкен идентификаторлары әртүрлі идентификаторлар болып табылады.

Үйлесімділік үшін pricingMode="universal" жоқ API сұраулары қолма-қол баға белгілеуді және бастапқы валюта шектеулерін сақтайды. Бар шоттар ешқашан қайта есептелмейді. Аналитикадағы расталған түбіртектер тексерілген төлемдерден сақталған шот шығындарын шегергендегі соманы көрсетеді; олар шығарылатын баланс емес. Мұрагерлік шот валюталары бөлек қалады, ал төлемдер қолдау қызметімен келісіледі. Тапсырысты тек payment.fulfillmentReady=true және payment.status="succeeded" сервер API, оқиғалар тарихы немесе қол қойылған вебхук арқылы тексергеннен кейін орындаңыз.