REST API сипаттамасы
REST — бұл желі арқылы деректерді тасымалдаудың қарапайым әдісі. Деректер параметрлер жиынтығы бар HTTP-сұрауларыарқылы тасымалданады. Өңделген сұраулар JSON нысандары түрінде қайтарылады (жауап мысалын төменде қараңыз).
{
"errorCode": "12",
"errorMessage": "Empty amount"
}
Сынақ карталар
Сынақ өткізу мақсатында келесі сынақ карталарды пайдалануға болады.
Мерчант аутентификациясы
Төлем шлюзінде мерчант аутентификациясын орындау үшін екі әдісті қолдануға болады.
- Тіркелу кезінде алынған мерчанттың API-пайдаланушысының логин мен құпиясөзін пайдалану (
-api
суффиксі бар тіркелгі). Осы мәндер сәйкесіншеuserName
жәнеpassword
параметрлерінде көрсетіледі (төмендегі кестені қараңыз).
Міндетті | Атау | Түрі | Сипаттама |
---|---|---|---|
Сипаттаманы көру | userName |
String | Сатушының API есептік жазбасының логині. Аутентификация үшін тіркелу кезінде пайдаланушы аты мен құпиясөз орнына токен пайдаланылса (token параметрі), құпиясөзді жіберудің қажеті жоқ. |
Сипаттаманы көру | password |
String | Сатушының API есептік жазбасының құпиясөзі. Аутентификация үшін тіркелу кезінде пайдаланушы аты мен құпиясөз орнына токен пайдаланылса (token параметрі), құпиясөзді жіберудің қажеті жоқ. |
- Арнайы токен арқылы – оның мәнін техникалық қолдау көрсету қызметінде сұрауға болады. Сұрауларда оның мәні
token
параметрі арқылы беріледі (төмендегі кестені қараңыз).
Міндетті | Атау | Түрі | Сипаттама |
---|---|---|---|
Сипаттаманы көру | token |
String | Төлем шлюзіне сұрауларды жіберген кезде сатушы аутентификациясы үшін пайдаланылатын мән. Осы параметрді көрсетсеңіз, userName және password көрсетілмеуі керек. |
REST протоколы арқылы, application/x-www-form-urlencoded
түріндегі сұрауларды жіберу (multipart/form-data
түрінде жібермеу).
Қосылым координаттары
Сұраулар келесі талаптарға сәйкес болуы керек:
- барлық мәтіндік өрістер Юникод (UTF-8) арқылы берілуі керек;
- арнайы таңбалар URL кодына сәйкес экрандалуы керек, мысалы,
qwe?rt%y
құпиясөзіqwe%0Frt%25y
түрінде көрсетілуі тиіс.
Төмендегі кестеде 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 сұрауын орындау төлем шлюзінің сатушы консоліндегі қатеге себеп болады. Төлем шлюзінің сатушы консоліндегі сеансты қалпына келтіру үшін мына қадамдарды орындау керек:
- сатушы консолінен шығып, қайта кіріңіз;
- мәселе шешілмесе, cookie файлдарын жойып, жүйеге қайта кіріңіз.
Қатенің пайда болуын алдын алу үшін төмендегі әдістердің бірін орындауға болады:
- REST-сұраулары үшін жасырын режимді пайдаланып, сатушы консолінде қалыпты режимде жұмыс істеу;
- REST-сұрауларын жіберу және сатушы консоліне кіру үшін әртүрлі браузерлерді пайдалану.
Интеграция үлгісі
Төлем шлюзінің төлем бетіндегі карта деректерін енгізу арқылы төлем жасау
№ | Бір кезеңді төлем | Екі кезеңді төлем |
---|---|---|
1 | Сатып алушы тауарлар мен қызметтерді таңдап, төлем әдісі ретінде төлем картасын пайдаланады. | Сатып алушы тауарлар мен қызметтерді таңдап, төлем әдісі ретінде төлем картасын пайдаланады. |
2 | Мерчант төлем шлюзіне тапсырысты тіркеу сұрауын жібереді: register.do. Басқа параметрлерге қоса, мына параметрлер көрсетіледі:
|
Мерчант авторизациядан бұрын төлем шлюзіне тапсырысты тіркеу сұрауын жібереді: registerPreAuth.do. Басқа параметрлерге қоса, мына параметрлер көрсетіледі:
|
3 | Басқа параметрлерге қоса, төлем шлюзі мына параметрлерді қайтарады:
|
Басқа параметрлерге қоса, төлем шлюзі мына параметрлерді қайтарады:
|
4 | Сатушы пайдаланушыны formUrl жауап параметрінде көрсетілген мекенжай бойынша өткізеді. |
Сатушы клиентті formUrl сұрау параметрінде көрсетілген мекенжай бойынша өткізеді. |
5 | Клиентке төлем картасының деректерін енгізу пішіні көрсетіледі. Клиент алған пішінді толтырып, деректерді төлем шлюзінің серверіне жібереді. | 5 |
6 | Кейінгі әрекеттер клиенттің картасында 3-D Secure протоколының бар-жоғына байланысты болады:
|
Кейінгі әрекеттер клиенттің картасында 3-D Secure протоколының бар-жоғына байланысты болады:
|
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-сұратымдарының топтамасын жүктеп алуыңызға болады.
Тапсырысты тіркеу
Тапсырысты тіркеу үшін 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 параметрі көрсетілуі керек.Әдепкі бойынша банк процессингіне мына параметрлер жіберіледі:
Егер merchantOrderId көрсетілсе, оның мәні банк процессингіне тапсырыс нөмірі ретінде жіберіледі (orderNumber параметрінің орнына). |
Жоқ | sessionTimeoutSecs |
Integer | Тапсырыстың секундпен берілген мерзімі. Параметр көрсетілмесе, мерчант параметрлерде көрсеткен мән немесе әдепкі уақыт (1200 секунд = 20 минут) пайдаланылады. Сұрауда expirationDate параметрі бар болса, sessionTimeoutSecs параметрінің мәні ескерілмейді. |
Жоқ | expirationDate |
String | Тапсырыс мерзімінің аяқталу күні және уақыты. Формат: yyyy-MM-ddTHH:mm:ss .Осы параметр сұрауда берілмеген жағдайда, тапсырыс мерзімінің аяқталу күнін анықтау үшін sessionTimeoutSecs параметрі пайдаланылады. |
Жоқ | bindingId |
String | Бұрын жасалған байламның идентификаторы. Оны тек мерчанттың байламдармен жұмыс істеуге рұқсаты бар болған жағдайда ғана пайдалануға болады. |
Жоқ | features |
String | Төменде рұқсат етілетін мәндер көрсетілген.
|
Жоқ | phone |
Integer | Сатып алушының телефон нөмірі. Ел кодын әрқашан көрсету керек, осында + белгісін көрсетуге не көрсетпеуге болады. Осылайша, келесі нұсқалар қолжетімді болады:
|
Жоқ | 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 параметрі көрсетілуі керек.Әдепкі бойынша банк процессингіне мына параметрлер жіберіледі:
Егер merchantOrderId көрсетілсе, оның мәні банк процессингіне тапсырыс нөмірі ретінде жіберіледі (orderNumber параметрінің орнына). |
Жоқ | sessionTimeoutSecs |
Integer | Тапсырыстың секундпен берілген мерзімі. Параметр көрсетілмесе, мерчант параметрлерде көрсеткен мән немесе әдепкі уақыт (1200 секунд = 20 минут) пайдаланылады. Сұрауда expirationDate параметрі бар болса, sessionTimeoutSecs параметрінің мәні ескерілмейді. |
Жоқ | expirationDate |
String | Тапсырыс мерзімінің аяқталу күні және уақыты. Формат: yyyy-MM-ddTHH:mm:ss .Осы параметр сұрауда берілмеген жағдайда, тапсырыс мерзімінің аяқталу күнін анықтау үшін sessionTimeoutSecs параметрі пайдаланылады. |
Жоқ | bindingId |
String | Бұрын жасалған байламның идентификаторы. Оны тек мерчанттың байламдармен жұмыс істеуге рұқсаты бар болған жағдайда ғана пайдалануға болады. |
Жоқ | features |
String | Төменде рұқсат етілетін мәндер көрсетілген.
|
Жоқ | autocompletionDate |
String | Дата и время автоматического завершения двухстадийного платежа в следующем формате: 2017-12-29T13:02:51. Используемый часовой пояс: UTC+3. Чтобы включить отправку этого поля в процессинговую систему, обратитесь в службу технической поддержки. |
Жоқ | email |
String | Клиенттің электрондық пошта мекенжайы. |
Жоқ | phone |
Integer | Сатып алушының телефон нөмірі. Ел кодын әрқашан көрсету керек, осында + белгісін көрсетуге не көрсетпеуге болады. Осылайша, келесі нұсқалар қолжетімді болады:
|
Сипаттаманы көру | 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 | Осы параметрдің мәні төлем шлюзіндегі тапсырыстың күйін көрсетеді. Тапсырыс табылмаған кезде болмайды. Төменде қолжетімді параметрлер тізімі берілген:
|
Барлық нұсқалар. | Иә | 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 верификациясының жауап коды (карта иесінің мекенжайын және пошта индексін тексеру). Ықтимал мәндері:
|
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 | Банк сатып алушыға қаражатты мәжбүрлі түрде қайтарды ма. Ықтимал мәндері:
|
08 және одан жоғары. | Иә | paymentSystem |
String | Төлем жүйесінің атауы. Келесі мәндер көрсетілуі мүмкін:
|
08 және одан жоғары. | Иә | product |
String | Корпоративті карталар туралы қосымша мәліметтер. Осы мәліметтерді техникалық қолдау көрсету қызметі толтырады. Осындай мәліметтер болмаса, бос мән қайтарылады. |
secureAuthInfo
элементі cavv
және xid
параметрлерінің тізімі болып табылатын eci
және threeDSInfo
элементтерінен тұрады.
Нұсқа | Атау | Түрі | Міндетті | Сипаттама |
---|---|---|---|---|
Барлық нұсқалар. | Жоқ | eci |
Integer | Электрондық коммерциялық көрсеткіш. Тапсырыс бойынша төлем жасалғаннан кейін және тиісті рұқсаттар болған жағдайда ғана көрсетіледі. Төменде ECI-кодтарының түсіндірмесі берілген.
|
Барлық нұсқалар. | Жоқ | 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 | Тапсырыс күйі, параметр мына мәндерде болуы мүмкін:
|
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": "<Unknown>"
}
}
Байламдар арқылы төлеу
Сұрау параметрлері
Міндетті | Атау | Түрі | Сипаттама |
---|---|---|---|
Иә | 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"
}
]
}
Тапсырыс үшін төлеу сұрауы, карта деректері мерчант (ішкі MPI) тарапынан жиналады
Төлем жасау үшін 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 | Рұқсат етілетін мәндер:
|
Жоқ | jsonParams |
String | Мерчанттың қосымша параметрлерін көрсету бөлімі. Кейін сақтауға арналған қосымша ақпарат өрістері.{name1:value1,…,nameN:valueN} Осы өрістер кейін банк реестрінде көрсету үшін банк процессингіне жіберілуі мүмкін. Осы функцияны қосу үшін банкіңізге хабарласыңыз. Мерчант үшін сатып алушылар туралы хабарландырулар орнатылған болса, осы бөлімде сатушының электрондық пошта мекенжайы бар email параметрі көрсетілуі керек.Әдепкі бойынша банк процессингіне мына параметрлер жіберіледі:
Егер 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 қосу керек, осында:
Бұл 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``).Осында төлем шлюзі қатені қайтармайды. |
Тапсырыс үшін төлеу сұрауы, карта деректері мерчант (сыртқы MPI) тарапынан жиналады
Сұрау параметрлері
Міндетті | Атау | Түрі | Сипаттама |
---|---|---|---|
Иә | 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 | Рұқсат етілетін мәндер:
|
Жоқ | jsonParams |
Alphanumeric | Кейін сақтауға арналған қосымша ақпарат өрістері келесі түрде көрсетіледі: {"param":"value","param2":"value2"} .Осы өрістер кейін банк реестрінде көрсету үшін банк процессингіне жіберілуі мүмкін. Әдепкі бойынша orderNumber (тапсырыс нөмірі) және description (тапсырыс сипаттамасы) көрсетіледі.description 99 таңбадан аспауы керек және мына таңбалар пайдаланылмауы тиіс:% ,+ , күймешені қайтару \r және жолды түсіру \n ).Осы функцияны қосу үшін банкіңізге хабарласыңыз. Сыртқы MPI пайдаланылса, төлем шлюзі әр 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 | Алдын ала авторизациялау (клиент шотындағы қаражатты шешілгенше бұғаттау) қажеттілігін анықтайтын параметр. Келесі мәндер қолжетімді:
|
Иә | paymentToken |
String |
paymentToken параметрінде шифры ашылған және Base64 модулінде кодталған Apple Pay жүйесіндегі PKPaymentToken Object нысанынан алынған paymentData сипат мәні бар болуы керек (толық ақпаратты Apple Pay құжаттамасынан қараңыз). Осылайша, төлем шлюзіне төлем жасау сұрауын жіберу үшін сатушы:
|
Жауап параметрлері
Міндетті | Атау | Түрі | Сипаттама |
---|---|---|---|
Иә | success |
String | Сұраудың сәтті өңделгенін көрсетеді. Келесі мәндер қолжетімді:
|
Сипаттаманы көру | 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 | Осы параметрдің мәні төлем шлюзіндегі тапсырыстың күйін көрсетеді. Тапсырыс табылмаған кезде болмайды. Төменде қолжетімді параметрлер тізімі берілген:
|
Жоқ | 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 | Тапсырыс күйі, параметр мына мәндерде болуы мүмкін:
|
Иә | 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 | Алдын ала авторизациялау (клиент шотындағы қаражатты шешілгенше бұғаттау) қажеттілігін анықтайтын параметр. Келесі мәндер қолжетімді:
-
true
- екі кезеңді төлем жасау мүмкіндігі қосылған; -
false
- бір кезеңді төлем жасау мүмкіндігі қосылған (қаражат бірден шешіледі).
Жоқ
| 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 | Сатып алушының телефон нөмірі. Ел кодын әрқашан көрсету керек, осында +
белгісін көрсетуге не көрсетпеуге болады. Осылайша, келесі нұсқалар қолжетімді болады:
-
+79998887766
; -
79998887766
. Цифрлардың рұқсат етілген саны: 7-15 аралығында.
Иә
| 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 | Сұраудың сәтті өңделгенін көрсетеді. Келесі мәндер қолжетімді:
|
Сипаттаманы көру | 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&orderId=61c33664-85a0-7d6b-af26-09ee009c4000&lang=en
), идентифицирует перенаправляемого из шлюза держателя карты посде попытки оплаты, вы можете проверить статус заказа с помощью API-запроса getOrderStatusExtended
.
Этот вариант является самым простым, но он не совсем надежен, поскольку перенаправление держателя карты может завершиться ошибкой (например, в результате обрыва соединения или закрытия браузера держателем карты), а returnUrl
может не получить триггер для вызова getOrderStatusExtended
.
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": "<Unknown>"
}
}
Использовать подписанный 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 |
Тип события, вызвавшего уведомление:
|
status |
Индикатор успешности операции, указанной в параметре operation :
|
Пользовательские заголовки 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
Алгоритм обработки уведомлений о состоянии заказов
В разделах ниже представлен алгоритм обработки уведомлений о состоянии заказов в зависимости от типа таких уведомлений.
Уведомление без контрольной суммы
- Платежный шлюз отправляет на сервер продавца следующий запрос.
https://mybestmerchantreturnurl.com/callback/?mdOrder=1234567890-098776-234-522&orderNumber=0987&operation=deposited&status=0
- Сервер продавца возвращает HTTP-сообщение
200 OK
платежному шлюзу.
Уведомление с контрольной суммой
-
Платежный шлюз отправляет HTTPS-запрос следующего вида на сервер мерчанта, при этом:
- при использовании симметричной криптографии контрольная сумма формируется с помощью ключа, общего для платежного шлюза и продавца;
- при использовании асимметричной криптографии контрольная сумма формируется с помощью закрытого ключа, известного только платежному шлюзу.
https://mybestmerchantreturnurl.com/path?amount=123456&orderNumber=10747&checksum=DBBE9E54D42072D8CAF32C7F660DEB82086A25C14FD813888E231A99E1220AB3&mdOrder=3ff6962a-7dcc-4283-ab50-a6d7dd3386fe&operation=deposited&status=1
Порядок параметров в уведомлении может быть произвольным.
На стороне продавца из строки параметров уведомления удаляются параметры
checksum
иsign_alias
, а значение параметраchecksum
(контрольная сумма) сохраняется для проверки подлинности уведомления;Оставшиеся параметры и их значения используются для создания следующей строки.
имя_параметра1;значение_параметра1;имя_параметра2;значение_параметра2;…;имя_параметраN;значение_параметраN;
В этом случае парыимя_параметра;значение_параметра
должны быть отсортированы в прямом алфавитном порядке (по возрастанию) по именам параметров.
Пример сгенерированной строки параметров:amount;123456;mdOrder;3ff6962a-7dcc-4283-ab50-a6d7dd3386fe;operation;deposited;orderNumber;10747;status;1;
-
Контрольная сумма рассчитывается на стороне мерчанта, способ расчета зависит от способа ее формирования:
- при использовании симметричной криптографии - с помощью алгоритма HMAC-SHA256 и общего с платежным шлюзом закрытого ключа;
- при использовании асимметричной криптографии - с помощью алгоритма хеширования, который зависит от способа создания ключевой пары, и открытого ключа, который связан с закрытым ключом, находящимся на стороне платежного шлюза.
В получившейся строке контрольной суммы все буквы нижнего регистра заменяются на буквы верхнего регистра.
Происходит сравнение полученного значения с контрольной суммой, извлеченной ранее из параметра
checksum
.Если контрольные суммы совпадают, сервер отправляет в платежный шлюз HTTP-код
200 OK
.
Если контрольные суммы совпадают, это уведомление подлинно и было отправлено платежным шлюзом. В противном случае вероятно, что злоумышленник пытается выдать свое уведомление за уведомление платежного шлюза.
Уведомление о статусе платежа
Для того, чтобы определить, прошел ли платеж успешно или нет, вам необходимо:
- Проверить подпись (параметр
checksum
в уведомлении); - Проверять два параметра уведомления обратного вызова:
operation
иstatus
.
Если значение параметра operation
отличается от approved
или deposited
, то уведомление обратного вызова относится к статусу оплаты.
- Approved Successfully → operation = approved & status = 1 (Successful Operation)
- Approval was Declined → operation = approved & status = 0 (Failed Operation)
- Deposited Successfully → operation = deposited & status = 1 (Successful Operation)
- Deposit was Declined → operation = deposited & status = 0 (Failed Operation)
Неуспешные уведомления
Если в платежный шлюз возвращается ответ, отличный от HTTP-кода 200 OK
, отправка уведомления считается неуспешной. В этом случае платежный шлюз повторяет уведомление с интервалом в 30 секунд до тех пор, пока не будет выполнено одно из следующих условий:
- платежный шлюз получает
200 OK
или - происходит три неуспешных попытки информирования подряд.
При достижении одного из указанных выше условий попытки отправки 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 |
Флаг, указывающий тип операции.
|
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. Возможные значения:
|
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 (проверка адреса и почтового индекса держателя карты). Возможные значения:
|
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";
?>
- Присвойте строковое значение переменной
data
. - Присвойте значение закрытого ключа переменной
key
. - Функция
hash_hmac
( 'sha256', $data, $key) вычисляет контрольную сумму от переданной строки, с помощью закрытого ключа по алгоритму SHA-256. - Сохраните результат работы функции в переменной
hmac
. - Выведите результат работы функции командой
echo
. - Сравните это значение с тем, что передано в уведомлении о состоянии заказа.
Асимметричная криптография
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";
}
?>