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

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

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

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

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

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

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

• Тіркелу кезінде алынған мерчанттың API-пайдаланушысының логин мен құпиясөзін пайдалану (-api суффиксі бар тіркелгі). Осы мәндер сәйкесінше userName және password параметрлерінде көрсетіледі (төмендегі кестені қараңыз).

• Арнайы токен арқылы – оның мәнін техникалық қолдау көрсету қызметінде сұрауға болады. Сұрауларда оның мәні token параметрі арқылы беріледі (төмендегі кестені қараңыз).

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

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

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

• барлық мәтіндік өрістер Юникод (UTF-8) арқылы берілуі керек;
• арнайы таңбалар URL кодына сәйкес экрандалуы керек, мысалы, qwe?rt%y құпиясөзі qwe%0Frt%25y түрінде көрсетілуі тиіс.

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

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

• сатушы консолінен шығып, қайта кіріңіз;
• мәселе шешілмесе, cookie файлдарын жойып, жүйеге қайта кіріңіз.

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

• REST-сұраулары үшін жасырын режимді пайдаланып, сатушы консолінде қалыпты режимде жұмыс істеу;
• REST-сұрауларын жіберу және сатушы консоліне кіру үшін әртүрлі браузерлерді пайдалану.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Қателер коды

Мысалдар

Сұрау мысалы

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 әдісі пайдаланылады.

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

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

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

Қателер коды

Мысалдар

Сұрау мысалы

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 сұрауы пайдаланылады.

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

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

Қателер коды

Мысалдар

Сұрау мысалы

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 сұрауы пайдаланылады.

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

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

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

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

Қателер коды

Мысалдар

Сұрау мысалы

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"
}

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

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

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

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

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

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

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

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

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

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

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

Қателер коды

Мысалдар

Сұрау мысалы

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

Жауап мысалы

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

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

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

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

Қателер коды

Мысалдар

Сұрау мысалы

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"
}

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

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

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

Қателер коды

Мысалдар

Сұрау мысалы

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

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

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

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

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

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

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

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

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

Мысалдар

Сұрау мысалы

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 серверіне қайта бағытталуы керек. Қайта бағыттаудың екі жолы бар: қалыпты және жеңілдетілген (төмендегі кестені қараңыз).

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

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

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

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

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

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

Мысалдар

Сұрау мысалы

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 тапсырысын тіркеу

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

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

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

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

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

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

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

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

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

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

Қателер коды

Мысалдар

Сұрау мысалы

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 сұрауы пайдаланылады.

Иә

| 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/». |

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

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

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

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

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

Қателер коды

Мысалдар

Сұрау мысалы

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
}

• симметриялы криптография арқылы – шлюз тарапынан бақылау сомасын құру және сатушы тарапынан тексеру үшін бір (симметриялы) криптографиялық кілт пайдаланылады;
• Асимметриялы криптография арқылы - төлем шлюзі тарапынан бақылау сомасын құру үшін тек шлюзге белгілі жабық кілт пайдаланылады, ал бақылау сомасын растау үшін сатушыларға белгілі және еркін таратуға болатын жабық кілтпен байланысты ашық кілт пайдаланылады.

• Thawte Consulting cc – https://www.thawte.com/;
• VeriSign – https://www.verisign.com/;
• DigiCert Inc – https://www.digicert.com/;
• COMODO CA Limited – https://www.comodo.com/;
• GeoTrust Inc. – https://www.geotrust.com/;
• GlobalSign – https://www.globalsign.com/;
• Trustis Limited – http://www.trustis.com/;
• UniTrust – http://www.unitrust.co.uk/.

• RU-CENTER – http://ssl.ru/;
• REG.RU – https://www.reg.ru/ssl-certificate/;
• MySSL – https://myssl.ru/.

• ``approved`` - сатып алушының шотындағы қаражатты ұстап қалу;
• ``deposited`` - аяқтау операциясы;
• ``reversed`` - бас тарту операциясы;
• ``refunded`` - қайтару операциясы.

