Төлем шлюзі интеграциясы
Шлюз қаржылық операцияларды өңдейді. Kevmi оларды тапсырыстарға, дүкен параметрлеріне және хабарландыруларға қосады. Бұл нұсқаулық интеграция келісімшартын және қолжетімділік тексерулерін сипаттайды.
Осы бетте
Қолжетімділікті тексеру#
Kevmi шлюздің v3 API интерфейсін операцияларды құру және қалпына келтіру, статустарды оқу және нәтижелерді үйлестіру үшін пайдаланады. Интеграция шифрланған карточка және банк кодын тасымалдауды, Alipay және SBP QR төлемдерін, крипто монета/желі каталогын және кіріс қаржылық оқиғаларды қолдайды.
gateway.configured GET /api/config ішінде қажетті қосылым параметрлерінің бар-жоғын хабарлайды. Бұл нүкте шлюзді тексермейді; мұнда gateway.connected=false қосылым тексерілмегенін білдіреді. Нақты шот үшін GET /api/checkout/{token} ішінде invoice.availability оқыңыз: ол әдісті, соманы, шарттарды және сатушының мақұлдауын тексереді. invoice.gatewayConnected үйлесімділік өрісі availability.available көрсеткішін көрсетеді және ол да денсаулық тексеруі немесе төлемді мақұлдау кепілдігі емес.
Жаңа төлем және карта ниеті сатушының соңғы веб-сайт шолу өтінімінің мақұлдануын талап етеді. Мақұлдау ғана төлем шлюзін қоспайды. Егер шолу жөнелтілгеннен кейін өзгерсе, бар операция мәртебе оқуы, есеп айырысу және сұралған банк коды үшін қолжетімді болып қалады.
Клиенттің төлем келісімшарты#
Құпия деректер браузерде RSA-OAEP-256 және A256GCM көмегімен шифрланады. Жеке кілт шлюзде қалады. Kevmi ниеттің осы шотқа және мақсатқа тиесілі екенін тексереді, конвертті жібереді және ашық мәтіндегі карточка нөмірлерін, CVV, сатып алушының атын, email, банк кодтарын немесе конверттің өзін сақтамайды.
Карточкаларды қосу алдында шлюз хастына шифрланған тасымалдау кеңейтілімін орнатыңыз. Ол ниет қолтаңбасын, мерзімін, қайталануды, тапсырысты және сомаларды тексереді. Ашық мәтінге ауысу жоқ. Бұл қорғау механизмін сипаттайды, PCI сертификатын емес.
| Kevmi маршруты | Мақсат |
|---|---|
| GET /api/checkout/{token} | Шот, ұсыныс, әдістің қолжетімділігі және бар төлем |
| POST /api/checkout/{token}/card-intent | Төлем немесе код үшін бір реттік intent және ашық кілт |
| POST /api/checkout/{token}/pay | Операцияны бастау; карта мәліметтері шифрланған: {intent,jwe} |
| POST /api/checkout/{token}/code | Ағымдағы банктендіру үшін шифрланған бір реттік код |
| GET /api/checkout/{token}/status | Қосымша төлемсіз бастапқы операцияны оқу |
| POST /api/checkout/{token}/reconcile | Бастапқы операцияны анық келістіру |
| GET /api/checkout/{token}/crypto-services | USDT шоты-фан ағымдағы монеталар, желілер және шектеулер |
Хостинг және шлюз қосылымы#
Kevmi Cloudflare Workers-те D1 арқылы Sites хостингін және Node.js-те SQLite арқылы өз-өзі хостингті қолдайды. SQLite тұрақты көлем мен резервтік көшірмелерді қажет етеді. Төлем шлюзі жеке қызмет ретінде өзінің тұрақты сақтау орнымен жұмыс істейді.
Сыртқы шлюз серверге қолжетімді HTTPS origin талап етеді. Өз-өзі хостингті жинақта сервер жеке контейнер желісіндегі бекітілген шлюз қызметіне қосылады; шлюз қызметінің API интернетке ашық емес. Қоғамдық сайт пен қайта қоңыраулар HTTPS пайдаланады. Браузер сонымен қатар карта мәліметтерін және банк кодтарын Kevmi-ге жеткенге дейін шифрлайды.
localhost ағымдағы серверді немесе контейнерді білдіреді; ол шлюз иесінің компьютерін ашпайды. Қосылу кілттері мен құпиялар тек сервер конфигурациясында болады.
Теңшелетін домен үшін құру алдында NEXT_PUBLIC_SITE_URL ішінде қоғамдық HTTPS origin орнатыңыз. Құжаттама, канондық сілтемелер және индекстеу ресурстары осы мәнді пайдаланады. Ол тек схеманы және хостты, қосымша портпен қабылдайды, жолсыз, сұраныссыз, фрагментсіз немесе тіркелгі деректерінсіз. Оны сервер конфигурациясындағы APP_ORIGIN мәнімен сәйкестендіріңіз.
Есептеу және қолдау көрсетілетін шарттар#
Жаңа жұмыс кеңістігі шоттары АҚШ доллары базалық бағасын пайдаланады, ал Any төрт әдістің барлығын ұсынады. SBP Ресей Банкінің мұздатылған анықтамалық бағамы бойынша рубльге айырбастайды; крипто айқын 1:1 АҚШ доллары/USDT шот ережесін пайдаланады. Мұрагерлік қолма-қол баға белгілеу ескі шоттар мен pricingMode=universal жоқ API сұраулары үшін қолжетімді болып қалады. Төмендегі бірнеше дүкен және АҚШ доллары бағасы бөлімін қараңыз.
Жаңа тірі карта немесе Alipay төлемі үшін ағымдағы шлюз тек feeCustomerPercent=0 және vatCustomerPercent=100 мәндерін қолдайды: сатушы барлық өңдеу комиссиясын жабады, ал ҚҚС клиент үшін толық қосылады. Басқа үлестер шотта сақталып, есептелуі мүмкін, бірақ орындау unsupported_allocation кодымен бұғатталған. Сервер үнсіз сақталған шарттарды өзгертпейді. SBP және USDT крипто төлемдері кез келген өңдеу комиссиясы үлесін қолдайды және ҚҚС жоқ.
Ерікті total_cents жіберу провайдердің салық есептеуін өзгертпейді. Сақталған сомадан ерекшеленетін нақты сома тексеруге түседі және орындалуды растай алмайды. Шлюздің business_balance өрістері есеп айырысу дәлелі ретінде сақталады, Kevmi саудагер балансы ретінде қарастырылмайды.
Тірі шлюзді қосу#
Шлюзді қосу сервер конфигурациясын, таңдалған арналарды тексеруді және расталған қаржылық оқиғаларды өңдеуді қамтиды. Конфигурацияның дайындығы провайдер қосылымынан бөлек тексеріледі. Сәтті төлем операция мәртебесі мен сомасын тексергеннен кейін қабылданады. Орналастыру нұсқаулықтары ops/gateway-integration.md ішінде.
- 1
Kevmi серверін және шлюзді жеке қызметтер ретінде орналастырыңыз. Тұрақты сақтауды, резервтік көшірмелерді және қажетті фондық процестерді конфигурациялаңыз.
- 2
Сыртқы қосылым үшін GATEWAY_BASE_URL ішінде HTTPS origin орнатыңыз. Өз-өзі хостингті жинақта өзінің конфигурацияланған ішкі қызметін пайдаланады. Екеуі де тек серверге арналған GATEWAY_API_KEY және бөлек GATEWAY_WEBHOOK_SECRET талап етеді; құпиялар ешқашан браузерге жетпейді.
- 3
Шлюздің BACKEND_WEBHOOK_URL мәнін Kevmi-де /api/gateway/webhook деп және сәйкес BACKEND_WEBHOOK_SECRET мәнін орнатыңыз.
- 4
Шифрланған карта тасымалын қосыңыз және оның жеке кілтін тек шлюз хостында сақтаңыз. Ашық кілттің қолжетімділігін және сәйкес intent қол қою параметрлерін тексеріңіз.
- 5
Іске қосу алдында арна дайындығын, шектеулерді және саудагер веб-сайтының мақұлдауын тексеріңіз.
Бірнеше дүкен және бір АҚШ доллары базалық бағасы#
Жиынтық аналитика мен операциялар үшін Барлық дүкендерді таңдаңыз немесе жеке жазбалары үшін дүкенді таңдаңыз. Әр дүкеннің жеке 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, оқиғалар тарихы немесе қол қойылған вебхук арқылы тексергеннен кейін орындаңыз.
Көмекші, қолдау және жобаны басқару#
Жеке операцияларға көмек қажет болғанда, чатта менің деректеріме қолжетімділікті қосыңыз. includeAccount=true бар веб-сұраным жарамды сессияны, Origin және X-CSRF-Token-ді талап етеді; X-Kevmi-Store меншікті дүкенді немесе барлық меншікті дүкендерді таңдайды. Рұқсатсыз көмекші тек қоғамдық құжаттаманы пайдаланады. Telegram-да жіберуші анықталғаннан кейін жеке батырма қолжетімділікті қосады.
read_account құралы меншікті дүкендерді, расталған төлем мәртебесі бар шот-фактураларды, оқиғаларды, өтінімдерді және маман жауаптары бар қолдау сұранымдарын оқиды. Ол 30 жазбаны және nextPage-ті қайтарады; ескі жазбалар пагинация арқылы қолжетімді. Әр жауаптағы оқулар шектеулі, сондықтан толық емес үлгі ашық көрсетілуі тиіс. API кілттері, вебхук құпиялары, карта деректері және сессиялар құралға берілмейді. Ол ақы ала алмайды, төлем жасай алмайды, қайтара алмайды немесе параметрлерді өзгерте алмайды.
Жұмыс кеңістігінде немесе Telegram-да қолдау сұранымын жасау тұрақты кезекте бөлек әкімші ескертуін орналастырады. Ол /admin/tickets?ticket=<id> сілтемесімен байланысады; уақытша Telegram ақаулары қайта қайталанады. Қалпына келтіру ескертусіз ескі ашық сұранымдарды да қамтиды. Әкімшілер сұраным бетінде жауап береді; жауап пайдаланушы жұмыс кеңістігінде сақталады және қолдау хабарландыулары қосылғанда Telegram арқылы жіберіледі.
Бот негізгі мәзір, дүкендер, хабарландырулар, қолдау, қауіпсіздік және тіл үшін ішкі батырмаларды пайдаланады. Навигация ағымдағы хабарламаны өңдейді; қолжетімсіз ескі мәзір ауыстырылады. Төлем және қауіпсіздік хабарландырулары бір реттік навигация ретінде қарастырылмайды. Мәзір арқылы жүйеден шығу растауды қажет етеді. Айқын /logout командасы әлі де әрбір аккаунт сессиясын аяқтайды.
/admin/project панелі сервер жағындағы MODERATOR_TELEGRAM_IDS рұқсат тізіміндегі Telegram ID-лерімен шектелген. Ол пайдаланушыларды, дүкендерді, операцияларды, кілтті жоюды, вебхукті өшіруді, шот-фактураны тоқтата тұруды, қабылдау бақылауын және аудит журналын қамтиды. Өзгертулер CSRF және себепті талап етеді. Панель әкімшіні шектей алмайды немесе төлемді қолмен сәтті деп жариялай алмайды. Меншіктісін шектеу сессияларды аяқтайды және API кілтіне қолжетімділікті бұғаттайды; дүкенді шектеу жаңа операцияларды тоқтатады. Тарих сақталады.
Қоғамдық ұсыныс /public-offer мекенжайында және құпиялық саясаты /privacy-policy мекенжайында әрбір қосылған тілде қолжетімді. Монеталарды аты немесе тикері бойынша іздеңіз. Желі таңдағышы тек бірнеше тірі желі болғанда ғана пайда болады. Бір желі автоматты түрде таңдалады және растауда атауы қалады. Тірі шлюз қолжетімділігі таңдалатын жұптарды анықтайды; анықтамалық каталог қызметті қоспайды.
Күнделікті веб-қосымша шығарылымдары үшін update.sh пайдаланыңыз: үміткерді құрастырыңыз, миграция тарихын тексеріңіз, SQLite-ті онлайн резервтеңіз, екінші контейнерді іске қосыңыз, оны тексеріңіз және Caddy-ді бірқалыпты ауыстырыңыз. Gateway, PostgreSQL және пошта қайта іске қосылмайды. Алдыңғы статикалық ресурстар ашық қойындылар үшін қолжетімді болып қалады. Жаңа миграция айқын уәкілеттікпен қарауды қажет етеді; үйлесімсіз схема өзгерісі үздіксіз орналастыру емес.