Сұрақтарыңыз бар болса, бір түймен біргеміз

Бізге хабарласу
Кілт сөз арқылы іздеу
/

REST API сипаттамасы

REST — бұл желі арқылы деректерді тасымалдаудың қарапайым әдісі. Деректер параметрлер жиынтығы бар HTTP-сұрауларыарқылы тасымалданады. Өңделген сұраулар JSON нысандары түрінде қайтарылады (жауап мысалын төменде қараңыз).

{
  "errorCode": "12",
  "errorMessage": "Empty amount"
}

Сынақ карталар

Сынақ өткізу мақсатында келесі сынақ карталарды пайдалануға болады.

Карта нөмірі (SSL) 4444 5555 1111 3333
Жарамдылық мерзімі 12/24
CVC 123
Карта нөмірі (3DS1) 4012 0010 3816 6662
Жарамдылық мерзімі 12/24
CVC 123
3-D Secure растау коды 12345678
Карта нөмірі (3DS2) 5555 5555 5555 5599
Жарамдылық мерзімі 12/24
CVC 123

Мерчант аутентификациясы

Төлем шлюзінде мерчант аутентификациясын орындау үшін екі әдісті қолдануға болады.

Міндетті Атау Түрі Сипаттама
Сипаттаманы көру

userName String Сатушының API есептік жазбасының логині. Аутентификация үшін тіркелу кезінде пайдаланушы аты мен құпиясөз орнына токен пайдаланылса (token параметрі), құпиясөзді жіберудің қажеті жоқ.
Сипаттаманы көру

password String Сатушының API есептік жазбасының құпиясөзі. Аутентификация үшін тіркелу кезінде пайдаланушы аты мен құпиясөз орнына токен пайдаланылса (token параметрі), құпиясөзді жіберудің қажеті жоқ.
Міндетті Атау Түрі Сипаттама
Сипаттаманы көру

token String Төлем шлюзіне сұрауларды жіберген кезде сатушы аутентификациясы үшін пайдаланылатын мән. Осы параметрді көрсетсеңіз, userName және password көрсетілмеуі керек.

REST протоколы арқылы, application/x-www-form-urlencoded түріндегі сұрауларды жіберу (multipart/form-data түрінде жібермеу).

Қосылым координаттары

Сұраулар келесі талаптарға сәйкес болуы керек:

Төмендегі кестеде REST сұрауларына қатынасуға болатын URL-мекенжайлары көрсетілген.

Сұрау URL

Тапсырысты тіркеу

 https://3dsec.berekebank.kz/payment/rest/register.do

Алдын ала авторизациядан өтетін тапсырысты тіркеу

 https://3dsec.berekebank.kz/payment/rest/registerPreAuth.do

Тапсырысты аяқтау сұрауы

 https://3dsec.berekebank.kz/payment/rest/deposit.do

Қаражатты қайтару сұрауы

 https://3dsec.berekebank.kz/payment/rest/refund.do

Тапсырыс күйінің сұрауы

 https://3dsec.berekebank.kz/payment/rest/getOrderStatusExtended.do

Байламдар арқылы төлеу

 https://3dsec.berekebank.kz/payment/rest/paymentOrderBinding.do

Тапсырыс үшін төлеу сұрауы, карта деректері мерчант тарапынан жиналады - валидация

 https://3dsec.berekebank.kz/payment/rest/paymentOrder.do

Тапсырыс үшін төлеу сұрауы, карта деректері мерчант тарапынан жиналады

 https://3dsec.berekebank.kz/payment/rest/paymentOrder.do

Тапсырыс үшін төлеу сұрауы, карта деректері мерчант тарапынан жиналады

 https://3dsec.berekebank.kz/payment/rest/paymentOrder.do

Егер сіз REST-сұрауларын төлем шлюзінің сатушы консоліне кірген браузерден тексерсеңіз, кез келген REST сұрауын орындау төлем шлюзінің сатушы консоліндегі қатеге себеп болады. Төлем шлюзінің сатушы консоліндегі сеансты қалпына келтіру үшін мына қадамдарды орындау керек:

Қатенің пайда болуын алдын алу үшін төмендегі әдістердің бірін орындауға болады:

Интеграция үлгісі

Төлем шлюзінің төлем бетіндегі карта деректерін енгізу арқылы төлем жасау

№ Бір кезеңді төлем Екі кезеңді төлем
1 Сатып алушы тауарлар мен қызметтерді таңдап, төлем әдісі ретінде төлем картасын пайдаланады. Сатып алушы тауарлар мен қызметтерді таңдап, төлем әдісі ретінде төлем картасын пайдаланады.
2 Мерчант төлем шлюзіне тапсырысты тіркеу сұрауын жібереді:
register.do.
Басқа параметрлерге қоса, мына параметрлер көрсетіледі:
  • returnUrl – төлем сәтті аяқталған кезде клиент бағытталатын URL-мекенжайы;
  • failUrl – төлем сәтсіз аяқталған кезде клиент бағытталатын URL-мекенжайы.
 Мерчант авторизациядан бұрын төлем шлюзіне тапсырысты тіркеу сұрауын жібереді:
registerPreAuth.do.
Басқа параметрлерге қоса, мына параметрлер көрсетіледі:
  • amount – есептен шығару сомасы;
  • orderNumber – мерчант жүйесіндегі тапсырыс нөмірі;
  • returnUrl – төлем сәтті аяқталған кезде клиент бағытталатын URL-мекенжайы;
  • failUrl – төлем сәтсіз аяқталған кезде клиент бағытталатын URL-мекенжайы;
3 Басқа параметрлерге қоса, төлем шлюзі мына параметрлерді қайтарады:
  • orderId – төлем шлюзіндегі тапсырыстың бірегей нөмірі;
  • formUrl – төлем пішімінің URL-мекенжайы.
 Басқа параметрлерге қоса, төлем шлюзі мына параметрлерді қайтарады:
  • orderId – төлем шлюзіндегі тапсырыстың бірегей нөмірі;
  • formUrl – төлем пішімінің URL-мекенжайы.
4 Сатушы пайдаланушыны formUrl жауап параметрінде көрсетілген мекенжай бойынша өткізеді. Сатушы клиентті formUrl сұрау параметрінде көрсетілген мекенжай бойынша өткізеді.
5 Клиентке төлем картасының деректерін енгізу пішіні көрсетіледі. Клиент алған пішінді толтырып, деректерді төлем шлюзінің серверіне жібереді. 5
6 Кейінгі әрекеттер клиенттің картасында 3-D Secure протоколының бар-жоғына байланысты болады:
  • 3-D Secure протоколына қолдау көрсетілмейді – үдерістің келесі қадамына өту;
  • 3-D Secure протоколына қолдау көрсетіледі – төлем шлюзі клиентті банк-эмитенттің ACS серверіндегі аутентификация (көп жағдайда, SMS-аутентификация) пішініне өткізеді және аутентификация сәтті өтсе, үдеріс аяқталады.
 Кейінгі әрекеттер клиенттің картасында 3-D Secure протоколының бар-жоғына байланысты болады:
  • 3-D Secure протоколына қолдау көрсетілмейді – үдерістің келесі қадамына өту;
  • 3-D Secure протоколына қолдау көрсетіледі – төлем шлюзі клиентті банк-эмитенттің ACS серверіндегі аутентификация (көп жағдайда, SMS-аутентификация) пішініне өткізеді және аутентификация сәтті өтсе, үдеріс аяқталады.
7 Төлем шлюзі тіркелген тапсырыстың сомасын есептен шығарады.
8 Төлем өңделген соң, төлем шлюзі клиентті returnUrl бетіне бағыттайды. Төлем өңделген соң, төлем шлюзі клиентті returnUrl бетіне бағыттайды.
9 Клиенттің браузерінде дүкеннен төлем нәтижелері көрсетілген беттің ашылуы талап етіледі. Клиенттің браузерінде дүкеннен төлем нәтижелері көрсетілген беттің ашылуы талап етіледі.
10 Сатушы төлем шлюзінен (orderId):
getOrderStatusExtended.do тапсырысын тіркеу кезінде алынған бірегей идентификаторды пайдаланып, тапсырыс күйін талап етеді.		 Сатушы төлем шлюзінен (orderId):
getOrderStatusExtended.do тапсырысын тіркеу кезінде алынған бірегей идентификаторды пайдаланып, тапсырыс күйін талап етеді.
11 Төлем шлюзі дүкенге төлем күйін қайтарады, ал дүкен төлем нәтижесін клиент браузеріне жібереді. Төлем шлюзі дүкенге төлем күйін қайтарады, ал дүкен төлем нәтижесін клиент браузеріне жібереді.
12 N/A Клиенттен қаражатты алу үшін сатушы тапсырысты аяқтау сұрауын жіберуі тиіс:
deposit.do.
13 N/A Төлем шлюзі жауапты жібереді. Тапсырыс күйі қайтарылмайды. Тапсырыс күйін алу үшін төлем шлюзіне getOrderStatusExtended сұрауын жіберіңіз:
getOrderStatusExtended.do.

Тапсырыс күйін алу үшін getOrderStatusExtended сұрауының орнына кері қоңырау хабарландыруларын пайдалануға болады. Осы хабарландырулар сізге автоматты түрде тапсырыс күйі өзгергеннен кейін жіберіледі.

Қаражатты қайтару

Төлем шлюзінде қаражатты толық немесе ішінара қайтаруға болады. ** Deposited** (Аяқталды) күйіндегі тапсырыстар бойынша қаражатты қайтаруға болады. Төмендегі кестеде қаражатты қайтару кезіндегі әрекеттер көрсетілген.

№ Әрекет
1 Сатушы қаражатты қайтаруды сұрады (refund):
refund.do.
2 Сәтті жауаптан кейін сатушы тапсырыс күйін сұрайды:
getOrderStatusExtended.do.

Тапсырыс күйін алу үшін getOrderStatusExtended сұрауының орнына кері қоңырау хабарландыруларын пайдалануға болады. Осы хабарландырулар сізге автоматты түрде тапсырыс күйі өзгергеннен кейін жіберіледі.

REST API бойынша анықтама

Электронды саудаға арналған негізгі мүмкіндіктерді тексеріп көру мақсатында Postman үшін API-сұратымдарының топтамасын жүктеп алуыңызға болады.

Postman топтамасын жүктеу

Тапсырысты тіркеу

Тапсырысты тіркеу үшін register.do сұрауы пайдаланылады.

Сұрау параметрлері

Міндетті Атау Түрі Сипаттама
Сипаттаманы көру

userName String Сатушының API есептік жазбасының логині. Аутентификация үшін тіркелу кезінде пайдаланушы аты мен құпиясөз орнына токен пайдаланылса (token параметрі), құпиясөзді жіберудің қажеті жоқ.
Сипаттаманы көру

password String Сатушының API есептік жазбасының құпиясөзі. Аутентификация үшін тіркелу кезінде пайдаланушы аты мен құпиясөз орнына токен пайдаланылса (token параметрі), құпиясөзді жіберудің қажеті жоқ.
Сипаттаманы көру

token String Төлем шлюзіне сұрауларды жіберген кезде сатушы аутентификациясы үшін пайдаланылатын мән. Осы параметрді көрсетсеңіз, userName және password көрсетілмеуі керек.
Сипаттаманы көру

orderNumber Alphanumeric Мерчант жүйесіндегі тапсырыс нөмірі (ID); әр мерчант үшін бірегей болуы керек.
Иә

amount Integer Ең төменгі валюта бірліктерінде көрсетілген төлем сомасы (мысалы, тиынмен).
Жоқ

currency Integer ISO 4217 төлем валютасының коды. Көрсетілмеген жағдайда, әдепкі мән пайдаланылады.
Иә