• ``1`` - операция сәтті аяқталды;
• ``0`` - операция қатемен аяқталды.
| ## Мысалдар ### Бақылау сомасы жоқ хабарландырудың URL-мекенжайының мысалы ```shell https://myshop.ru/callback/?mdOrder=1234567890-098776-234-522&orderNumber=0987&operation=deposited&status=0 ``` ### Бақылау сомасы бар хабарландырудың URL-мекенжайының мысалы ```shell https://myshop.ru/callback/?mdOrder=1234567890-098776-234-522&orderNumber=0987&checksum=DBBE9E54D42072D8CAF32C7F660DEB82086A25C14FD813888E231A99E1220AB3&operation=deposited&status=0 ``` ## Тапсырыс күйі туралы хабарландыруларды өңдеу алгоритмі Төмендегі бөлімдерде хабарландырулардың түріне байланысты тапсырыстардың күйі туралы хабарландыруларды өңдеу алгоритмі ұсынылған. ### Бақылау сомасы жоқ хабарландыру 1. Төлем шлюзі сатушының серверіне келесі сұрауды жібереді:
``https://myshop.ru/callback/?mdOrder=1234567890-098776-234-522&orderNumber=0987&operation=deposited&status=0`` 1. Сервер төлем шлюзіне ``200 OK`` HTTP-кодын жібереді. ### Бақылау сомасы бар хабарландыру 1. Төлем шлюзі мерчант серверіне келесі түрдегі HTTP-сұрауын жібереді, осында: * симметриялы криптографияны пайдаланған кезде бақылау сомасы төлем шлюзі мен сатушы үшін ортақ болып табылатын кілт арқылы құрылады; асимметриялы криптографияны пайдаланған кезде бақылау сомасы тек төлем шлюзіне белгілі жабық кілт арқылы құрылады.
``http://site.ru/path?amount=123456&orderNumber=10747&checksum=DBBE9E54D42072D8CAF32C7F660DEB82086A25C14FD813888E231A99E1220AB3&mdOrder=3ff6962a-7dcc-4283-ab50-a6d7dd3386fe&operation=deposited&status=1``
Хабарландырудағы параметрлердің реті еркін болуы мүмкін. 1. Сатушы тарапынан хабарландырудың параметрлер жолағынан ``checksum`` параметрі жойылады, ал бұл параметрдің мәні (бақылау сомасы) хабарландырудың түпнұсқалығын тексеру үшін сақталады. 1. Қалған параметрлер мен олардың мәндерінен келесі түрдегі жол құралады.
``parameter_name1;paramenter_value1;parameter_name2;paramenter_value2;…;parameter_nameN;paramenter_valueN;``
Осында ``name_parameter;value_parameter`` жұптары параметрлердің атаулары бойынша әліпби ретімен (өсуі бойынша) сұрыпталуы керек.
Параметрлердің құралған жолының мысалы төменде көрсетілген.
``amount;123456;mdOrder;3ff6962a-7dcc-4283-ab50-a6d7dd3386fe;operation;deposited;orderNumber;10747;status;1;`` 1. Бақылау сомасы мерчант тарапынан есептеліп, есептеу әдісі оның құрылу жолына байланысты болады: * симметриялы криптографияны пайдаланған кезде – HMAC-SHA256 алгоритмі мен төлем шлюзі мен ортақ жабық кілт арқылы; * асимметриялы криптографияны пайдаланған кезде – кілт жұптарының жасалу әдісіне байланысты хэштеу алгоритмі мен төлем шлюзі тарапында орналасқан жабық кілтпен байланысты ашық кілт арқылы. 1. Бақылау сомасының пайда болған жолағында төменгі регистрмен берілген барлық әріптер жоғарғы регистрдегі әріптерге ауыстырылады. 1. Есептелген мән осыдан бұрын ``checksum`` параметрінен алынған бақылау сомасымен салыстырылады. 1. Бақылау сомалары сәйкес келген жағдайда, сервер төлем шлюзіне ``200 OK`` HTTP-кодын жібереді. Бақылау сомалары сәйкес келген жағдайда, бұл осы хабарландырудың түпнұсқа екенін және төлем шлюзінен жіберілгенін білдіреді. Сәйкес келмеген жағдайда, бұл қаскүнемдердің осы хабарландыруды төлем шлюзінің хабарландыруы ретінде көрсеткісі келгенін білдіреді. ## Сәтсіз аяқталған хабарландырулар Төлем шлюзіне ``200 OK`` HTTP-кодынан өзгеше жауап қайтарылатын болса, бұл хабарландырудың сәтсіз аяқталғанын білдіреді. Осы жағдайда төлем шлюзі хабарландыруды төмендегі шарттардың бірі орындалмағанша ``10*A`` минут сайын жіберіп тұрады (осында ``A`` — бұл әрекеттің реттік нөмірі, мысалы, хабарландыруды жіберудің екінші әрекетінен кейін жіберу аралығы 20 минут болады, үшінші әрекеттен кейін — 30 минут болады және т.с.с.): * төлем шлюзі келесі мәнді алады: 200 OK НЕМЕСЕ * мәліметтерді жіберудің қатарынан алты сәтсіз әрекеті орындалды. Callback-хабарландыруларын жіберудің жоғарыда көрсетілген шарттарының бірі орындалған кезде, операциялар аяқталады. ## Код мысалдары ### Cимметриялы криптография #### 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);
    }
}

### Acимметриялы криптография #### 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 ``` 1. Жолды ``data`` айнымалысына теріңіз. 1. ``key`` айнымалысына жабық кілтті теріңіз. 1. ``hash_hmac`` ( 'sha256', $data, $key) функциясы SHA-256 алгоритмі бойынша жабық кілт арқылы берілген жолдан бақылау сомасын есептейді. 1. Функция жұмысының нәтижесін ``hmac`` айнымалысында сақтаңыз. 1. Функция жұмысының нәтижесін ``echo`` пәрмені арқылы шығарып алыңыз. 1. Осы мәнді алынған тапсырыстың күйі туралы хабарландыруда көрсетілген мәнмен салыстырыңыз. ### Асимметриялы криптография #### PHP ```php ```