returnUrl String Төлем сәтті орындалған жағдайда, пайдаланушы бағытталатын мекенжай. Мекенжайды пайдаланылатын протоколымен бірге толық көрсету қажет (мысалы, test.ruорнына https://test.ru ). Кері жағдайда, пайдаланушы мына мекенжайға бағытталады: «https://https://3dsec.berekebank.kz/payment/».
Жоқ

failUrl String Төлем орындалмаған жағдайда, пайдаланушы бағытталатын мекенжай. Мекенжайды пайдаланылатын протоколымен бірге толық көрсету қажет (мысалы, test.ruорнына https://test.ru ). Кері жағдайда, пайдаланушы мына мекенжайға бағытталады: «https://https://3dsec.berekebank.kz/payment/».
Жоқ

dynamicCallbackUrl String Параметр callback-хабарландыруларын динамикалық түрде жіберу функциясын пайдалануға мүмкіндік береді. Осында мерчант үшін белсендірілген барлық «төлемді» callback-хабарландырулары жіберілетін мекенжайды көрсетуге болады. «Төлемді» – мына операциялар туралы callback-хабарландыруларды білдіреді: қаражатты сәтті ұстап тұру (холд), төлемді таймаут үшін өткізбеу, cardpresent төлемін қабылдамау, сәтті іске асырылған есептен шығару, қайтару, бас тарту. Осында «төлемді» болып табылмайтын мерчант үшін белсендірілген callback-хабарландырулары (байламды қосу/ажырату, байламды жасау) callback-хабарландыруларының статикалық мекенжайына жіберіледі. Параметрді пайдалану қажеттілігі төлем шлюзі тарапындағы сатушы конфигурацияларына байланысты болады.
Жоқ

description String Кез келген пішімдегі тапсырыс сипаттамасы.
Осы өрісті процессинг жүйесіне жіберу функциясын қосу үшін техникалық қолдау көрсету қызметіне хабарласыңыз.
Жоқ

language Alphabetic ISO 639-1 бойынша тіл кілті. Көрсетілмесе, әдепкі бойынша дүкен параметрлерінде таңдалған тіл пайдаланылады.
Жоқ

clientId Alphanumeric Мерчант жүйесіндегі клиенттің нөмірі (ID) — 255 таңбаға дейін. Байламдардың функцияларын орындау үшін қолданылады. Мерчантқа байламдарды жасауға рұқсат етілсе, жауап ретінде қайтарылуы мүмкін.
Төлемдер байлам арқылы өңделген кезде осы параметрді міндетті түрде таңдау қажет. Кері жағдайда, төлемді жасау мүмкін болмайды.
Жоқ

merchantLogin String Тапсырысты еншілес мерчанттың атынан тіркеу үшін оның логинін осы параметрде көрсетіңіз.
Жоқ

jsonParams String Мерчанттың қосымша параметрлерін көрсету бөлімі. Кейін сақтауға арналған қосымша ақпарат өрістері.
{name1:value1,…,nameN:valueN}
Осы өрістер кейін банк реестрінде көрсету үшін банк процессингіне жіберілуі мүмкін.
Осы функцияны қосу үшін банкіңізге хабарласыңыз.
Мерчант үшін сатып алушылар туралы хабарландырулар орнатылған болса, осы бөлімде сатушының электрондық пошта мекенжайы бар email параметрі көрсетілуі керек.
Әдепкі бойынша банк процессингіне мына параметрлер жіберіледі:
  • orderNumber - мерчант жүйесіндегі тапсырыс нөмірі;
  • description - тапсырыс сипаттамасы (99 таңбаға дейін пайдаланылып, келесі таңбаларды қолдануға рұқсат берілмейді: %, +, күймешені қайтару \r және жолды түсіру \n).

Егер merchantOrderId көрсетілсе, оның мәні банк процессингіне тапсырыс нөмірі ретінде жіберіледі (orderNumber параметрінің орнына).
Жоқ

sessionTimeoutSecs Integer Тапсырыстың секундпен берілген мерзімі. Параметр көрсетілмесе, мерчант параметрлерде көрсеткен мән немесе әдепкі уақыт (1200 секунд = 20 минут) пайдаланылады. Сұрауда expirationDate параметрі бар болса, sessionTimeoutSecs параметрінің мәні ескерілмейді.
Жоқ

expirationDate String Тапсырыс мерзімінің аяқталу күні және уақыты. Формат: yyyy-MM-ddTHH:mm:ss.
Осы параметр сұрауда берілмеген жағдайда, тапсырыс мерзімінің аяқталу күнін анықтау үшін sessionTimeoutSecs параметрі пайдаланылады.
Жоқ

bindingId String Бұрын жасалған байламның идентификаторы. Оны тек мерчанттың байламдармен жұмыс істеуге рұқсаты бар болған жағдайда ғана пайдалануға болады.
Жоқ

features String Төменде рұқсат етілетін мәндер көрсетілген.
  • AUTO_PAYMENT - төлем карта иесінің түпнұсқалығын тексерусіз жүзеге асырылады (CVC және 3D-Secure кодтары талап етілмейді). Осындай төлемдерді жасау үшін мерчантта тиісті рұқсаттар болуы керек.
  • VERIFY- осы мәнді тапсырысты рәсімдеу сұрауында көрсеткен кезде, карта иесі верификациядан өтеді, (оған 3-D Secure үдерісінен өту қажет болады), дегенмен, қаражат алынбайды, себебі осы жағдайда amount параметрі 0 мәнінде болуы мүмкін. Верификация картаның өз иесінде екеніне көз жеткізуге және осыдан кейін төлемдер жасаған кезде бұл картадан аутентификация деректерін (CVC, 3D-Secure) тексермей, қаражатты есептен шығаруға мүмкіндік береді. Сұрауда төлем сомасы көрсетілсе де, VERIFY мәні берілген кезде бұл сома клиент шотынан алынбайды. Тіркелу сәтті аяқталған соң, тапсырыс бірден REVERSED (бас тартылды) күйіне өтеді.
  • FORCE_TDS - 3-D Secure қорғанысын пайдалану арқылы төлемді мәжбүрлі түрде орындау. Карта 3-D Secure қорғанысына қолдау көрсетпесе, транзакция өтпейді.
  • FORCE_SSL - SSL арқылы (3-D Secure қорғанысы жоқ) төлемді мәжбүрлі түрде орындау.
  • FORCE_FULL_TDS - 3-D Secure арқылы аутентификацияны орындағаннан кейін, PaRes күйі тек Y болуы керек, бұл пайдаланушының сәтті аутентификациясын қамтамасыз етеді. Кері жағдайда, транзакция өтпейді.
Жоқ

phone Integer Сатып алушының телефон нөмірі. Ел кодын әрқашан көрсету керек, осында + белгісін көрсетуге не көрсетпеуге болады. Осылайша, келесі нұсқалар қолжетімді болады:
  • +79998887766;
  • 79998887766. Цифрлардың рұқсат етілген саны: 7-15 аралығында.
Жоқ

email String Клиенттің электрондық пошта мекенжайы.
Сипаттаманы көру

billingPayerData Object Клиенттің AVS/AVV қызметтері аясында мекенжай тексерісінен өту үшін қажетті тіркеу деректері (мекенжай, пошта индексі) бар блок. Төлем шлюзінің тарапынан сатушы үшін функция қосулы болған жағдайда міндетті болып табылады.

Төменде billingPayerData блогының параметрлері келтірілген (клиентті тіркеу мекенжайы туралы деректер).

Міндетті Атау Түрі Сипаттама
Жоқ

billingCity String Эмитент банктің нақты картасы бойынша тіркелген қала.
Жоқ

billingCountry String Эмитент банктің нақты картасы бойынша тіркелген ел (ISO 3166-1, сандық).
Жоқ

billingAddressLine1 String Эмитент банктің нақты картасы бойынша тіркелген мекенжай. 1-жол. AVS-тексерісі үшін берілуі міндетті.
Жоқ

billingAddressLine2 String Эмитент банктің нақты картасы бойынша тіркелген мекенжай. 2-жол.
Жоқ

billingAddressLine3 String Эмитент банктің нақты картасы бойынша тіркелген мекенжай. 3-жол.
Жоқ

billingPostalCode String Эмитент банктің нақты картасы бойынша тіркелген пошта индексі. AVS-тексерісі үшін берілуі міндетті.
Жоқ

billingState String Эмитент банктің нақты картасы бойынша тіркелген штат.

Жауап параметрлері

Міндетті Атау Түрі Сипаттама
Жоқ

formUrl String Сатып алушы бағытталатын төлем пішінінің URL-мекенжайы. Тапсырысты тіркеу errorCode кодында көрсетілген қатеге байланысты сәтсіз аяқталса, URL қайтарылмайды.
Жоқ

errorCode Integer Қате коды. Қате орын алмаған кезде, болмауы мүмкін.
Жоқ

orderId String Төлем шлюзіндегі тапсырыс нөмірі. Төлем шлюзі ауқымында бірегей болып табылады.
Жоқ

errorMessage String Қате сипаттамасы. Сипаттама тілі сұраудың language параметрінде таңдалады.

Қателер коды

Қате коды Хабар
0 Сұрауды өңдеу жүйелік қателерсіз аяқталды.
1 Көрсетілген нөмірі бар тапсырыс өңделіп қойды.
1 Тапсырыс нөмірі дұрыс емес
3 Белгісіз валюта.
4 Тапсырыс нөмірі бос болмауы керек
4 Сатушы аты бос болмауы керек
4 Сома көрсетілмеген
4 Қайтару URL-мекенжайы бос болмауы керек
4 Құпиясөз бос болмауы керек.
5 Кіру рұқсаты жоқ.
5 Пайдаланушы құпиясөзді ауыстыруы керек.
5 [jsonParams] дұрыс емес
7 Жүйелік қате.
13 Мерчанттың тексеру төлемдерін орындау артықшылықтары жоқ
14 Features дұрыс көрсетілмеген

Мысалдар

Сұрау мысалы

curl --request POST \
  --url https://3dsec.berekebank.kz/payment/rest/register.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data amount=2000 \
  --data userName=test_user \
  --data password=test_user_password \
  --data returnUrl=finish.html \
  --data failUrl=errors_en.html \
  --data email=test@test.ru \
  --data clientId=259753456 \
  --data language=en

Жауап мысалы

{
  "orderId": "01491d0b-c848-7dd6-a20d-e96900a7d8c0",
  "formUrl": "https://3dsec.berekebank.kz/payment/merchants/rbs/payment_en.html?mdOrder=01491d0b-c848-7dd6-a20d-e96900a7d8c0"
}

Алдын ала авторизациядан өтетін тапсырысты тіркеу

Алдын ала авторизациядан өтетін тапсырысты тіркеу үшін registerPreAuth.do әдісі пайдаланылады.

Сұрау параметрлері

Міндетті Атау Түрі Сипаттама
Сипаттаманы көру

userName String Сатушының API есептік жазбасының логині. Аутентификация үшін тіркелу кезінде пайдаланушы аты мен құпиясөз орнына токен пайдаланылса (token параметрі), құпиясөзді жіберудің қажеті жоқ.
Сипаттаманы көру

password String Сатушының API есептік жазбасының құпиясөзі. Аутентификация үшін тіркелу кезінде пайдаланушы аты мен құпиясөз орнына токен пайдаланылса (token параметрі), құпиясөзді жіберудің қажеті жоқ.
Сипаттаманы көру

token String Төлем шлюзіне сұрауларды жіберген кезде сатушы аутентификациясы үшін пайдаланылатын мән. Осы параметрді көрсетсеңіз, userName және password көрсетілмеуі керек.
Иә

orderNumber Alphanumeric Мерчант жүйесіндегі тапсырыс нөмірі (ID); әр мерчант үшін бірегей болуы керек.
Иә

amount Integer Ең төменгі валюта бірліктерінде көрсетілген төлем сомасы (мысалы, тиынмен).
Жоқ

currency Integer ISO 4217 төлем валютасының коды. Көрсетілмеген жағдайда, әдепкі мән пайдаланылады.
Иә

returnUrl String Төлем сәтті орындалған жағдайда, пайдаланушы бағытталатын мекенжай. Мекенжайды пайдаланылатын протоколымен бірге толық көрсету қажет (мысалы, test.ruорнына https://test.ru ). Кері жағдайда, пайдаланушы мына мекенжайға бағытталады: «https://https://3dsec.berekebank.kz/payment/».
Жоқ

failUrl String Төлем орындалмаған жағдайда, пайдаланушы бағытталатын мекенжай. Мекенжайды пайдаланылатын протоколымен бірге толық көрсету қажет (мысалы, test.ruорнына https://test.ru ). Кері жағдайда, пайдаланушы мына мекенжайға бағытталады: «https://https://3dsec.berekebank.kz/payment/».
Жоқ

dynamicCallbackUrl String Параметр callback-хабарландыруларын динамикалық түрде жіберу функциясын пайдалануға мүмкіндік береді. Осында мерчант үшін белсендірілген барлық «төлемді» callback-хабарландырулары жіберілетін мекенжайды көрсетуге болады. «Төлемді» – мына операциялар туралы callback-хабарландыруларды білдіреді: қаражатты сәтті ұстап тұру (холд), төлемді таймаут үшін өткізбеу, cardpresent төлемін қабылдамау, сәтті іске асырылған есептен шығару, қайтару, бас тарту. Осында «төлемді» болып табылмайтын мерчант үшін белсендірілген callback-хабарландырулары (байламды қосу/ажырату, байламды жасау) callback-хабарландыруларының статикалық мекенжайына жіберіледі. Параметрді пайдалану қажеттілігі төлем шлюзі тарапындағы сатушы конфигурацияларына байланысты болады.
Жоқ

description String Кез келген пішімдегі тапсырыс сипаттамасы.
Осы өрісті процессинг жүйесіне жіберу функциясын қосу үшін техникалық қолдау көрсету қызметіне хабарласыңыз.
Жоқ

language Alphabetic ISO 639-1 бойынша тіл кілті. Көрсетілмесе, әдепкі бойынша дүкен параметрлерінде таңдалған тіл пайдаланылады.
Жоқ

clientId Alphanumeric Мерчант жүйесіндегі клиенттің нөмірі (ID) — 255 таңбаға дейін. Байламдардың функцияларын орындау үшін қолданылады. Мерчантқа байламдарды жасауға рұқсат етілсе, жауап ретінде қайтарылуы мүмкін.
Төлемдер байлам арқылы өңделген кезде осы параметрді міндетті түрде таңдау қажет. Кері жағдайда, төлемді жасау мүмкін болмайды.
Жоқ

merchantLogin String Тапсырысты еншілес мерчанттың атынан тіркеу үшін оның логинін осы параметрде көрсетіңіз.
Жоқ

jsonParams String Мерчанттың қосымша параметрлерін көрсету бөлімі. Кейін сақтауға арналған қосымша ақпарат өрістері.
{name1:value1,…,nameN:valueN}
Осы өрістер кейін банк реестрінде көрсету үшін банк процессингіне жіберілуі мүмкін.
Осы функцияны қосу үшін банкіңізге хабарласыңыз.
Мерчант үшін сатып алушылар туралы хабарландырулар орнатылған болса, осы бөлімде сатушының электрондық пошта мекенжайы бар email параметрі көрсетілуі керек.
Әдепкі бойынша банк процессингіне мына параметрлер жіберіледі:
  • orderNumber - мерчант жүйесіндегі тапсырыс нөмірі;
  • description - тапсырыс сипаттамасы (99 таңбаға дейін пайдаланылып, келесі таңбаларды қолдануға рұқсат берілмейді: %, +, күймешені қайтару \r және жолды түсіру \n).

Егер merchantOrderId көрсетілсе, оның мәні банк процессингіне тапсырыс нөмірі ретінде жіберіледі (orderNumber параметрінің орнына).
Жоқ

sessionTimeoutSecs Integer Тапсырыстың секундпен берілген мерзімі. Параметр көрсетілмесе, мерчант параметрлерде көрсеткен мән немесе әдепкі уақыт (1200 секунд = 20 минут) пайдаланылады. Сұрауда expirationDate параметрі бар болса, sessionTimeoutSecs параметрінің мәні ескерілмейді.
Жоқ

expirationDate String Тапсырыс мерзімінің аяқталу күні және уақыты. Формат: yyyy-MM-ddTHH:mm:ss.
Осы параметр сұрауда берілмеген жағдайда, тапсырыс мерзімінің аяқталу күнін анықтау үшін sessionTimeoutSecs параметрі пайдаланылады.
Жоқ

bindingId String Бұрын жасалған байламның идентификаторы. Оны тек мерчанттың байламдармен жұмыс істеуге рұқсаты бар болған жағдайда ғана пайдалануға болады.
Жоқ

features String Төменде рұқсат етілетін мәндер көрсетілген.
  • AUTO_PAYMENT - төлем карта иесінің түпнұсқалығын тексерусіз жүзеге асырылады (CVC және 3D-Secure кодтары талап етілмейді). Осындай төлемдерді жасау үшін мерчантта тиісті рұқсаттар болуы керек.
  • VERIFY- осы мәнді тапсырысты рәсімдеу сұрауында көрсеткен кезде, карта иесі верификациядан өтеді, (оған 3-D Secure үдерісінен өту қажет болады), дегенмен, қаражат алынбайды, себебі осы жағдайда amount параметрі 0 мәнінде болуы мүмкін. Верификация картаның өз иесінде екеніне көз жеткізуге және осыдан кейін төлемдер жасаған кезде бұл картадан аутентификация деректерін (CVC, 3D-Secure) тексермей, қаражатты есептен шығаруға мүмкіндік береді. Сұрауда төлем сомасы көрсетілсе де, VERIFY мәні берілген кезде бұл сома клиент шотынан алынбайды. Тіркелу сәтті аяқталған соң, тапсырыс бірден REVERSED (бас тартылды) күйіне өтеді.
  • FORCE_TDS - 3-D Secure қорғанысын пайдалану арқылы төлемді мәжбүрлі түрде орындау. Карта 3-D Secure қорғанысына қолдау көрсетпесе, транзакция өтпейді.
  • FORCE_SSL - SSL арқылы (3-D Secure қорғанысы жоқ) төлемді мәжбүрлі түрде орындау.
  • FORCE_FULL_TDS - 3-D Secure арқылы аутентификацияны орындағаннан кейін, PaRes күйі тек Y болуы керек, бұл пайдаланушының сәтті аутентификациясын қамтамасыз етеді. Кері жағдайда, транзакция өтпейді.
Жоқ

autocompletionDate String Дата и время автоматического завершения двухстадийного платежа в следующем формате: 2017-12-29T13:02:51. Используемый часовой пояс: UTC+3. Чтобы включить отправку этого поля в процессинговую систему, обратитесь в службу технической поддержки.
Жоқ

email String Клиенттің электрондық пошта мекенжайы.
Жоқ

phone Integer Сатып алушының телефон нөмірі. Ел кодын әрқашан көрсету керек, осында + белгісін көрсетуге не көрсетпеуге болады. Осылайша, келесі нұсқалар қолжетімді болады:
  • +79998887766;
  • 79998887766. Цифрлардың рұқсат етілген саны: 7-15 аралығында.
Сипаттаманы көру

billingPayerData Object Клиенттің AVS/AVV қызметтері аясында мекенжай тексерісінен өту үшін қажетті тіркеу деректері (мекенжай, пошта индексі) бар блок. Төлем шлюзінің тарапынан сатушы үшін функция қосулы болған жағдайда міндетті болып табылады.

Төменде billingPayerData блогының параметрлері келтірілген (клиентті тіркеу мекенжайы туралы деректер).

Міндетті Атау Түрі Сипаттама
Жоқ

billingCity String Эмитент банктің нақты картасы бойынша тіркелген қала.
Жоқ

billingCountry String Эмитент банктің нақты картасы бойынша тіркелген ел (ISO 3166-1, сандық).
Жоқ

billingAddressLine1 String Эмитент банктің нақты картасы бойынша тіркелген мекенжай. 1-жол. AVS-тексерісі үшін берілуі міндетті.
Жоқ

billingAddressLine2 String Эмитент банктің нақты картасы бойынша тіркелген мекенжай. 2-жол.
Жоқ

billingAddressLine3 String Эмитент банктің нақты картасы бойынша тіркелген мекенжай. 3-жол.
Жоқ

billingPostalCode String Эмитент банктің нақты картасы бойынша тіркелген пошта индексі. AVS-тексерісі үшін берілуі міндетті.
Жоқ

billingState String Эмитент банктің нақты картасы бойынша тіркелген штат.

Жауап параметрлері

Міндетті Атау Түрі Сипаттама
Жоқ

orderId String Төлем шлюзіндегі тапсырыс нөмірі. Төлем шлюзі ауқымында бірегей болып табылады.
Жоқ

formUrl String Сатып алушы бағытталатын төлем пішінінің URL-мекенжайы. Тапсырысты тіркеу errorCode кодында көрсетілген қатеге байланысты сәтсіз аяқталса, URL қайтарылмайды.
Жоқ

errorCode Integer Қате коды. Қате орын алмаған кезде, болмауы мүмкін.
Жоқ

errorMessage String Қате сипаттамасы. Сипаттама тілі сұраудың language параметрінде таңдалады.

Қателер коды

Қате коды Хабар
0 Сұрауды өңдеу жүйелік қателерсіз аяқталды.
1 Көрсетілген нөмірі бар тапсырыс өңделіп қойды.
1 Тапсырыс нөмірі дұрыс емес
3 Белгісіз валюта.
4 Тапсырыс нөмірі бос болмауы керек
4 Сатушы аты бос болмауы керек
4 Сома көрсетілмеген
4 Қайтару URL-мекенжайы бос болмауы керек
4 Құпиясөз бос болмауы керек.
5 Дұрыс емес сома.
5 'Тіл’ параметрі дұрыс емес.
5 Сатушы логіне дұрыс емес
5 Кіру рұқсаты жоқ.
5 Пайдаланушы құпиясөзді ауыстыруы керек.
5 [jsonParams] дұрыс емес
7 Жүйелік қате.
13 Мерчанттың тексеру төлемдерін орындау артықшылықтары жоқ
14 Features дұрыс көрсетілмеген

Мысалдар

Сұрау мысалы

curl --request POST \
  --url https://3dsec.berekebank.kz/payment/rest/registerPreAuth.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data amount=2000 \
  --data userName=test_user \
  --data password=test_user_password \
  --data returnUrl=finish.html \
  --data orderNumber=1255555555555 \
  --data clientId=259753456 \
  --data language=en

Жауап мысалы

{
  "orderId": "01492437-d2fb-77fa-8db7-9e2900a7d8c0",
  "formUrl": "https://3dsec.berekebank.kz/payment/merchants/rbs/payment_en.html?mdOrder=01492437-d2fb-77fa-8db7-9e2900a7d8c0"
}

Тапсырысты аяқтау

Алдын ала авторизацияланған тапсырысты аяқтау үшін deposit.do сұрауы пайдаланылады.

Сұрау параметрлері

Міндетті Атау Түрі Сипаттама
Иә

userName String Сатушының API есептік жазбасының логині.
Иә

password String Сатушының API есептік жазбасының құпиясөзі.
Иә

orderId String Төлем шлюзіндегі тапсырыс нөмірі. Төлем шлюзі ауқымында бірегей болып табылады.
Иә

amount Integer Ең төменгі валюта бірліктерінде көрсетілген төлем сомасы (мысалы, тиынмен).

Жауап параметрлері

Міндетті Атау Түрі Сипаттама
Жоқ

errorCode Integer Қате коды. Қате орын алмаған кезде, болмауы мүмкін.
Жоқ

errorMessage String Қате сипаттамасы. Сипаттама тілі сұраудың language параметрінде таңдалады.

Қателер коды

Қате коды Хабар
5 Кіру рұқсаты жоқ.
5 Пайдаланушы құпиясөзді ауыстыруы керек.
5 Дұрыс емес сома.
5 Депозит сомасы нөлге тең немесе кемінде бір рубль болуы керек.
6 Тіркелмеген orderId.
7 Төлем дұрыс күйінде болуы керек.
7 Жүйелік қате.

Мысалдар

Сұрау мысалы

curl --request POST \
  --url https://3dsec.berekebank.kz/payment/rest/deposit.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data amount=2000 \
  --data orderId=01492437-d2fb-77fa-8db7-9e2900a7d8c0 \
  --data language=en

Жауап мысалы

{
  "errorCode": 0,
  "errorMessage":"Success"
}

Қаражатты қайтару

Қаражатты қайтару үшін refund.do сұрауы пайдаланылады.

Тұрақты төлемдерді бастайтын тапсырыстар бойынша қаражатты қайтару мүмкін емес, себебі осы жағдайда қаражат есептен шығарылмайды.

Бұл сұрауда көрсетілген тапсырыс бойынша қаражат төлем жасаушыға қайтарылады. Тапсырыс бойынша қаражат есептен шығарылмаған жағдайда, сұрау қатемен қайтарылады. Жүйе қаражатты бірнеше рет қайтаруға рұқсат береді, дегенмен, жалпы алғанда, сома бастапқы есептен шығарылған сомадан аспауы керек.

Сұрау параметрлері

Міндетті Атау Түрі Сипаттама
Иә

orderId String Төлем шлюзіндегі тапсырыс нөмірі. Төлем шлюзі ауқымында бірегей болып табылады.
Иә

amount Integer Ең төменгі валюта бірліктерінде көрсетілген төлем сомасы (мысалы, тиынмен).
Жоқ

language Alphabetic ISO 639-1 бойынша тіл кілті. Көрсетілмесе, әдепкі бойынша дүкен параметрлерінде таңдалған тіл пайдаланылады.

Жауап параметрлері

Міндетті Атау Түрі Сипаттама
Жоқ

errorCode Integer Қате коды. Қате орын алмаған кезде, болмауы мүмкін.
Жоқ

errorMessage String Қате сипаттамасы. Сипаттама тілі сұраудың language параметрінде таңдалады.

Қателер коды

Қате коды Хабар
0 Сұрауды өңдеу жүйелік қателерсіз аяқталды.
5 Кіру рұқсаты жоқ.
5 Пайдаланушы құпиясөзді ауыстыруы керек.
5 [orderId] көрсетілмеген
5 Дұрыс емес сома.
6 Тіркелмеген orderId.
7 Төлем дұрыс күйінде болуы керек.
7 Қайтару сомасы төлем сомасынан асып кетті.
7 Жүйелік қате.

Мысалдар

Сұрау мысалы

curl --request POST \
  --url https://3dsec.berekebank.kz/payment/rest/refund.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data orderId=01491d0b-c848-7dd6-a20d-e96900a7d8c0 \
  --data amount=2000 \
  --data language=en

Жауап мысалы

{
  "errorCode": 0,
  "errorMessage":"Success"
}

Тапсырыстың күйі

Сұрау параметрлері

Міндетті Атау Түрі Сипаттама
Жоқ

userName String Сатушының API есептік жазбасының логині. Аутентификация үшін тіркелу кезінде пайдаланушы аты мен құпиясөз орнына токен пайдаланылса (token параметрі), құпиясөзді жіберудің қажеті жоқ.
Жоқ

password String Сатушының API есептік жазбасының құпиясөзі. Аутентификация үшін тіркелу кезінде пайдаланушы аты мен құпиясөз орнына токен пайдаланылса (token параметрі), құпиясөзді жіберудің қажеті жоқ.
Жоқ

token String Төлем шлюзіне сұрауларды жіберген кезде сатушы аутентификациясы үшін пайдаланылатын мән. Осы параметрді көрсетсеңіз, userName және password көрсетілмеуі керек.
Иә

orderId String Төлем шлюзіндегі тапсырыс нөмірі. Төлем шлюзі ауқымында бірегей болып табылады.
Иә

orderNumber Alphanumeric Мерчант жүйесіндегі тапсырыс нөмірі (ID); әр мерчант үшін бірегей болуы керек.
Жоқ

language Alphabetic ISO 639-1 бойынша тіл кілті. Көрсетілмесе, әдепкі бойынша дүкен параметрлерінде таңдалған тіл пайдаланылады.

Жауап параметрлері

Жауап параметрлерінің бірнеше жиынтығы бар. Жауаппен келген параметрдің түрі төлем шлюзіндегі мерчант параметрлерінде көрсетілген getOrderStatusExtended нұсқасына байланысты болады.

Нұсқа Міндетті Атау Түрі Сипаттама
Барлық нұсқалар. Сипаттаманы көру

orderNumber Alphanumeric Мерчант жүйесіндегі тапсырыс нөмірі (ID); төлем шлюзінде тіркелген әр мерчант үшін бірегей болуы керек — 30 таңбаға дейін. Тапсырыс нөмірі төлем шлюзінің тарапында жасалса, осы параметрді көрсету қажет емес.
Барлық нұсқалар. Жоқ

orderStatus Integer Осы параметрдің мәні төлем шлюзіндегі тапсырыстың күйін көрсетеді. Тапсырыс табылмаған кезде болмайды. Төменде қолжетімді параметрлер тізімі берілген:
  • 0 - тапсырыс тіркелген, бірақ төленбеген;
  • 1 - алдын ала авторизацияланған сома ұсталған (екі кезеңді төлемдер үшін)
  • 2 - тапсырыс сомасының толық авторизациясы орындалды;
  • 3 - авторизациядан бас тартылды;
  • 4 - транзакция бойынша қайтару операциясы орындалды;
  • 5 - банк-эмитентінің ACS сервері арқылы авторизация іске қосылды;
  • 6 - авторизация орындалмады.
Барлық нұсқалар. Иә

actionCode Integer Банк процессингінен алынған жауап коды.
Барлық нұсқалар. Иә

actionCodeDescription String Банк процессингімен қайтарылатын actionCode сипаттамасы.
Барлық нұсқалар. Жоқ

errorCode Integer Қате коды. Қате орын алмаған кезде, болмауы мүмкін.
Барлық нұсқалар. Жоқ

errorMessage String Қате сипаттамасы. Сипаттама тілі сұраудың language параметрінде таңдалады.
Барлық нұсқалар. Иә

amount Integer Ең төменгі валюта бірліктерінде көрсетілген төлем сомасы (мысалы, тиынмен).
Барлық нұсқалар. Жоқ

currency Integer ISO 4217 төлем валютасының коды. Көрсетілмеген жағдайда, әдепкі мән пайдаланылады.
Барлық нұсқалар. Иә

date String Тапсырысты тіркеу күні.
Барлық нұсқалар. Жоқ

orderDescription String Тіркеу кезінде төлем шлюзіне жіберілетін тапсырыстың сипаттамасы.
Барлық нұсқалар. Иә

ip String Төлеушінің IP-мекенжайы. IPv6 барлық сұрауларда қолданылады (39 таңбаға дейін).
09+ Иә

paymentWay String Төлем жасау әдістері (карта деректерін енгізу арқылы төлеу, байлам арқылы төлеу және т.б.).
19+ Жоқ

avsCode Alphabetic AVS верификациясының жауап коды (карта иесінің мекенжайын және пошта индексін тексеру). Ықтимал мәндері:
  • A – пошта индексі мен мекенжай сәйкес келеді.
  • B – мекенжай сәйкес келеді, ал пошта индексі сәйкес келмейді.
  • C – пошта индексі сәйкес келеді, ал мекенжай сәйкес келмейді.
  • D – пошта индексі мен мекенжай сәйкес келмейді.
  • E – деректерді тексеру сұратылды, бірақ нәтиже сәтсіз болды.
  • F – AVS/AVV тексеру сұратымының пішімі дұрыс емес.

attributes бөлімінде төлем шлюзіндегі тапсырыс нөмірі туралы ақпарат бар. name параметрі әрқашан mdOrder болады, ал value – төлем жүйесіндегі тапсырыс нөмірі болады.

Нұсқа Атау Түрі Міндетті Сипаттама
Барлық нұсқалар. Жоқ

name Numeric Қосымша параметрдің атауы.
Барлық нұсқалар. Жоқ

value Numeric Қосымша параметрдің мәні – 1024 таңбаға дейін.

Тапсырыста мерчанттың қосымша параметрлері бар болса, жауапта merchantOrderParams бөлімі таңдалады. Әр қосымша параметр merchantOrderParams жеке элементінде таңдалады.

Нұсқа Атау Түрі Міндетті Сипаттама
Барлық нұсқалар. Жоқ

name Numeric Қосымша параметрдің атауы.
Барлық нұсқалар. Жоқ

value Numeric Қосымша параметрдің мәні – 1024 таңбаға дейін.

cardAuthInfo элементінде secureAuthInfo элемент тізімі мен келесі параметрлерден тұратын құрылым болады.

Нұсқа Атау Түрі Міндетті Сипаттама
Барлық нұсқалар. Жоқ

maskedPan String Төлемді жасау үшін пайдаланылатын жасырылған карта нөмірі. Тапсырыс бойынша төлем жасалған соң ғана көрсетіледі.
Барлық нұсқалар. Жоқ

expiration Integer Келесі пішімдегі картаның жарамдылық мерзімі: YYYYMM. Тапсырыс бойынша төлем жасалған соң ғана көрсетіледі.
Барлық нұсқалар. Жоқ

cardholderName Alphabetic Карта иесінің латын әліпбиімен көрсетілген аты. Осы параметр тек тапсырыс төленгеннен кейін беріледі.
Барлық нұсқалар. Жоқ

approvalCode String Халықаралық төлем жүйесінің (ХТЖ) авторизация коды. Бұл өрістің ұзындығы бекітілген (алты таңба) және сандар мен латын әріптерінен тұруы мүмкін.
06 және одан жоғары. Жоқ

refund Boolean Банк сатып алушыға қаражатты мәжбүрлі түрде қайтарды ма. Ықтимал мәндері:
  • true - қаражат қайтарылды;
  • false - қаражат қайтарылмады.
08 және одан жоғары. Иә

paymentSystem String Төлем жүйесінің атауы. Келесі мәндер көрсетілуі мүмкін:
  • VISA;
  • MASTERCARD;
  • AMEX;
  • JCB;
  • CUP;
  • MIR.
08 және одан жоғары. Иә

product String Корпоративті карталар туралы қосымша мәліметтер. Осы мәліметтерді техникалық қолдау көрсету қызметі толтырады. Осындай мәліметтер болмаса, бос мән қайтарылады.

secureAuthInfo элементі cavv және xid параметрлерінің тізімі болып табылатын eci және threeDSInfo элементтерінен тұрады.

Нұсқа Атау Түрі Міндетті Сипаттама
Барлық нұсқалар. Жоқ

eci Integer Электрондық коммерциялық көрсеткіш. Тапсырыс бойынша төлем жасалғаннан кейін және тиісті рұқсаттар болған жағдайда ғана көрсетіледі. Төменде ECI-кодтарының түсіндірмесі берілген.
  • ECI=1 немесе ECI=6 – мерчант 3-D Secure протоколына қолдау көрсетеді, төлем картасы 3-D Secure протоколына қолдау көрсетпейді, төлем CVV2/CVC негізінде өңделеді.
  • ECI=2 немесе ECI=5 – мерчант және төлем картасы 3-D Secure протоколына қолдау көрсетпейді;
  • ECI=7 - мерчант 3-D Secure протоколына қолдау көрсетпейді, төлем CVV2/CVC негізінде өңделеді.
Барлық нұсқалар. Жоқ

cavv String Карта иесінің аутентификациясын тексеру мәні. Тапсырыс бойынша төлем жасалғаннан кейін және тиісті рұқсаттар болған жағдайда ғана көрсетіледі.
Барлық нұсқалар. Жоқ

xid String Транзакцияның электрондық коммерциялық идентификаторы. Тапсырыс бойынша төлем жасалғаннан кейін және тиісті рұқсаттар болған жағдайда ғана көрсетіледі.

bindingInfo элементі келесі параметрлерден тұрады.

Нұсқа Атау Түрі Міндетті Сипаттама
Барлық нұсқалар. Жоқ

clientId Alphanumeric Мерчант жүйесіндегі клиенттің нөмірі (ID) — 255 таңбаға дейін. Байламдардың функцияларын орындау үшін қолданылады. Мерчантқа байламдарды жасауға рұқсат етілсе, жауап ретінде қайтарылуы мүмкін.
Төлемдер байлам арқылы өңделген кезде осы параметрді міндетті түрде таңдау қажет. Кері жағдайда, төлемді жасау мүмкін болмайды.
Барлық нұсқалар. Жоқ

bindingId String Бұрын жасалған байламның идентификаторы. Оны тек мерчанттың байламдармен жұмыс істеуге рұқсаты бар болған жағдайда ғана пайдалануға болады.
02 және одан жоғары. Жоқ

authDateTime String 1 қаңтар, 1970 жылдың (GMT) 00:00 уақытынан өтіп кеткен, миллисекунд саны ретінде көрсетілген авторизацияның күні мен уақыты.
02 және одан жоғары. Жоқ

authRefNum String Төлемді тіркеу кезінде берілген төлем авторизациясының тіркеу нөмірі.
02 және одан жоғары. Жоқ

terminalId String Терминал идентификаторы.

paymentAmountInfo элементі келесі параметрлерден тұрады.

Нұсқа Атау Түрі Міндетті Сипаттама
03 және одан жоғары. Жоқ

approvedAmount Integer Сатып алушының шотында бұғатталып қалған ең төменгі валюта бірліктеріндегі сома (мысалы, цент түрінде). Тек екі сатылы төлемдерде ғана пайдаланылады.
03 және одан жоғары. Жоқ

depositedAmount Integer Минималды валюта бірлігімен (мысалы, тиынмен) берілген есептен шығару сомасы.
03 және одан жоғары. Жоқ

refundedAmount Integer Минималды бірлікпен берілген қайтару сомасы.
03 және одан жоғары. Жоқ

paymentState String Тапсырыс күйі, параметр мына мәндерде болуы мүмкін:
  • CREATED - тапсырыс жасалған (бірақ төленбеген);
  • APPROVED - тапсырыс расталған (сатып алушы шотындағы қаражат бұғатталған);
  • DEPOSITED- тапсырыс аяқталды (қаражат сатып алушы шотынан түсті);
  • DECLINED - тапсырыс қабылданбады;
  • REVERSED - бас тарту операциясы;
  • REFUNDED - қаражатты қайтару операциясы.
11 және одан жоғары. Жоқ

feeAmount Integer Комиссия сомасы.

bankInfo элементі келесі параметрлерден тұрады.

Нұсқа Атау Түрі Міндетті Сипаттама
03 және одан жоғары. Жоқ

bankName String Эмитент банктің атауы.
03 және одан жоғары. Жоқ

bankCountryCode String Эмитент банктің ел коды.
03 және одан жоғары. Жоқ

bankCountryName String Эмитент банктің елі.

Қателер коды

Қате коды Хабар
0 Сұрауды өңдеу жүйелік қателерсіз аяқталды.
5 Кіру рұқсаты жоқ.
5 Пайдаланушы құпиясөзді ауыстыруы керек.
5 [orderId] көрсетілмеген
6 Тіркелмеген orderId.
7 Жүйелік қате.

Мысалдар

Сұрау мысалы

curl --request POST \
  --url https://3dsec.berekebank.kz/payment/rest/getOrderStatusExtended.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data orderId=01491d0b-c848-7dd6-a20d-e96900a7d8c0 \
  --data language=en

Жауап мысалы

{
  "errorCode": "0",
  "errorMessage": "Success",
  "orderNumber": "7005",
  "orderStatus": 2,
  "actionCode": 0,
  "actionCodeDescription": "",
  "amount": 2000,
  "currency": "978",
  "date": 1617972915659,
  "orderDescription": "",
  "merchantOrderParams": [],
  "transactionAttributes": [],
  "attributes": [
    {
      "name": "mdOrder",
      "value": "01491d0b-c848-7dd6-a20d-e96900a7d8c0"
    }
  ],
  "cardAuthInfo": {
    "maskedPan": "555555**5599",
    "expiration": "202412",
    "cardholderName": "TEST CARDHOLDER",
    "approvalCode": "123456",
    "pan": "555555**5599"
  },
  "bindingInfo": {
    "clientId": "259753456",
    "bindingId": "01491394-63a6-7d45-a88f-7bce00a7d8c0"
  },
  "authDateTime": 1617973059029,
  "terminalId": "123456",
  "authRefNum": "714105591198",
  "paymentAmountInfo": {
    "paymentState": "DEPOSITED",
    "approvedAmount": 2000,
    "depositedAmount": 2000,
    "refundedAmount": 0
  },
  "bankInfo": {
    "bankCountryCode": "UNKNOWN",
    "bankCountryName": "&ltUnknown&gt"
  }
}

Байламдар арқылы төлеу

Сұрау параметрлері

Міндетті Атау Түрі Сипаттама
Иә

userName String Сатушының API есептік жазбасының логині.
Иә

password String Сатушының API есептік жазбасының құпиясөзі.
Иә

mdOrder String Төлем шлюзіндегі тапсырыс нөмірі. Төлем шлюзі ауқымында бірегей болып табылады.
Иә

bindingId String Бұрын жасалған байламның идентификаторы. Оны тек мерчанттың байламдармен жұмыс істеуге рұқсаты бар болған жағдайда ғана пайдалануға болады.
Жоқ

language Alphabetic ISO 639-1 бойынша тіл кілті. Көрсетілмесе, әдепкі бойынша дүкен параметрлерінде таңдалған тіл пайдаланылады.
Иә

ip String Төлеушінің IP-мекенжайы. IPv6 барлық сұрауларда қолданылады (39 таңбаға дейін).
Жоқ

cvc Integer Мерчант үшін Төлемдерді CVC кодынсыз жасай алады рұқсаты таңдалмаған жағдайда, бұл параметр міндетті болып табылады.
Жоқ

email String Клиенттің электрондық пошта мекенжайы.
Жоқ

threeDSSDK String Ықтимал мәндері: true немесе false. Төлемнің 3DS SDK арқылы түсетінін көрсететін жалауша.

Жауап параметрлері

Міндетті Атау Түрі Сипаттама
Жоқ

redirect String Төлем сәтті орындалып, төлеу кезінде картадағы 3-D Secure протоколының қосылуы тексерілмесе, осы параметр қайтарылады. Төлем жасалғаннан кейін клиент қайта бағытталатын URL-мекенжайы.
Жоқ

info String Жауап сәтті болған жағдайда. Төлем жасау әрекетінің нәтижесі. Төменде ықтимал мәндері көрсетілген.
  • Төлеміңіз өңделді, қайта бағыттау орындалуда...
  • Операция өтпеді. Енгізілген деректерді, картадағы қаражаттың жеткілікті екенін тексеріп, операцияны қайталаңыз. Қайта бағыттау орындалуда...
  • Төлем жасау мүмкін емес. Қайта бағыттау орындалуда...
  • Операция өтпеді. Дүкенге хабарласыңыз. Қайта бағыттау орындалуда...
  • Операция өтпеді. Картаны шығарған банкке хабарласыңыз. Қайта бағыттау орындалуда...
  • Рұқсат етілмеген операция Карта иесінің аутентификациясы сәтсіз аяқталды. Қайта бағыттау орындалуда...
  • Банкпен байланыс жоқ. Кейінірек қайталаңыз. Қайта бағыттау орындалуда...
  • Деректерді енгізудің күту мерзімі аяқталды. Қайта бағыттау орындалуда...
  • Банктен жауап алынбады. Кейінірек қайталаңыз. Қайта бағыттау орындалуда...
Иә

errorCode Integer Қате коды. Қате орын алмаған кезде, болмауы мүмкін.
Жоқ

errorMessage String Қате сипаттамасы. Сипаттама тілі сұраудың language параметрінде таңдалады.
Жоқ

error String Сұрау жіберілген тілдегі қате туралы хабар (жауапта қате болған жағдайда).
Жоқ

acsUrl String 3D-Secure арқылы төлеген жағдайда сәтті жауап берілген кезде. ACS серверіне қайта бағыттайтын URL-мекенжайы.
Жоқ

paReq String 3D-Secure арқылы төлеген жағдайда сәтті жауап берілген кезде. Payment Authentication Request. Төлеуші аутентификациясының сұрауы.
Жоқ

termUrl String 3D-Secure арқылы төлеген жағдайда сәтті жауап берілген кезде. ACS серверіне қайта бағыттайтын URL-мекенжайы.

Қателер коды

Қате коды Хабар
0 Сұрауды өңдеу жүйелік қателерсіз аяқталды.
1 [cvc] көрсетілмеді.
2 Байлам табылмады.
2 Тапсырыс табылмады.
5 Кіру рұқсаты жоқ.
5 Пайдаланушы құпиясөзді ауыстыруы керек.
7 Жүйелік қате.

Мысалдар

Сұрау мысалы

curl --request POST \
  --url https://3dsec.berekebank.kz/payment/rest/paymentOrderBinding.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data mdOrder=01491d0b-c848-7dd6-a20d-e96900a7d8c0 \
  --data bindingId=01491394-63a6-7d45-a88f-7bce00a7d8c0 \
  --data clientId=259753456 \
  --data ip=1d0d:db8:6:1::77 \
  --data cvc=123 \
  --data language=en

SSL-төлемін сәтті іске асыру жауабының мысалы (3-D Secure протоколы жоқ)

{
  "redirect": "https://3dsec.berekebank.kz/payment/merchants/temp/finish.html?orderId=01491d0b-c848-7dd6-a20d-e96900a7d8c0&lang=en",
  "info": "Your order is proceeded, redirecting...",
  "errorCode": 0
}

3D-Secure арқылы төлемді сәтті іске асыру жауабының мысалы

{
  "info": "Your order is proceeded, redirecting...",
  "errorCode": 0,
  "acsUrl": "https://web.rbsuat.com/acs/auth/start.do",
  "paReq": "eJxVUu9vgjAQ/VcM37FQKqI5a9zUjEWI2TDZt6VCBxj5IRSj/vVrEab70OTe3fW967vC/JIdB2de1WmRzzRzaGgDnodFlObxTNsFa93R5hSCpOJ8+cnDpuIUPF7XLOaDNJpp2B79OJYz0e2ITXTCTaI7Y2bpeDwyrYkVhXuHaRS2iw9+otAJUakzxIB6KBmrMGG5oMDC04vrU4LHtmEA6iBkvHKXdEQsbBFAdwQ5yzitWR7ti8t31lEAatMQFk0uqiu1iQWoB9BUR5oIUU4RErwWw7DIAKkkoMcM20ZFtSS5pBH1b/HVv3mGF6ywF8SGd9jd/IMnTzwDpDogYoJTbGDTICYZmM7UsqeGlG3zwDKlLuvtg+4ASqWxeK48Z0AaXck99OP3CPilLHKu7gD6iwE9Jn59Ux6GQvpzLlfBpEwcX3ibrVuwdbrelOv3OvpaucrZtkkxptIZTMw7pQKAFA3qloa6fcvo3z/4BaHYvAI=",
  "termUrl": "https://3dsec.berekebank.kz/payment/rest/finish3ds.do?lang=en"
}

Қатесі бар жауаптың мысалы

{
  "error": "Access denied",
  "errorCode": 5,
  "errorMessage": "Access denied"
}

Байламдарды алу

Сұрау параметрлері

Міндетті Атау Түрі Сипаттама
Иә

clientId Alphanumeric Мерчант жүйесіндегі клиенттің нөмірі (ID) — 255 таңбаға дейін. Байламдардың функцияларын орындау үшін қолданылады. Мерчантқа байламдарды жасауға рұқсат етілсе, жауап ретінде қайтарылуы мүмкін.
Төлемдер байлам арқылы өңделген кезде осы параметрді міндетті түрде таңдау қажет. Кері жағдайда, төлемді жасау мүмкін болмайды.

Жауап параметрлері

Міндетті Атау Түрі Сипаттама
Иә

errorCode Integer Қате коды. Қате орын алмаған кезде, болмауы мүмкін.
Жоқ

errorMessage String Қате сипаттамасы. Сипаттама тілі сұраудың language параметрінде таңдалады.
Жоқ

error String Сұрау жіберілген тілдегі қате туралы хабар (жауапта қате болған жағдайда).
Жоқ

maskedPan String Төлемді жасау үшін пайдаланылатын жасырылған карта нөмірі. Тапсырыс бойынша төлем жасалған соң ғана көрсетіледі.
Жоқ

paymentWay String Төлем жасау әдістері (карта деректерін енгізу арқылы төлеу, байлам арқылы төлеу және т.б.).
Иә

bindingId String Бұрын жасалған байламның идентификаторы. Оны тек мерчанттың байламдармен жұмыс істеуге рұқсаты бар болған жағдайда ғана пайдалануға болады.
Иә

expiryDate Integer Келесі пішімдегі картаның жарамдылық мерзімі: YYYYMM. Тапсырыс бойынша төлем жасалған соң ғана көрсетіледі.

Қателер коды

Қате коды Хабар
0 Сұрауды өңдеу жүйелік қателерсіз аяқталды.
1 [cvc] көрсетілмеді.
2 Байлам табылмады.
2 Тапсырыс табылмады.
5 Кіру рұқсаты жоқ.
5 Пайдаланушы құпиясөзді ауыстыруы керек.
7 Жүйелік қате.

Мысалдар

Сұрау мысалы

curl --request POST \
  --url https://3dsec.berekebank.kz/payment/rest/getBindings.do \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data userName=ik_bindings-api \
  --data password=Ik_pass1 \
  --data clientId=dos-clientos \
  --data bindingType=C

Сәтті аяқталған сұрау мысалдары

{
"errorCode":"0",
"errorMessage":"Success",
"bindings": [
    {
        "bindingId":"69d6a793-afb5-79be-8ce7-63ff00a8656a",
        "maskedPan":"444455**3333",
        "expiryDate":"202412",
        "paymentWay":"CARD",
        "displayLabel":"XXXXXXXXXXXX3333"
        }
    ]
 }

Тапсырыс үшін төлеу сұрауы, карта деректері мерчант (ішкі 3DS Server) тарапынан жиналады

Төлем жасау үшін paymentOrder.do сұрауы пайдаланылады.

Сұрау параметрлері

Міндетті Атау Түрі Сипаттама
Иә

userName String Сатушының API есептік жазбасының логині.
Иә

password String Сатушының API есептік жазбасының құпиясөзі. Аутентификация үшін тіркелу кезінде пайдаланушы аты мен құпиясөз орнына токен пайдаланылса (token параметрі), құпиясөзді жіберудің қажеті жоқ.
Иә

MDORDER String Төлем шлюзіндегі тапсырыс нөмірі.
Иә

$PAN Numeric Төлем картасының нөмірі.
Иә

$CVC Numeric Картаның артқы жағындағы CVC/CVV2 коды.
Иә

YYYY Numeric Төлем картасы жарамдылығының аяқталу жылы.
Иә

MM Numeric Төлем картасы жарамдылығының аяқталу айы.
Иә

TEXT Alphabetic Карта иеленушісінің аты.
Иә

language Alphabetic ISO 639-1 бойынша тіл кілті. Көрсетілмесе, әдепкі бойынша дүкен параметрлерінде таңдалған тіл пайдаланылады.
Жоқ

ip String Төлеушінің IP-мекенжайы. IPv6 барлық сұрауларда қолданылады (39 таңбаға дейін).
Жоқ

email String Клиенттің электрондық пошта мекенжайы.
Жоқ

bindingNotNeeded Boolean Рұқсат етілетін мәндер:
  • true – төлемді аяқтағаннан кейін байлам жасау өшірілген (байлам – клиенттің тапсырысты тіркеуге сұрау салған кезде берілген идентификаторы, бұл идентификатор paymentOrder сұратымынан кейін тапсырыстың мәліметтерінен жойылады);
  • false – сәтті төленген жағдайда байламды жасауға болады (қажетті шарттарды сақтаған кезде). Бұл әдепкі бойынша мән.
Жоқ

jsonParams String Мерчанттың қосымша параметрлерін көрсету бөлімі. Кейін сақтауға арналған қосымша ақпарат өрістері.
{name1:value1,…,nameN:valueN}
Осы өрістер кейін банк реестрінде көрсету үшін банк процессингіне жіберілуі мүмкін.
Осы функцияны қосу үшін банкіңізге хабарласыңыз.
Мерчант үшін сатып алушылар туралы хабарландырулар орнатылған болса, осы бөлімде сатушының электрондық пошта мекенжайы бар email параметрі көрсетілуі керек.
Әдепкі бойынша банк процессингіне мына параметрлер жіберіледі:
  • orderNumber - мерчант жүйесіндегі тапсырыс нөмірі;
  • description - тапсырыс сипаттамасы (99 таңбаға дейін пайдаланылып, келесі таңбаларды қолдануға рұқсат берілмейді: %, +, күймешені қайтару \r және жолды түсіру \n).

Егер merchantOrderId көрсетілсе, оның мәні банк процессингіне тапсырыс нөмірі ретінде жіберіледі (orderNumber параметрінің орнына).
Жоқ

threeDSSDK String Ықтимал мәндері: true немесе false. Төлемнің 3DS SDK арқылы түсетінін көрсететін жалауша.
Сипаттаманы көру

billingPayerData Object Клиенттің AVS/AVV қызметтері аясында мекенжай тексерісінен өту үшін қажетті тіркеу деректері (мекенжай, пошта индексі) бар блок. Төлем шлюзінің тарапынан сатушы үшін функция қосулы болған жағдайда міндетті болып табылады.

Төменде billingPayerData блогының параметрлері келтірілген (клиентті тіркеу мекенжайы туралы деректер).

Міндетті Атау Түрі Сипаттама
Жоқ

billingCity String Эмитент банктің нақты картасы бойынша тіркелген қала.
Жоқ

billingCountry String Эмитент банктің нақты картасы бойынша тіркелген ел (ISO 3166-1, сандық).
Жоқ

billingAddressLine1 String Эмитент банктің нақты картасы бойынша тіркелген мекенжай. 1-жол. AVS-тексерісі үшін берілуі міндетті.
Жоқ

billingAddressLine2 String Эмитент банктің нақты картасы бойынша тіркелген мекенжай. 2-жол.
Жоқ

billingAddressLine3 String Эмитент банктің нақты картасы бойынша тіркелген мекенжай. 3-жол.
Жоқ

billingPostalCode String Эмитент банктің нақты картасы бойынша тіркелген пошта индексі. AVS-тексерісі үшін берілуі міндетті.
Жоқ

billingState String Эмитент банктің нақты картасы бойынша тіркелген штат.

Жауап параметрлері

Міндетті Атау Түрі Сипаттама
Иә

errorCode Integer Қате коды. Қате орын алмаған кезде, болмауы мүмкін.
Жоқ

errorMessage String Қате сипаттамасы. Сипаттама тілі сұраудың language параметрінде таңдалады.
Жоқ

info String Жауап сәтті болған жағдайда. Төлем жасау әрекетінің нәтижесі. Төменде ықтимал мәндері көрсетілген.
  • Төлеміңіз өңделді, қайта бағыттау орындалуда...
  • Операция өтпеді. Енгізілген деректерді, картадағы қаражаттың жеткілікті екенін тексеріп, операцияны қайталаңыз. Қайта бағыттау орындалуда...
  • Төлем жасау мүмкін емес. Қайта бағыттау орындалуда...
  • Операция өтпеді. Дүкенге хабарласыңыз. Қайта бағыттау орындалуда...
  • Операция өтпеді. Картаны шығарған банкке хабарласыңыз. Қайта бағыттау орындалуда...
  • Рұқсат етілмеген операция Карта иесінің аутентификациясы сәтсіз аяқталды. Қайта бағыттау орындалуда...
  • Банкпен байланыс жоқ. Кейінірек қайталаңыз. Қайта бағыттау орындалуда...
  • Деректерді енгізудің күту мерзімі аяқталды. Қайта бағыттау орындалуда...
  • Банктен жауап алынбады. Кейінірек қайталаңыз. Қайта бағыттау орындалуда...
Жоқ

redirect String Төлем сәтті орындалып, төлеу кезінде картадағы 3-D Secure протоколының қосылуы тексерілмесе, осы параметр қайтарылады. Төлем жасалғаннан кейін клиент қайта бағытталатын URL-мекенжайы.
Жоқ

termUrl String 3D-Secure арқылы төлеген жағдайда сәтті жауап берілген кезде. ACS серверіне қайта бағыттайтын URL-мекенжайы.
Жоқ

acsUrl String 3D-Secure арқылы төлеген жағдайда сәтті жауап берілген кезде. ACS серверіне қайта бағыттайтын URL-мекенжайы.
Жоқ

paReq String 3D-Secure арқылы төлеген жағдайда сәтті жауап берілген кезде. Payment Authentication Request. Төлеуші аутентификациясының сұрауы.

Қателер кодтары (errorCode параметрі):

Мәні Сипаттама
0 Сұрауды өңдеу жүйелік қателерсіз аяқталды.
5 Төлем жасау әрекеттері аяқталды
5 Жүйелік немесе ішкі қате.

Мысалдар

Сұрау мысалы

curl --request POST \
  --url https://3dsec.berekebank.kz/payment/rest/paymentorder.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data MDORDER=014932b6-9dc7-7782-aeec-a07500a7d8c0 \
  --data '$PAN=5555555555555599' \
  --data '$CVC=123' \
  --data YYYY=2024 \
  --data MM=12 \
  --data 'TEXT=TEST CARDHOLDER' \
  --data language=en

Жауап мысалдары

3-D Secure аутентификациясы қажет болмаған кездегі жауаптың мысалы.

{
  "redirect": "https://3dsec.berekebank.kz/payment/merchants/temp/finish.html?orderId=014932b6-9dc7-7782-aeec-a07500a7d8c0&lang=en",
  "info": "Your order is proceeded, redirecting...",
  "errorCode": 0
}

3-D Secure аутентификациясы қажет болған кездегі жауаптың мысалы.

{
  "info": "Your order is proceeded, redirecting...",
  "errorCode": 0,
  "acsUrl": "https://web.rbsuat.com/acs/auth/start.do",
  "paReq": "eJxVUsFWwjAQ/BVe7yVNmrbIW+JDQOFAVawHvfhKu5QKTaENvsrXm0ARve3MJjOb2cBtU2w7X1jVeSkHFu06VgdlUqa5zAbWa3Rv96xbAdG6Qhy/YHKoUMAc6zrOsJOnA6sXBMFq5fn2kiO1OcOl3XN7nr2M0VkFbnrjUd8S8DRc4F5AayS0T5cBuUCtWCXrWCoBcbK/m4WCs8B3HCAthAKr2Vh43GUuB3JGIOMCRR3LdFk2H0UrAeREQ1IepKq+hc9dIBcAh2or1krt+oQorFU3KQsghgRyneHpYKpaizR5KsLjjIfjZ3d+nLB5lDnh54aG0eR7ftwMgJgTkMYKBXMYdTj1Oo7f91jfpUBOPMSFcdf904POAHbGY/i385cBHXSl93AZ/4IAm10p0dwB8lsDuU48mpoME6XzkYutGr5Pm8fR5G5fUF4c3yI2XT1kb5lvkj0dMoq5ToZxepY0AIiRIe3SSLtvXf37Bz+jLruc",
  "termUrl": "https://3dsec.berekebank.kz/payment/rest/finish3ds.do?lang=en"
}

3-D Secure аутентификациясы қажет болса, paymentOrder бойынша жауап келгенде, клиент ACS серверіне қайта бағытталуы керек. Қайта бағыттаудың екі жолы бар: қалыпты және жеңілдетілген (төмендегі кестені қараңыз).

Қайта бағыттау әдісі Сипаттама
Қалыпты Төлем 3-D Secure арқылы орындалса, мерчанттар клиенттерін acsUrl ішінде көрсетілген мекенжай бойынша ACS серверіне қайта бағыттауы керек, сұраудың негізгі мәтініне MD=mdorder&PaReq=pareq&TermUrl=termUrl қосу керек, осында:
  • mdorder - төлем шлюзіндегі тапсырыстың бірегей идентификаторы;
  • pareq - paymentOrder жауабы ретінде алынған параметр;
  • termUrl - paymentOrder жауабы ретінде алынған параметр;

    • Бұл POST-сұрауы болуы керек.
    Банкпен келісілген конфигурацияға байланысты, ACS серверіндегі аутентификациядан кейін сатып алушы дүкенге немесе төлем шлюзіне қайта бағытталады. Төлемді жалғастыру жолдары төменде көрсетілген.
Жеңілдетілген Клиенттер ACS аутентификация бетіне кіру рұқсатын алуы үшін мерчант оларды мына URL-мекенжайы бойынша төлем шлюзінің бетіне өткізеді:
https://3dsec.berekebank.kz/payment/acsRedirect.do?orderId=«
осында:
  • »« – клиент тапсырысының бірегей нөмірі.

Осыдан кейін, клиенттен қосымша әрекеттердің қажетінсіз, төлем шлюзі клиентті аутентификацияны өтуі үшін ACS серверіне өткізеді.
Рұқсат етілген әрекеттердің санынан асып кетсе, соңғы төлем жасау әрекетіне келесі жауап қайтарылады.
»{"redirect":"false.html?login=test&orderId=85eb9a84-2a47-7cca-b0ae-662c000016d1&lang=ru","info":"Операция өтпеді. Енгізілген деректерді, төлем картасындағы қолжетімді соманы тексеріп, әрекетті қайталаңыз.
Қайта бағыттау орындалуда...","errorCode":0}<br/>Осында қайта бағыттаудың URL-мекенжайы — бұлfailUrlпараметрінде берілген мән (немесеfailUrlберілмеген жағдайда,returnUrl).<br/>Барлық келесі әрекеттерге келесі жауап қайтарылады.<br/>{"redirect":"false.html?login=test&orderId=85eb9a84-2a47-7cca-b0ae-662c000016d1&lang=ru","info":"Redirecting...","errorCode":0}<br/>Осында қайта бағыттаудың URL-мекенжайы — бұлfailUrlпараметрінде берілген мән (немесеfailUrlберілмеген жағдайда,returnUrl``).
Осында төлем шлюзі қатені қайтармайды.

Тапсырыс үшін төлеу сұрауы, карта деректері мерчант (сыртқы 3DS Server) тарапынан жиналады

Сұрау параметрлері

Міндетті Атау Түрі Сипаттама
Иә

userName String Сатушының API есептік жазбасының логині.
Иә

password String Сатушының API есептік жазбасының құпиясөзі.
Иә

MDORDER String Төлем шлюзіндегі тапсырыс нөмірі.
Иә

$PAN Numeric Төлем картасының нөмірі.
Иә

$CVC Numeric Картаның артқы жағындағы CVC/CVV2 коды.
Иә

YYYY Numeric Төлем картасы жарамдылығының аяқталу жылы.
Иә

MM Numeric Төлем картасы жарамдылығының аяқталу айы.
Иә

TEXT Alphabetic Карта иеленушісінің аты.
Иә

language Alphabetic ISO 639-1 бойынша тіл кілті. Көрсетілмесе, әдепкі бойынша дүкен параметрлерінде таңдалған тіл пайдаланылады.
Жоқ

ip String Төлеушінің IP-мекенжайы. IPv6 барлық сұрауларда қолданылады (39 таңбаға дейін).
Жоқ

email String Клиенттің электрондық пошта мекенжайы.
Жоқ

bindingNotNeeded Boolean Рұқсат етілетін мәндер:
  • true – төлемді аяқтағаннан кейін байлам жасау өшірілген (байлам – клиенттің тапсырысты тіркеуге сұрау салған кезде берілген идентификаторы, бұл идентификатор paymentOrder сұратымынан кейін тапсырыстың мәліметтерінен жойылады);
  • false – сәтті төленген жағдайда байламды жасауға болады (қажетті шарттарды сақтаған кезде). Бұл әдепкі бойынша мән.
Жоқ

jsonParams Alphanumeric Кейін сақтауға арналған қосымша ақпарат өрістері келесі түрде көрсетіледі: {"param":"value","param2":"value2"}.
Осы өрістер кейін банк реестрінде көрсету үшін банк процессингіне жіберілуі мүмкін.
Әдепкі бойынша orderNumber (тапсырыс нөмірі) және description (тапсырыс сипаттамасы) көрсетіледі.description 99 таңбадан аспауы керек және мына таңбалар пайдаланылмауы тиіс:% ,+ , күймешені қайтару \r және жолды түсіру \n).
Осы функцияны қосу үшін банкіңізге хабарласыңыз.
Сыртқы 3DS Server пайдаланылса, төлем шлюзі әр paymentOrder сұрауының eci параметрі болатынын күтеді. eci мәні SSL-авторизациясы үшін пайдаланылатын мәндерден өзгеше болса, xid және cavv параметрлерін көрсету керек.
Сипаттаманы көру

billingPayerData Object Клиенттің AVS/AVV қызметтері аясында мекенжай тексерісінен өту үшін қажетті тіркеу деректері (мекенжай, пошта индексі) бар блок. Төлем шлюзінің тарапынан сатушы үшін функция қосулы болған жағдайда міндетті болып табылады.

Төменде billingPayerData блогының параметрлері келтірілген (клиентті тіркеу мекенжайы туралы деректер).

Міндетті Атау Түрі Сипаттама
Жоқ

billingCity String Эмитент банктің нақты картасы бойынша тіркелген қала.
Жоқ

billingCountry String Эмитент банктің нақты картасы бойынша тіркелген ел (ISO 3166-1, сандық).
Жоқ

billingAddressLine1 String Эмитент банктің нақты картасы бойынша тіркелген мекенжай. 1-жол. AVS-тексерісі үшін берілуі міндетті.
Жоқ

billingAddressLine2 String Эмитент банктің нақты картасы бойынша тіркелген мекенжай. 2-жол.
Жоқ

billingAddressLine3 String Эмитент банктің нақты картасы бойынша тіркелген мекенжай. 3-жол.
Жоқ

billingPostalCode String Эмитент банктің нақты картасы бойынша тіркелген пошта индексі. AVS-тексерісі үшін берілуі міндетті.
Жоқ

billingState String Эмитент банктің нақты картасы бойынша тіркелген штат.

Жауап параметрлері

Міндетті Атау Түрі Сипаттама
Иә

errorCode Integer Қате коды. Қате орын алмаған кезде, болмауы мүмкін.
Жоқ

errorMessage String Қате сипаттамасы. Сипаттама тілі сұраудың language параметрінде таңдалады.
Жоқ

info String Жауап сәтті болған жағдайда. Төлем жасау әрекетінің нәтижесі. Төменде ықтимал мәндері көрсетілген.
  • Төлеміңіз өңделді, қайта бағыттау орындалуда...
  • Операция өтпеді. Енгізілген деректерді, картадағы қаражаттың жеткілікті екенін тексеріп, операцияны қайталаңыз. Қайта бағыттау орындалуда...
  • Төлем жасау мүмкін емес. Қайта бағыттау орындалуда...
  • Операция өтпеді. Дүкенге хабарласыңыз. Қайта бағыттау орындалуда...
  • Операция өтпеді. Картаны шығарған банкке хабарласыңыз. Қайта бағыттау орындалуда...
  • Рұқсат етілмеген операция Карта иесінің аутентификациясы сәтсіз аяқталды. Қайта бағыттау орындалуда...
  • Банкпен байланыс жоқ. Кейінірек қайталаңыз. Қайта бағыттау орындалуда...
  • Деректерді енгізудің күту мерзімі аяқталды. Қайта бағыттау орындалуда...
  • Банктен жауап алынбады. Кейінірек қайталаңыз. Қайта бағыттау орындалуда...

errorCode = 0 және info = "Your order is proceeded, redirecting"болса, бұл төлемнің сәтті өңделгенін білдіреді. Басқа жағдайларда қате пайда болды, errorMessage қараңыз.

Қателер кодтары (errorCode параметрі):

Мәні Сипаттама
0 Сұрауды өңдеу жүйелік қателерсіз аяқталды
5 Төлем жасау әрекеттері аяқталды
5 Жүйелік немесе ішкі қате.

Мысалдар

Сұрау мысалы

curl --request POST \\
  --url https://3dsec.berekebank.kz/payment/rest/paymentorder.do \\
  --header 'content-type: application/x-www-form-urlencoded' \\
  --data userName=test_user \\
  --data password=test_user_password \\
  --data MDORDER=0140dda0-71ed-7706-a61f-36bd00a7d8c0 \\
  --data '$PAN=5555555555555599' \\
  --data '$CVC=123' \\
  --data YYYY=2024 \\
  --data MM=12 \\
  --data 'TEXT=TEST CARDHOLDER' \\
  --data language=en \\
  --data 'xid=MDAwMDAwMDEzMzkyMjg5ODExNTc=' \\
  --data 'cavv=AAABCpEChRM5IomAKFAAAAAAAAA=' \\
  --data eci=05

Жауап мысалы

{
  "redirect": "https://3dsec.berekebank.kz/payment/merchants/temp/finish.html?orderId=01493844-d4d3-703f-9f7e-a73900a7d8c0&lang=en",
  "info": "Your order is proceeded, redirecting...",
  "errorCode": 0
}

Apple Pay тапсырысын тіркеу

Сұрау параметрлері

Міндетті Атау Түрі Сипаттама
Иә

merchant String Төлем шлюзі жүйесіндегі сатушының логині.
Иә

orderNumber Alphanumeric Мерчант жүйесіндегі тапсырыс нөмірі (ID); әр мерчант үшін бірегей болуы керек.
Жоқ

description String Кез келген пішімдегі тапсырыс сипаттамасы.
Осы өрісті процессинг жүйесіне жіберу функциясын қосу үшін техникалық қолдау көрсету қызметіне хабарласыңыз.
Жоқ

language Alphabetic ISO 639-1 бойынша тіл кілті. Көрсетілмесе, әдепкі бойынша дүкен параметрлерінде таңдалған тіл пайдаланылады.
Жоқ

additionalParameters Сипаттаманы көру Кейін қарауы үшін сатушының жеке кабинетінде сақталатын тапсырыстың қосымша параметрлері. Параметр атауының әрбір жаңа жұбы мен оның мәндері үтірмен бөлінуі қажет. Төменде пайдалану мысалы келтірілген.
{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"}
Жоқ

preAuth String Алдын ала авторизациялау (клиент шотындағы қаражатты шешілгенше бұғаттау) қажеттілігін анықтайтын параметр. Келесі мәндер қолжетімді:
  • true - екі кезеңді төлем жасау мүмкіндігі қосылған;
  • false- бір кезеңді төлем жасау мүмкіндігі қосылған (қаражат бірден шешіледі).
Параметр жоқ болса, бір кезеңді төлем жасалады.
Иә

paymentToken String paymentToken параметрінде шифры ашылған және Base64 модулінде кодталған Apple Pay жүйесіндегі PKPaymentToken Object нысанынан алынған paymentData сипат мәні бар болуы керек (толық ақпаратты Apple Pay құжаттамасынан қараңыз). Осылайша, төлем шлюзіне төлем жасау сұрауын жіберу үшін сатушы:
  1. Apple Pay жүйесінен paymentData сипаты бар PKPaymentToken Object нысанын алуы керек;
  2. paymentData мәнін шығарып, оны Base64 модулінде кодтауы керек;
  3. paymentData сипатының кодталған мәнін сатушы төлем шлюзіне бағыттайтын төлем жасау сұрауындағы paymentToken параметрінің мәні ретінде қосуы керек.

Жауап параметрлері

Міндетті Атау Түрі Сипаттама
Иә

success String Сұраудың сәтті өңделгенін көрсетеді. Келесі мәндер қолжетімді:
  • true - сұрау сәтті өңделді
  • false - сұрау өтпеді.
Сипаттаманы көру data N/A Осы параметр төлем сәтті өңделген кезде ғана қайтарылады. Төмендегі сипаттаманы қараңыз.
Сипаттаманы көру error N/A Осы параметр төлемде қате пайда болған кезде ғана қайтарылады. Төмендегі сипаттаманы қараңыз.
Сипаттаманы көру orderStatus N/A Тапсырыс күйінің параметрлері бар және төлем шлюзі сұраудың барлық параметрлерін дұрыс деп анықтаған кезде ғана қайтарылады. Төмендегі сипаттаманы қараңыз.

data бөлімінде келесі элементтер бар.

Міндетті Атау Түрі Сипаттама
Иә

orderId String Төлем шлюзіндегі тапсырыс нөмірі. Төлем шлюзі ауқымында бірегей болып табылады.

error бөлімінде келесі элементтер бар.

Міндетті Атау Түрі Сипаттама

code Integer Қате коды.

description String Қатенің толық техникалық сипаттамасы – бұл параметрдің құрамы пайдаланушыға көрсетілмеуі керек.

message String Пайдаланушыға көрсетілетін қате туралы хабар.

orderStatus бөлімінде келесі элементтер бар.

Міндетті Атау Түрі Сипаттама
Жоқ

errorCode Integer Қате коды. Қате орын алмаған кезде, болмауы мүмкін.
Жоқ

orderNumber Alphanumeric Мерчант жүйесіндегі тапсырыс нөмірі (ID); әр мерчант үшін бірегей болуы керек.
Жоқ

orderStatus Integer Осы параметрдің мәні төлем шлюзіндегі тапсырыстың күйін көрсетеді. Тапсырыс табылмаған кезде болмайды. Төменде қолжетімді параметрлер тізімі берілген:
  • 0 - тапсырыс тіркелген, бірақ төленбеген;
  • 1 - алдын ала авторизацияланған сома ұсталған (екі кезеңді төлемдер үшін)
  • 2 - тапсырыс сомасының толық авторизациясы орындалды;
  • 3 - авторизациядан бас тартылды;
  • 4 - транзакция бойынша қайтару операциясы орындалды;
  • 5 - банк-эмитентінің ACS сервері арқылы авторизация іске қосылды;
  • 6 - авторизация орындалмады.
Жоқ

actionCode Integer Банк процессингінен алынған жауап коды.
Жоқ

actionCodeDescription String Банк процессингімен қайтарылатын actionCode сипаттамасы.
Жоқ

amount Integer Ең төменгі валюта бірліктерінде көрсетілген төлем сомасы (мысалы, тиынмен).
Жоқ

currency Integer ISO 4217 төлем валютасының коды. Көрсетілмеген жағдайда, әдепкі мән пайдаланылады.
Жоқ

date String Тапсырысты тіркеу күні.
Жоқ

ip String Төлеушінің IP-мекенжайы. IPv6 барлық сұрауларда қолданылады (39 таңбаға дейін).
Сипаттаманы көру merchantOrderParams N/A Мерчанттың қосымша параметрлері берілетін атрибуттары бар бөлім. Төмендегі сипаттаманы қараңыз.
Сипаттаманы көру attributes N/A Төлем жүйесіндегі тапсырыс атрибуттары (тапсырыс нөмірі). Төмендегі сипаттаманы қараңыз.
Сипаттаманы көру cardAuthInfo N/A Сатып алушының төлем картасы туралы ақпарат. Төмендегі сипаттаманы қараңыз.
Жоқ

authDateTime String 1 қаңтар, 1970 жылдың (GMT) 00:00 уақытынан өтіп кеткен, миллисекунд саны ретінде көрсетілген авторизацияның күні мен уақыты.
Жоқ

terminalId String Терминал идентификаторы.
Жоқ

authRefNum String Төлемді тіркеу кезінде берілген төлем авторизациясының тіркеу нөмірі.
Сипаттаманы көру paymentAmountInfo N/A Растау, есептен шығару және қайтару сомалары туралы ақпаратты қамтитын кірістірілген параметрлері бар параметр. Төмендегі сипаттаманы қараңыз.
Сипаттаманы көру bankInfo N/A Кірістірілген  bankCountryName параметрі бар. Төмендегі сипаттаманы қараңыз.

merchantOrderParams бөлімінде келесі элементтер бар.

Міндетті Атау Түрі Сипаттама
Иә

name Alphanumeric Мерчанттың қосымша параметрінің атауы.
Иә

value Alphanumeric Сатушының қосымша параметрінің мәні – 1024 таңбаға дейін.

attributes бөлімінде келесі элементтер бар.

Міндетті Атау Түрі Сипаттама
Иә

name Alphanumeric Қосымша параметрдің атауы.
Иә

value Alphanumeric Қосымша параметрдің мәні – 1024 таңбаға дейін.

cardAuthInfo бөлімінде келесі элементтер бар.

Міндетті Атау Түрі Сипаттама
Иә

expiration Integer Келесі пішімдегі картаның жарамдылық мерзімі: YYYYMM. Тапсырыс бойынша төлем жасалған соң ғана көрсетіледі.
Иә

cardholderName Alphabetic Карта иесінің латын әліпбиімен көрсетілген аты. Осы параметр тек тапсырыс төленгеннен кейін беріледі.
Иә

approvalCode String Халықаралық төлем жүйесінің (ХТЖ) авторизация коды. Бұл өрістің ұзындығы бекітілген (алты таңба) және сандар мен латын әріптерінен тұруы мүмкін.
Иә

pan String Жасырын DPAN: сатып алушының мобильді құрылғысымен байланыстырылған және Apple Pay жүйесінде төлем картасы нөмірінің функцияларын атқаратын нөмір.

paymentAmountInfo бөлімінде келесі элементтер бар.

Міндетті Атау Түрі Сипаттама
Иә

paymentState String Тапсырыс күйі, параметр мына мәндерде болуы мүмкін:
  • CREATED - тапсырыс жасалған (бірақ төленбеген);
  • APPROVED - тапсырыс расталған (сатып алушы шотындағы қаражат бұғатталған);
  • DEPOSITED- тапсырыс аяқталды (қаражат сатып алушы шотынан түсті);
  • DECLINED - тапсырыс қабылданбады;
  • REVERSED - бас тарту операциясы;
  • REFUNDED - қаражатты қайтару операциясы.
Иә

approvedAmount Integer Сатып алушының шотында бұғатталып қалған ең төменгі валюта бірліктеріндегі сома (мысалы, цент түрінде). Тек екі сатылы төлемдерде ғана пайдаланылады.
Иә

depositedAmount Integer Минималды валюта бірлігімен (мысалы, тиынмен) берілген есептен шығару сомасы.
Иә

refundedAmount Integer Минималды бірлікпен берілген қайтару сомасы.

bankInfo бөлімінде келесі элементтер бар.

Міндетті Атау Түрі Сипаттама
Иә

bankCountryName String Эмитент банктің елі.

Қателер коды

Мысалдар

Сұрау мысалы

curl --request POST \
--url https://3dsec.berekebank.kz/payment/applepay/payment.do \
--header 'Content-Type: application/json' \
--data-raw '{
  "additionalParameters" : {
    "phone" : "9521235847",
    "order-pain" : "111",
    "email" : "apple@pay.com"
  },
  "features" : [ ],
  "language" : "ru",
  "merchant" : "sandbox_merchant",
  "orderNumber" : "281477871",
  "paymentToken" : "eyJkYXRhIjoiYPhK3M1bEtm...YjM2NWMzZWNmYjE5fIkVDX3YxIn0=",
  "preAuth" : false,
  "recurrent" : false,
  "recurrentInitialize" : false
}'

Төлем сәтті аяқталған жағдайдағы жауап

{
    "success": true,
    "data": {
        "orderId": "b926351f-a634-49cf-9484-ccb0a3b8cfad"
    },
    "orderStatus": {
        "errorCode": "0",
        "orderNumber": "229",
        "orderStatus": 1,
        "actionCode": 0,
        "actionCodeDescription": "",
        "amount": 960000,
        "currency": "978",
        "date": 1478682458102,
        "ip": "81.18.144.51",
        "merchantOrderParams": [
            {
                "name": "param2",
                "value": "param2"
            },
            {
                "name": "param1",
                "value": "param1"
            }
        ],
        "attributes": [
            {
                "name": "mdOrder",
                "value": "b926351f-a634-49cf-9484-ccb0a3b8cfad"
            }
        ],
        "cardAuthInfo": {
            "expiration": "201907",
            "cardholderName": "CARD HOLDER",
            "approvalCode": "123456",
            "pan": "520424**0010"
        },
        "authDateTime": 1478682459082,
        "terminalId": "12345678",
        "authRefNum": "111111111111",
        "paymentAmountInfo": {
            "paymentState": "APPROVED",
            "approvedAmount": 960000,
            "depositedAmount": 0,
            "refundedAmount": 0
        },
        "bankInfo": {
            "bankCountryName": "<UNKNOWN>"
        }
    }
}

Төлем сәтсіз аяқталған жағдайдағы жауап

{
  "error": {
    "code": 10,
    "description": "Processing Error",
    "message": "Auth is invalid"
  },
  "success": false
}

Google Pay тапсырысын тіркеу

Сұрау параметрлері

Тапсырысты тіркеу үшін /google/payment.do сұрауы пайдаланылады.

Міндетті Атау Түрі Сипаттама
Иә

merchant String Төлем шлюзі жүйесіндегі сатушының логині.

Иә

| orderNumber | Alphanumeric | Мерчант жүйесіндегі тапсырыс нөмірі (ID); әр мерчант үшін бірегей болуы керек. |

Жоқ

| description | String | Кез келген пішімдегі тапсырыс сипаттамасы.
Осы өрісті процессинг жүйесіне жіберу функциясын қосу үшін техникалық қолдау көрсету қызметіне хабарласыңыз. |

Жоқ

| language | Alphabetic | ISO 639-1 бойынша тіл кілті. Көрсетілмесе, әдепкі бойынша дүкен параметрлерінде таңдалған тіл пайдаланылады. |

Жоқ

| additionalParameters | Сипаттаманы көру | Кейін қарауы үшін сатушының жеке кабинетінде сақталатын тапсырыстың қосымша параметрлері. Параметр атауының әрбір жаңа жұбы мен оның мәндері үтірмен бөлінуі қажет. Төменде пайдалану мысалы келтірілген.
{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"} |

Жоқ

| preAuth | String | Алдын ала авторизациялау (клиент шотындағы қаражатты шешілгенше бұғаттау) қажеттілігін анықтайтын параметр. Келесі мәндер қолжетімді:

Параметр жоқ болса, бір кезеңді төлем жасалады. |

Жоқ

| clientId | Alphanumeric | Мерчант жүйесіндегі клиенттің нөмірі (ID) — 255 таңбаға дейін. Байламдардың функцияларын орындау үшін қолданылады. Мерчантқа байламдарды жасауға рұқсат етілсе, жауап ретінде қайтарылуы мүмкін.
Төлемдер байлам арқылы өңделген кезде осы параметрді міндетті түрде таңдау қажет. Кері жағдайда, төлемді жасау мүмкін болмайды. |

Иә

| paymentToken | String | Google Pay жүйесінен алынған және Base64 модулінде кодталған токен. |

Иә

| ip | String | Төлеушінің IP-мекенжайы. IPv6 барлық сұрауларда қолданылады (39 таңбаға дейін). |

Иә

| amount | Integer | Ең төменгі валюта бірліктерінде көрсетілген төлем сомасы (мысалы, тиынмен). |

Жоқ

| currencyCode | String | ISO 4217 төлем валютасының цифрлық коды. Көрсетілмеген жағдайда, 643 (Ресей рублі) болып есептеледі. |

Сипаттаманы көру

| email | String | Клиенттің электрондық пошта мекенжайы. |

Сипаттаманы көру

| phone | Integer | Сатып алушының телефон нөмірі. Ел кодын әрқашан көрсету керек, осында + белгісін көрсетуге не көрсетпеуге болады. Осылайша, келесі нұсқалар қолжетімді болады:

|

Иә

| returnUrl | String | Төлем сәтті орындалған жағдайда, пайдаланушы бағытталатын мекенжай. Мекенжайды пайдаланылатын протоколымен бірге толық көрсету қажет (мысалы, test.ruорнына https://test.ru ). Кері жағдайда, пайдаланушы мына мекенжайға бағытталады: «https://https://3dsec.berekebank.kz/payment/». |

Жоқ

| failUrl | String | Төлем орындалмаған жағдайда, пайдаланушы бағытталатын мекенжай. Мекенжайды пайдаланылатын протоколымен бірге толық көрсету қажет (мысалы, test.ruорнына https://test.ru ). Кері жағдайда, пайдаланушы мына мекенжайға бағытталады: «https://https://3dsec.berekebank.kz/payment/». |

Жауап параметрлері

Міндетті Атау Түрі Сипаттама
Иә

success String Сұраудың сәтті өңделгенін көрсетеді. Келесі мәндер қолжетімді:
  • true - сұрау сәтті өңделді
  • false - сұрау өтпеді.
Сипаттаманы көру data N/A Осы параметр төлем сәтті өңделген кезде ғана қайтарылады. Төмендегі сипаттаманы қараңыз.
Сипаттаманы көру error N/A Осы параметр төлемде қате пайда болған кезде ғана қайтарылады. Төмендегі сипаттаманы қараңыз.
Сипаттаманы көру orderStatus N/A Тапсырыс күйінің параметрлері бар және төлем шлюзі сұраудың барлық параметрлерін дұрыс деп анықтаған кезде ғана қайтарылады. Төмендегі сипаттаманы қараңыз.

data бөлімінде келесі элементтер бар.

Міндетті Атау Түрі Сипаттама
Иә

orderId String Төлем шлюзіндегі тапсырыс нөмірі. Төлем шлюзі ауқымында бірегей болып табылады.
Иә

orderId String Төлем шлюзіндегі тапсырыс нөмірі. Төлем шлюзі ауқымында бірегей болып табылады.
Банк-эмитентінің ACS серверінде қосымша аутентификация пайдаланылған жағдайда ғана

termUrl String 3D-Secure арқылы төлеген жағдайда сәтті жауап берілген кезде. ACS серверіне қайта бағыттайтын URL-мекенжайы.
Банк-эмитентінің ACS серверінде қосымша аутентификация пайдаланылған жағдайда ғана

acsUrl String 3D-Secure арқылы төлеген жағдайда сәтті жауап берілген кезде. ACS серверіне қайта бағыттайтын URL-мекенжайы.
Банк-эмитентінің ACS серверінде қосымша аутентификация пайдаланылған жағдайда ғана

paReq String 3D-Secure арқылы төлеген жағдайда сәтті жауап берілген кезде. Payment Authentication Request. Төлеуші аутентификациясының сұрауы.
Байламдар пайдаланылса, параметр қайтарылады

bindingId String Бұрын жасалған байламның идентификаторы. Оны тек мерчанттың байламдармен жұмыс істеуге рұқсаты бар болған жағдайда ғана пайдалануға болады.

error бөлімінде келесі элементтер бар.

Міндетті Атау Түрі Сипаттама

code Integer Қате коды.

| description | String | Қатенің толық техникалық сипаттамасы – бұл параметрдің құрамы пайдаланушыға көрсетілмеуі керек. |

| message | String | Пайдаланушыға көрсетілетін қате туралы хабар. |

Қателер коды

Қате коды Хабар
0 Сұрауды өңдеу жүйелік қателерсіз аяқталды
1 Картадағы қаражат жеткіліксіз
5 Кіру рұқсаты жоқ.
10 paymentToken параметрінің дұрыс емес мәні
10 orderNumber параметрінің дұрыс емес мәні
10 merchant параметрінің дұрыс емес мәні
10 ip параметрінің дұрыс емес мәні
10 Жіберілген деректерді шифрлау орындалмады.
10 Сатушыда жеке кілті жоқ

Мысалдар

Сұрау мысалы

curl --request POST \
--url https://3dsec.berekebank.kz/payment/google/payment.do \
--header 'Content-Type: application/json' \
--data-raw '{
  "amount" : 1000,
  "features" : [ ],
  "merchant" : "sandbox_merchant",
  "orderNumber" : "350467565",
  "paymentToken" : "eyJzaWduYXR1cmUiOiJNRVF...dGM3NHUxQWY5L1pNPVwifSJ9",
  "preAuth" : false,
  "returnUrl" : "https://ya.ru/"
}'

Төлем сәтті аяқталған жағдайдағы жауап

{
"success":true,
"data": {
 "orderId": "12312312123"
 }
}

Токені жоқ карта мен ACS серверіне өткізу орындалатын сұрауға жауап мысалы

{"success":true,"data":{"orderId":"e757d0cf-a028-7bdc-acb9-44480008afa2","acsUrl":"https://test.ru/acs/auth/start.do","paReq":"eJxV....DOm3R/rFG/TvQ/wAgGS/bg==","termUrl":"https://3dsec.berekebank.kz/payment/rest/finish3ds.do"}

Төлем сәтсіз аяқталған жағдайдағы жауап

{
  "error": {
    "code": 1,
    "description":
"Processing Error",
    "message":
"The funds on the card are not sufficient"
  },
  "success": false
}

Уведомления обратного вызова

API платежного шлюза позволяет получать уведомления обратного вызова (callback-уведомления) об изменении статусов платежей.

Общая информация

События, о которых могут приходить уведомления

Вы можете получать уведомления об изменении статуса оплаты заказа и о других событиях в платежном шлюзе.

Наиболее распространенные уведомления описывают изменения статуса заказа, например:

Более сложные интеграции могут подразумевать дополнительные триггеры обратного вызова, такие как:

Тип триггера передается в параметре operation уведомления обратного вызова (см. подробности ниже). Для удобства уведомления для дополнительных триггеров могут быть направлены на другой URL-адрес с помощью параметра dynamicCallbackUrl в запросах на регистрацию заказа.

Интеграция через уведомления обратного вызова (callback)

Вместо последнего шага интеграции через редирект вы можете выбрать один из следующих подходов.

Использовать returnUrl

Когда код вашего сайта, расположенный по адресу returnUrl (например, https://mybestmerchantreturnurl.com/?back&amp;orderId=61c33664-85a0-7d6b-af26-09ee009c4000&amp;lang=en), идентифицирует перенаправляемого из шлюза держателя карты посде попытки оплаты, вы можете проверить статус заказа с помощью API-запроса getOrderStatusExtended.
Этот вариант является самым простым, но он не совсем надежен, поскольку перенаправление держателя карты может завершиться ошибкой (например, в результате обрыва соединения или закрытия браузера держателем карты), а returnUrl может не получить триггер для вызова getOrderStatusExtended.

getOrderStatusExtended.do

curl --request POST \
  --url https://3dsec.berekebank.kz/payment/rest/getOrderStatusExtended.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data orderId=016b6f47-4628-7ea2-80f5-6c6e00a7d8c0 \
  --data language=en
{
  "errorCode": "0",
  "errorMessage": "Success",
  "orderNumber": "11008",
  "orderStatus": 2,
  "actionCode": 0,
  "actionCodeDescription": "",
  "amount": 2000,
  "currency": "398",
  "date": 1618577250840,
  "orderDescription": "my_first_order",
  "merchantOrderParams": [
    {
      "name": "browser_language_param",
      "value": "en"
    },
    {
      "name": "browser_os_param",
      "value": "UNKNOWN"
    },
    {
      "name": "user_agent",
      "value": "curl/7.75.0"
    },
    {
      "name": "browser_name_param",
      "value": "DOWNLOAD"
    }
  ],
  "transactionAttributes": [],
  "attributes": [
    {
      "name": "mdOrder",
      "value": "016b7747-c4ed-70b3-bc36-fdd400a7d8c0"
    }
  ],
  "cardAuthInfo": {
    "maskedPan": "555555**5599",
    "expiration": "202412",
    "cardholderName": "TEST CARDHOLDER",
    "approvalCode": "123456",
    "pan": "555555**5599"
  },
  "authDateTime": 1618577288377,
  "terminalId": "123456",
  "authRefNum": "931793605827",
  "paymentAmountInfo": {
    "paymentState": "DEPOSITED",
    "approvedAmount": 2000,
    "depositedAmount": 2000,
    "refundedAmount": 0
  },
  "bankInfo": {
    "bankCountryCode": "UNKNOWN",
    "bankCountryName": "&ltUnknown&gt"
  }
}

Использовать подписанный callback шлюза

Если вы знаете, как обращаться с цифровыми сертификатами и подписями, вы можете использовать callback с цифровой подписью и контрольной суммой (шлюз позволяет настроить отправку таких уведомлений). Контрольная сумма используется для проверки и безопасности. После того, как подпись уведомления была проверена, уже нет необходимости отправлять getOrderStatusExtended, потому что уведомление содержит в себе информацию о статусе заказа.

https://mybestmerchantreturnurl.com/callback/?mdOrder=1234567890-098776-234-522&orderNumber=0987&checksum=DBBE9E54D42072D8CAF32C7F660DEB82086A25C14FD813888E231A99E1220AB3&operation=deposited&status=1

Типы уведомлений

Уведомления без контрольной суммы

Эти уведомления содержат только информацию о заказе, поэтому потенциально продавец рискует принять уведомление, отправленное злоумышленником, за подлинное.

Уведомления с контрольной суммой

Такие уведомления помимо сведений о заказе содержат аутентификационный код. Аутентификационный код представляет собой контрольную сумму сведений о заказе. Эта контрольная сумма позволяет убедиться, что callback-уведомление действительно было отправлено платежным шлюзом.
Существует два способа реализации callback-уведомлений с контрольной суммой:


Открытый ключ можно выгрузить из личного кабинета платежного шлюза при наличии соответствующих полномочий. Для большей безопасности рекомендуется использовать асимметричную криптографию.
Чтобы включить уведомления с контрольными суммами, а также получить соответствующий криптографический ключ, обратитесь в нашу службу технической поддержки.

Требования к SSL-сертификатам на сайте продавца

Если уведомление о состоянии заказа приходит через HTTPS-соединение, необходимо удостоверить подлинность сайта с помощью SSL-сертификата, выпущенного и подписанного доверенным центром сертификации (см. таблицу ниже). Использование самозаверенных сертификатов не допускается.

Требование Описание
Алгоритм подписи. Не ниже SHA-256.
Поддерживаемые центры сертификации. Ниже приведены примеры организаций, которые регистрируют цифровые сертификаты:

Формат URL-адресов уведомлений

Поддерживаются запросы POST и GET.

Ниже приведен пример GET-запроса. Параметры получены в запросе.

Уведомление без контрольной суммы (GET)

https://mybestmerchantreturnurl.com/callback/?mdOrder=
1234567890-098776-234-522&orderNumber=0987&operation=deposited&
callbackCreationDate=Mon Jan 31 21:46:52 UTC 2022&status=0

Уведомление с контрольной суммы (GET)

https://mybestmerchantreturnurl.com/callback/?mdOrder=1234567890-098776-234-522&
orderNumber=0987&checksum=DBBE9E54D42072D8CAF32C7F660DEB82086A25C14FD813888E231A99E1220AB3&
operation=deposited&callbackCreationDate=Mon Jan 31 21:46:52 UTC 2022&status=0

Для POST-коллбэков вы получите те же параметры в теле HTTP (вместо параметров запроса).

Уведомление без контрольной суммы (POST)

https://mybestmerchantreturnurl.com/callback/
mdOrder=
1234567890-098776-234-522&orderNumber=0987&operation=deposited&
callbackCreationDate=Mon Jan 31 21:46:52 UTC 2022&status=0

Уведомление с контрольной суммой (POST)

https://mybestmerchantreturnurl.com/callback/
mdOrder=1234567890-098776-234-522&
orderNumber=0987&checksum=DBBE9E54D42072D8CAF32C7F660DEB82086A25C14FD813888E231A99E1220AB3&operation=deposited&callbackCreationDate=Mon Jan 31 21:46:52 UTC 2022&status=0

Передаваемые параметры представлены в таблице ниже.

В таблице указаны только основные параметры. Вы также можете использовать дополнительные параметры, если они настроены в платежном шлюзе.

Параметр Описание
mdOrder Уникальный номер заказа, хранящийся в платежном шлюзе.
orderNumber Уникальный номер заказа (идентификатор) в системе мерчанта.
checksum Аутентификационный код или контрольная сумма, полученная из набора параметров.
operation Тип события, вызвавшего уведомление:
  • approved - холдирование (удержание) средств на счете покупателя;
  • deposited - операция завершения;
  • reversed - платеж был отменен;
  • refunded - деньги за заказ возвращены;
  • bindingCreated - карта плательщика сохранена (cвязка создана);
  • bindingActivityChanged - существующая связка была отключена/включена.
  • declinedByTimeout - платеж был отклонен из-за истечения времени ожидания;
  • declinedCardPresent - отклоненная транзакция с предъявлением карты (оплата физической картой).
status Индикатор успешности операции, указанной в параметре operation:
  • 1 - успех;
  • 0 - ошибка.

Пользовательские заголовки callback уведомлений

Пользовательские заголовки callback уведомлений можно задать, обратившись в службу технической поддержки. Например:

'http://mybestmerchantreturnurl.com/callback.php', headers={Authorization=token, Content-type=plain
/text}, params={orderNumber=349002, mdOrder=5ffb1899-cd1e-7c1e-8750-e98500093c43, operation=deposited, status=1}

где {Authorization=token, Content-type=plain/text} – это настраиваемый заголовок.

Примеры

Пример URL-адреса уведомления без контрольной суммы

https://mybestmerchantreturnurl.com/callback/?mdOrder=1234567890-098776-234-522&orderNumber=0987&operation=deposited&status=0

Пример URL-адреса уведомления с контрольной суммой

https://mybestmerchantreturnurl.com/callback/?mdOrder=1234567890-098776-234-522&orderNumber=0987&checksum=DBBE9E54D42072D8CAF32C7F660DEB82086A25C14FD813888E231A99E1220AB3&operation=deposited&status=0

Алгоритм обработки уведомлений о состоянии заказов

В разделах ниже представлен алгоритм обработки уведомлений о состоянии заказов в зависимости от типа таких уведомлений.

Уведомление без контрольной суммы

  1. Платежный шлюз отправляет на сервер продавца следующий запрос.
    https://mybestmerchantreturnurl.com/callback/?mdOrder=1234567890-098776-234-522&amp;orderNumber=0987&amp;operation=deposited&amp;status=0
  2. Сервер продавца возвращает HTTP-сообщение 200 OK платежному шлюзу.

Уведомление с контрольной суммой

  1. Платежный шлюз отправляет HTTPS-запрос следующего вида на сервер мерчанта, при этом:

    • при использовании симметричной криптографии контрольная сумма формируется с помощью ключа, общего для платежного шлюза и продавца;
    • при использовании асимметричной криптографии контрольная сумма формируется с помощью закрытого ключа, известного только платежному шлюзу.
      https://mybestmerchantreturnurl.com/path?amount=123456&amp;orderNumber=10747&amp;checksum=DBBE9E54D42072D8CAF32C7F660DEB82086A25C14FD813888E231A99E1220AB3&amp;mdOrder=3ff6962a-7dcc-4283-ab50-a6d7dd3386fe&amp;operation=deposited&amp;status=1
      Порядок параметров в уведомлении может быть произвольным.

  2. На стороне продавца из строки параметров уведомления удаляются параметры checksum и sign_alias, а значение параметра checksum (контрольная сумма) сохраняется для проверки подлинности уведомления;

  3. Оставшиеся параметры и их значения используются для создания следующей строки.
    имя_параметра1;значение_параметра1;имя_параметра2;значение_параметра2;…;имя_параметраN;значение_параметраN;
    В этом случае пары имя_параметра;значение_параметра должны быть отсортированы в прямом алфавитном порядке (по возрастанию) по именам параметров.
    Пример сгенерированной строки параметров:
    amount;123456;mdOrder;3ff6962a-7dcc-4283-ab50-a6d7dd3386fe;operation;deposited;orderNumber;10747;status;1;

  4. Контрольная сумма рассчитывается на стороне мерчанта, способ расчета зависит от способа ее формирования:

    • при использовании симметричной криптографии - с помощью алгоритма HMAC-SHA256 и общего с платежным шлюзом закрытого ключа;
    • при использовании асимметричной криптографии - с помощью алгоритма хеширования, который зависит от способа создания ключевой пары, и открытого ключа, который связан с закрытым ключом, находящимся на стороне платежного шлюза.

  5. В получившейся строке контрольной суммы все буквы нижнего регистра заменяются на буквы верхнего регистра.

  6. Происходит сравнение полученного значения с контрольной суммой, извлеченной ранее из параметра checksum.

  7. Если контрольные суммы совпадают, сервер отправляет в платежный шлюз HTTP-код 200 OK.

Если контрольные суммы совпадают, это уведомление подлинно и было отправлено платежным шлюзом. В противном случае вероятно, что злоумышленник пытается выдать свое уведомление за уведомление платежного шлюза.

Уведомление о статусе платежа

Для того, чтобы определить, прошел ли платеж успешно или нет, вам необходимо:

  1. Проверить подпись (параметр checksum в уведомлении);
  2. Проверять два параметра уведомления обратного вызова: operation и status.

Если значение параметра operation отличается от approved или deposited, то уведомление обратного вызова относится к статусу оплаты.

Неуспешные уведомления

Если в платежный шлюз возвращается ответ, отличный от HTTP-кода 200 OK, отправка уведомления считается неуспешной. В этом случае платежный шлюз повторяет уведомление с интервалом в 30 секунд до тех пор, пока не будет выполнено одно из следующих условий:

При достижении одного из указанных выше условий попытки отправки callback-уведомлений об операции прекращаются.

Дополнительные параметры уведомлений обратного вызова

В уведомлениях обратного вызова вы можете использовать следующие дополнительные параметры, если они настроены в платежном шлюзе. Если вы хотите их использовать, свяжитесь с нашей службой поддержки.

Параметр Описание Тип события
bindingId UUIID созданных/обновленных сохраненных учетных данных (связки). BINDING_CREATED, BINDING_ACTIVITY_CHANGED
email Электронная почта клиента. BINDING_CREATED
phone Телефон клиента. BINDING_CREATED
panMasked Маскированный PAN карты клиента. BINDING_CREATED
panCountryCode Код страны клиента. BINDING_CREATED
enabled Активна ли связка (true/false). BINDING_ACTIVITY_CHANGED
currentReverseAmountFormatted Форматированная сумма операции отмены. REVERSED
currentRefundAmountFormatted Отформатированная сумма операции возврата. REFUNDED
operationRefundedAmountFormatted Отформатированная сумма операции возврата. REFUNDED
operationRefundedAmount Сумма возврата в минимальных денежных единицах (например, в центах). REFUNDED
externalRefundId Внешний идентификатор операции возврата. REFUNDED
callbackCreationDate Дата создания уведомления обратного вызова. Требуется специальная настройка продавца. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT, BINDING_CREATED, BINDING_ACTIVITY_CHANGED
status Статус операции: 1 - успех, 0 - неудача DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
operation Тип callback-а Possible values: deposited, approved, reversed, refunded, bindingCreated, bindingActivityChanged, declinedByTimeout, declinedCardpresent DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT, BINDING_CREATED, BINDING_ACTIVITY_CHANGED
finishCheckUrl URL для генерации чека DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
sign_alias Имя ключа, используемого для подписи. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT, BINDING_CREATED, BINDING_ACTIVITY_CHANGED
checksum Контрольная сумма уведомления обратного вызова (используется для уведомлений обратного вызова с контрольной суммой). DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT, BINDING_CREATED, BINDING_ACTIVITY_CHANGED
cardholderName Имя держателя карты. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
amount Сумма зарегистрированного заказа в минимальных денежных единицах. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
paymentAmount Сумма зарегистрированного заказа в минимальных денежных единицах. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
amountFormatted Отформатированная сумма зарегистрированного заказа. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
feeAmount Сумма комиссии в минимальных единицах валюты. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
approvedAmount Предварительно авторизованная сумма в минимальных денежных единицах. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
depositedAmount Сумма завершения в минимальных денежных единицах. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
refundedAmount Сумма возмещения в минимальных единицах валюты. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
approvedAmountFormatted Отформатированная предварительно авторизованная сумма. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
depositedAmountFormatted Отформатированная сумма зачисления. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
refundedAmountFormatted Отформатированная сумма возврата. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
totalAmountFormatted Отформатированная общая сумма заказа (зарегистрированная сумма + комиссия). DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
depositedTotalAmountFormatted Отформатированная общая сумма завершения (все суммы завершения + все суммы возврата + комиссия). DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
approvalCode Код авторизации платежа, полученный от процессинга. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
authCode Код авторизации DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
bankName Наименование банка, выпустившего карту клиента. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
currency Валюта заказа. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
depositFlag Флаг, указывающий тип операции.
  • 1 - покупка
  • 2 - преавторизация
 DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
eci Электронный коммерческий индикатор. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
ip IP адрес плательщика. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
ipCountryCode Код страны банка-эмитента. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
maskedPan Маскированный номер карты клиента. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
mdOrder Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
mdorder Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
merchantFullName ФИО продавца. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
merchantLogin Логин продавца. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
orderDescription Описание заказа. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
orderNumber Номер заказа (ID) в системе мерчанта. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
threeDSType Вид транзакции (3DS). Возможные значения: SSL, THREE_DS1_FULL, THREE_DS1_ATTEMPT, THREE_DS2_FULL, THREE_DS2_FRICTIONLESS, THREE_DS2_ATTEMPT, THREE_DS2_EXEMPTION_GRANTED, THREE_DS2_3RI, THREE_DS2_3RI_ATTEMPT DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
date Дата создания заказа. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
clientId Номер клиента (ID) в системе мерчанта. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT,BINDING_CREATED, BINDING_ACTIVITY_CHANGED
actionCode Код результата выполнения операции. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
actionCodeDescription Описание кода результата выполнения операции. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
paymentRefNum Reference Retrieval Number - идентификатор транзакции, присвоенный банком-эквайером. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
paymentState Статус заказа. Possible values: started, payment_approved, payment_declined, payment_void, payment_deposited, refunded, pending, partly_deposited DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
paymentWay Способ оплаты заказа. Дополнительные возможные значения параметра приведены здесь. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
processingId Идентификатор клиента в процессинге. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
refNum Reference Retrieval Number - идентификатор транзакции, присвоенный банком-эквайером. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
refnum Reference Retrieval Number - идентификатор транзакции, присвоенный банком-эквайером. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
terminalId Идентификатор терминала в системе, обрабатывающей платеж. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
paymentSystem Наименование платежной системы. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
currencyName Трехбуквенный ISO-код валюты. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
transactionAttributes Атрибуты заказа. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
paymentDate Дата оплаты заказа. DEPOSITED, APPROVED, REVERSED, REFUNDED
depositedDate Дата операции завершения по заказу. DEPOSITED, APPROVED, REVERSED, REFUNDED
refundedDate Дата операции возврата по заказу. REFUNDED
reversedDate Дата операции отмены заказа. DEPOSITED, REVERSED, REFUNDED
declineDate Дата отмены заказа. DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
xid Индикатор электронной коммерции транзакции, определяемый продавцом. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
cavv Значение проверки аутентификации владельца карты. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
authValue Значение проверки аутентификации владельца карты. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
sessionExpiredDate Дата и время истечения срока действия заказа. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
tokenizeCryptogram Токенизированная криптограмма. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
creditBankName Название банка, выпустившего карту для зачисления (в P2P). DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
creditPanCountryCode Код страны карты получателя (в P2P). DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
isInternationalP2P Является ли P2P-транзакция межстрановой. DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
recipientData Информация о получателе P2P. DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
transactionTypeIndicator Информация о получателе P2P. Возможные значения:
  • A – Account-to-Account Transfer.
  • P – Person-to-Person Transfer.
  • O - Loan-Prepayment Transfer.
  • D - Funds Disbursement.
  • L - Card Bill Payment.
  • G - Online Gambling Payout.
  • W - Transfer to Own Staged Digital Wallet Account.
  • F - Transfer to Own Stored Digital Wallet Account.
 DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
operationType Тип операции P2P: AFT/OCT. DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
debitBankName Название банка, выпустившего карту для списания (в P2P). DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
debitPanCountryCode Код страны карты для списания (в P2P). DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
p2pDebitRrn RRN (Reference Retrieval Number) операции списания P2P. DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
avsCode Код ответа верификации AVS (проверка адреса и почтового индекса держателя карты). Возможные значения:
  • -1 – почтовый индекс и адрес совпадают.
  • 1 – адрес совпадает, почтовый индекс не совпадает.
  • 2 - почтовый индекс совпадает, адрес не совпадает.
  • 3 - почтовый индекс и адрес не совпадают.
  • 50 - запрошена проверка данных, но результат неуспешен.
  • 51 - некорректный формат запроса AVS/AVV проверки.
 DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT

Примеры кода

Симметричная криптография

Java
package net.payrdr.test;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.util.Comparator;
import java.util.Map;
import java.util.stream.Collector;

public class SymmetricCryptographyExample {

    private static final String secretToken = "ooc7slpvc61k7sf7ma7p4hrefr";
    private static final Map<String, String> callbackParams = Map.of(
            "checksum", "EAF2FB72CAB99FD5067F4BA493DD84F4D79C1589FDE8ED29622F0F07215AA972",
            "mdOrder", "06cf5599-3f17-7c86-bdbc-bd7d00a8b38b",
            "operation", "approved",
            "orderNumber", "2003",
            "status", "1"
    );

    public static void main(String[] args) throws Exception {
        String signedString = callbackParams.entrySet().stream()
                .filter(entry -> !entry.getKey().equals("checksum"))
                .sorted(Map.Entry.comparingByKey(Comparator.naturalOrder()))
                .collect(Collector.of(
                        StringBuilder::new,
                        (accumulator, element) -> accumulator
                                .append(element.getKey()).append(";")
                                .append(element.getValue()).append(";"),
                        StringBuilder::append,
                        StringBuilder::toString
                ));

        byte[] mac = generateHMacSHA256(secretToken.getBytes(), signedString.getBytes());
        String signature = callbackParams.get("checksum");

        boolean verified = verifyMac(signature, mac);
        System.out.println("signature verification result: " + verified);
    }

    private static boolean verifyMac(String signature, byte[] mac) {
        return signature.equals(bytesToHex(mac));
    }

    public static byte[] generateHMacSHA256(byte[] hmacKeyBytes, byte[] dataBytes) throws Exception {
        SecretKeySpec secretKey = new SecretKeySpec(hmacKeyBytes, "HmacSHA256");

        Mac hMacSHA256 = Mac.getInstance("HmacSHA256");
        hMacSHA256.init(secretKey);

        return hMacSHA256.doFinal(dataBytes);
    }

    private static String bytesToHex(byte[] bytes) {
        final byte[] HEX_ARRAY = "0123456789ABCDEF".getBytes(StandardCharsets.US_ASCII);
        byte[] hexChars = new byte[bytes.length * 2];
        for (int j = 0; j < bytes.length; j++) {
            int v = bytes[j] & 0xFF;
            hexChars[j * 2] = HEX_ARRAY[v >>> 4];
            hexChars[j * 2 + 1] = HEX_ARRAY[v & 0x0F];
        }
        return new String(hexChars, StandardCharsets.UTF_8);
    }
}

Асимметричная криптография

Java
package net.payrdr.test;

import java.io.ByteArrayInputStream;
import java.io.InputStream;
import java.security.Signature;
import java.security.cert.CertificateFactory;
import java.security.cert.X509Certificate;
import java.util.Base64;
import java.util.Comparator;
import java.util.Map;
import java.util.stream.Collector;

public class AsymmetricCryptographyExample {

    private static final Map<String, String> callbackParams = Map.of(
            "amount", "35000099",
            "sign_alias", "SHA-256 with RSA",
            "checksum", "163BD9FAE437B5DCDAAC4EB5ECEE5E533DAC7BD2C8947B0719F7A8BD17C101EBDBEACDB295C10BF041E903AF3FF1E6101FF7DB9BD024C6272912D86382090D5A7614E174DC034EBBB541435C80869CEED1F1E1710B71D6EE7F52AE354505A83A1E279FBA02572DC4661C1D75ABF5A7130B70306CAFA69DABC2F6200A698198F8",
            "mdOrder", "12b59da8-f68f-7c8d-12b5-9da8000826ea",
            "operation", "deposited",
            "status", "1");

    private static final String certificate =
            "MIICcTCCAdqgAwIBAgIGAWAnZt3aMA0GCSqGSIb3DQEBCwUAMHwxIDAeBgkqhkiG9w0BCQEWEWt6" +
                    "bnRlc3RAeWFuZGV4LnJ1MQswCQYDVQQGEwJSVTESMBAGA1UECBMJVGF0YXJzdGFuMQ4wDAYDVQQH" +
                    "EwVLYXphbjEMMAoGA1UEChMDUkJTMQswCQYDVQQLEwJRQTEMMAoGA1UEAxMDUkJTMB4XDTE3MTIw" +
                    "NTE2MDEyMFoXDTE4MTIwNTE2MDExOVowfDEgMB4GCSqGSIb3DQEJARYRa3pudGVzdEB5YW5kZXgu" +
                    "cnUxCzAJBgNVBAYTAlJVMRIwEAYDVQQIEwlUYXRhcnN0YW4xDjAMBgNVBAcTBUthemFuMQwwCgYD" +
                    "VQQKEwNSQlMxCzAJBgNVBAsTAlFBMQwwCgYDVQQDEwNSQlMwgZ8wDQYJKoZIhvcNAQEBBQADgY0A" +
                    "MIGJAoGBAJNgxgtWRFe8zhF6FE1C8s1t/dnnC8qzNN+uuUOQ3hBx1CHKQTEtZFTiCbNLMNkgWtJ/" +
                    "CRBBiFXQbyza0/Ks7FRgSD52qFYUV05zRjLLoEyzG6LAfihJwTEPddNxBNvCxqdBeVdDThG81zC0" +
                    "DiAhMeSwvcPCtejaDDSEYcQBLLhDAgMBAAEwDQYJKoZIhvcNAQELBQADgYEAfRP54xwuGLW/Cg08" +
                    "ar6YqhdFNGq5TgXMBvQGQfRvL7W6oH67PcvzgvzN8XCL56dcpB7S8ek6NGYfPQ4K2zhgxhxpFEDH" +
                    "PcgU4vswnhhWbGVMoVgmTA0hEkwq86CA5ZXJkJm6f3E/J6lYoPQaKatKF24706T6iH2htG4Bkjre" +
                    "gUA=";

    public static void main(String[] args) throws Exception {

        String signedString = callbackParams.entrySet().stream()
                .filter(entry -> !entry.getKey().equals("checksum") && !entry.getKey().equals("sign_alias"))
                .sorted(Map.Entry.comparingByKey(Comparator.naturalOrder()))
                .collect(Collector.of(
                        StringBuilder::new,
                        (accumulator, element) -> accumulator
                                .append(element.getKey()).append(";")
                                .append(element.getValue()).append(";"),
                        StringBuilder::append,
                        StringBuilder::toString
                ));

        InputStream publicCertificate = new ByteArrayInputStream(Base64.getDecoder().decode(certificate));
        String signature = callbackParams.get("checksum");

        boolean verified = checkSignature(signedString.getBytes(), signature.getBytes(), publicCertificate);
        System.out.println("signature verification result: " + verified);
    }

    private static boolean checkSignature(byte[] signedString, byte[] signature, InputStream publicCertificate) throws Exception {
        CertificateFactory certFactory = CertificateFactory.getInstance("X.509");
        X509Certificate x509Cert = (X509Certificate) certFactory.generateCertificate(publicCertificate);

        Signature signatureAlgorithm = Signature.getInstance("SHA512withRSA");
        signatureAlgorithm.initVerify(x509Cert.getPublicKey());
        signatureAlgorithm.update(signedString);

        return signatureAlgorithm.verify(decodeHex(new String(signature)));
    }

    private static byte[] decodeHex(String hex) {
        int l = hex.length();
        byte[] data = new byte[l / 2];
        for (int i = 0; i < l; i += 2) {
            data[i / 2] = (byte) ((Character.digit(hex.charAt(i), 16) << 4)
                    + Character.digit(hex.charAt(i + 1), 16));
        }
        return data;
    }
}

Симметричная криптография

PHP
<?php

$data = 'amount;123456;mdOrder;3ff6962a-7dcc-4283-ab50-a6d7dd3386fe;operation;deposited;orderNumber;10747;status;1;';
$key = 'yourSecretToken';
$hmac = hash_hmac ( 'sha256' , $data , $key);

echo "[$hmac]\n";
?>
  1. Присвойте строковое значение переменной data.
  2. Присвойте значение закрытого ключа переменной key.
  3. Функция hash_hmac ( 'sha256', $data, $key) вычисляет контрольную сумму от переданной строки, с помощью закрытого ключа по алгоритму SHA-256.
  4. Сохраните результат работы функции в переменной hmac.
  5. Выведите результат работы функции командой echo.
  6. Сравните это значение с тем, что передано в уведомлении о состоянии заказа.

Асимметричная криптография

PHP
<?php
// data from response
$data = 'amount;35000099;mdOrder;12b59da8-f68f-7c8d-12b5-9da8000826ea;operation;deposited;status;1;';
$checksum = '9524FD765FB1BABFB1F42E4BC6EF5A4B07BAA3F9C809098ACBB462618A9327539F975FEDB4CF6EC1556FF88BA74774342AF4F5B51BA63903BE9647C670EBD962467282955BD1D57B16935C956864526810870CD32967845EBABE1C6565C03F94FF66907CEDB54669A1C74AC1AD6E39B67FA7EF6D305A007A474F03B80FD6C965656BEAA74E09BB1189F4B32E622C903DC52843C454B7ACF76D6F76324C27767DE2FF6E7217716C19C530CA7551DB58268CC815638C30F3BCA3270E1FD44F63C14974B108E65C20638ECE2F2D752F32742FFC5077415102706FA5235D310D4948A780B08D1B75C8983F22F211DFCBF14435F262ADDA6A97BFEB6D332C3D51010B';

// your public key (e.g. SHA-512 with RSA)
// if you have a CERT, please see openssl_get_publickey()
$publicKey = <<<EOD
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwtuGKbQ4WmfdV1gjWWys
5jyHKTWXnxX3zVa5/Cx5aKwJpOsjrXnHh6l8bOPQ6Sgj3iSeKJ9plZ3i7rPjkfmw
qUOJ1eLU5NvGkVjOgyi11aUKgEKwS5Iq5HZvXmPLzu+U22EUCTQwjBqnE/Wf0hnI
wYABDgc0fJeJJAHYHMBcJXTuxF8DmDf4DpbLrQ2bpGaCPKcX+04POS4zVLVCHF6N
6gYtM7U2QXYcTMTGsAvmIqSj1vddGwvNGeeUVoPbo6enMBbvZgjN5p6j3ItTziMb
Vba3m/u7bU1dOG2/79UpGAGR10qEFHiOqS6WpO7CuIR2tL9EznXRc7D9JZKwGfoY
/QIDAQAB
-----END PUBLIC KEY-----
EOD;

$binarySignature = hex2bin(strtolower($checksum));
$isVerify = openssl_verify($data, $binarySignature, $publicKey, OPENSSL_ALGO_SHA512);
if ($isVerify == 1) {
    echo "signature ok\n";
} elseif ($isVerify == 0) {
    echo "bad (there's something wrong)\n";
} else {
    echo "error checking signature\n";
}
?>
Санаттар:
eCommerce API V1
Санаттар
Іздеу нәтижелері
Шарлау
Таңдау
Жабу
Санаттар
Іздеу нәтижелері