Связки и типы транзакций
В этом разделе описываются поддерживаемые типы транзакций по связкам.
Типы связок
Платежный шлюз позволяет создавать и использовать три типа связок:
- Обычная – для платежей, не связанных ни с каким планом или графиком. Например, когда покупатель делает новый заказ и оплачивает его, используя ранее сохраненные данные карты.
- Рекуррентная – для платежей, происходящих по фиксированному графику. Например, ежемесячные платежи за коммунальные услуги.
- Рассрочка – при оплате в рассрочку, когда клиент оплачивает счет небольшими частями в течение фиксированного периода времени в соответствии с планом платежей.
Одна карта может иметь связки разных типов. Более того, у карты может несколько связок для разных рассрочек.
Тип транзакций
Транзакции по связкам принадлежат к одной из двух групп в зависимости от инициатора транзакции:
-
CIT (cardholder-initiated transactions) – транзакции электронной коммерции, в которых держатель карты принимает участие в платеже.Эта группа включает 4 вида транзакций:
- C/CI – инициирующая транзакция с сохранением обычной связки для дальнейших платежей.
- RI – инициирующая транзакция с сохранением связки для рекуррентных платежей.
- II – инициирующая транзакция с сохранением связки для платежей в рассрочку.
- F – внеплановая транзакция, совершаемая держателем карты, с использованием обычной связки.
-
MIT (Merchant-initiated Transactions) – транзакции электронной коммерции, совершаемые продавцом без участия держателя карты. В эту группу входят 3 типа транзакций:
- U – внеплановая транзакция с использованием обычной связки. Например, начисление пени. Обратите внимание, что для такой операции нет CVC или 3DS-верификации, так как владелец карты не принимает в ней участия и не может вводить какие-либо данные.
- R – последующая рекуррентная транзакция с использованием рекуррентной связки.
- I – последующая транзакция в рассрочку с использованием связки для рассрочки.
Тип транзакции должен передаваться в параметре tii
платежных API-запросов. Подробнее о значениях параметра tii
читайте здесь.
Управление связками через API
Ниже приведены примеры создания и использования разных типов связок через API:
Обычные связки
Создание обычной связки
Чтобы создать обычную связку, выполните следующую последовательность запросов:
- Выполните запрос register.do с параметром
clientId
→ получите в ответorderId
. - Передайте полученное значение
orderId
в параметреMDORDER
запроса paymentorder.do.
В результате будет создана связка для клиента с изначально указанным clientId
. Вы можете выполнить запрос getBindigs.do, чтобы убедиться, что связка создана.
Пример запроса paymentorder.do
:
curl --request POST \
--url https://3dsec.berekebank.kz/payment/rest/paymentorder.do \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data '$CVC=123' \
--data '$EXPIRY=203012' \
--data '$PAN=4000001111111118' \
--data 'TEXT=TEST CARDHOLDER' \
--data MDORDER=59e00106-1f69-76a7-b893-b27c00b4f820 \
--data userName=test_user \
--data password=test_user_password
{
"redirect": "https://3dsec.berekebank.kz/payment/merchants/pay/finish.html?orderId=59e00106-1f69-76a7-b893-b27c00b4f820&lang=en",
"info": "Your order is proceeded, redirecting...",
"errorCode": 0
}
Оплата обычной cвязкой
Для оплаты заказа обычной связкой используйте следующую последовательность запросов:
- Выполните запрос register.do с параметром
clientId
→ получите в ответorderId
. - Получите список cвязок с помощью запроса getBindigs.do с тем же значением
clientId
и cbindingType=C
→ получите в ответеbindingId
. - Выполните запрос paymentOrderBinding.do. Передайте значение
orderId
(полученное на Шаге 1) в параметреmdOrder
, а также передайте полученныйbindingId
. Доступные значенияtii
:F
,U
.
В результате заказ будет оплачен с помощью связки с указанным bindingId
.
Пример запроса paymentOrderBinding.do
:
curl --request POST \
--url https://3dsec.berekebank.kz/payment/rest/paymentOrderBinding.do \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data mdOrder=24c3d392-4c60-7f0b-9ff5-b00100b4f820 \
--data ip=127.0.0.1 \
--data cvc=123 \
--data bindingId=b83317e0-1679-7d85-b375-a63200b4f820 \
--data userName=test_user \
--data password=test_user_password \
--data language=en \
--data tii=F
{
"redirect": "https://3dsec.berekebank.kz/payment/merchants/pay/finish.html?orderId=24c3d392-4c60-7f0b-9ff5-b00100b4f820&lang=en",
"info": "Your order is proceeded, redirecting...",
"errorCode": 0
}
Рекуррентные связки
Создание рекуррентной связки
Чтобы создать рекуррентную связку, выполните следующую последовательность запросов:
- Выполните запрос register.do с параметром
clientId
→ получите в ответorderId
. - Передайте полученное значение
orderId
в параметреMDORDER
запроса paymentorder.do. Необходимо передать дополнительные параметрыrecurringFrequency
иrecurringExpiry
(верификация не проводится, но эта информация используется банком, выпустившим карту).
В результате будет создана связка для клиента с изначально указанным clientId
. Вы можете выполнить запрос getBindigs.do, чтобы убедиться, что связка создана.
Пример запроса paymentorder.do
:
curl --request POST \
--url https://3dsec.berekebank.kz/payment/rest/paymentorder.do \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data '$CVC=123' \
--data '$EXPIRY=203012' \
--data '$PAN=4000001111111118' \
--data 'TEXT=TEST CARDHOLDER' \
--data MDORDER=59e00106-1f69-76a7-b893-b27c00b4f820 \
--data userName=test_user \
--data password=test_user_password \
--data language=en \
--data 'jsonParams={"recurringFrequency": "1", "recurringExpiry":"20261231"}'
{
"errorCode": 0,
"is3DSVer2": true,
"threeDSServerTransId": "efa8e3ce-a4a6-49f8-b422-df781de18119",
"threeDSMethodURLServer": "https://3dsec.berekebank.kz/payment/client/gather?threeDSServerTransID=efa8e3ce-a4a6-49f8-b422-df781de18119"
}
Оплата рекуррентной cвязкой
Для оплаты заказа рекуррентной связкой используйте следующую последовательность запросов:
- Получите список связок, используя запрос getBindigs.do с
bindingType=R
→ получите в ответеbindingId
. - Выполните запрос recurrentPayment.do с полученным
bindingId
.
В результате заказ будет оплачен с помощью связки с указанным bindingId
.
Пример запроса recurrentPayment.do
:
curl --request POST \
--url https://3dsec.berekebank.kz/payment/recurrentPayment.do \
--header 'Content-Type: application/json' \
--data '{
"userName": "test_user",
"password": "test_user_password",
"orderNumber": "UAF-203974-DE-12",
"language": "EN",
"bindingId": "3080a436-02a0-75c2-a2ce-41be00b40dc0",
"amount": 12300,
"currency": "398",
"description" : "Test description",
"additionalParameters": {
"firstParamName": "firstParamValue",
"secondParamName": "secondParamValue"
}
}'
{
"success": true,
"data": {
"orderId": "9adaa8f0-3b5a-742f-80b4-172200b40dc0"
},
"orderStatus": {
"errorCode": "0",
"orderNumber": "9003",
"orderStatus": 2,
"actionCode": 0,
"actionCodeDescription": "",
"amount": 12300,
"currency": "398",
"date": 1618338779501,
"orderDescription": "Test description",
"merchantOrderParams": [
{
"name": "firstParamName",
"value": "firstParamValue"
},
{
"name": "secondParamName",
"value": "secondParamValue"
}
],
"transactionAttributes": [],
"attributes": [
{
"name": "mdOrder",
"value": "9adaa8f0-3b5a-742f-80b4-172200b40dc0"
}
],
"cardAuthInfo": {
"maskedPan": "400000**1118",
"expiration": "202612",
"cardholderName": "TEST CARDHOLDER",
"approvalCode": "123456",
"paymentSystem": "VISA",
"product": "visa-product",
"secureAuthInfo": {
"eci": 7
},
"pan": "400000**1118"
},
"bindingInfo": {
"clientId": "test-client",
"bindingId": "3080a436-02a0-75c2-a2ce-41be00b40dc0"
},
"authDateTime": 1618338779790,
"authRefNum": "111111111111",
"paymentAmountInfo": {
"paymentState": "DEPOSITED",
"approvedAmount": 12300,
"depositedAmount": 12300,
"refundedAmount": 0,
"totalAmount": 12300
},
"bankInfo": {
"bankName": "ES TEST BANK",
"bankCountryCode": "ES",
"bankCountryName": "Spain"
},
"chargeback": false,
"operations": [
{
"amount": 12300,
"cardHolder": "TEST CARDHOLDER",
"authCode": "123456"
}
]
}
}
Связки для рассрочки
Создание связки для оплаты в рассрочку
Чтобы создать связку для рассрочки, выполните следующую последовательность запросов:
- Выполните запрос register.do с параметром
clientId
→ получите в ответorderId
. - Передайте полученное значение
orderId
в параметреMDORDER
запроса paymentorder.do. Необходимо передать дополнительные параметрыinstallments
,totalInstallmentAmount
,recurringFrequency
иrecurringExpiry
.
В результате будет создана связка для клиента с изначально указанным clientId
. Вы можете выполнить запрос getBindigs.do, чтобы убедиться, что связка создана.
Пример запроса paymentorder.do
:
curl --request POST \
--url https://3dsec.berekebank.kz/payment/rest/paymentorder.do \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data '$CVC=123' \
--data '$EXPIRY=203012' \
--data '$PAN=4000001111111118' \
--data 'TEXT=TEST CARDHOLDER' \
--data MDORDER=bd30b67f-f8c7-7c9c-a4ac-66b300b40dc0 \
--data userName=test_user \
--data password=test_user_password \
--data language=en \
--data 'jsonParams={"installments": "3", "totalInstallmentAmount": "900000", "recurringFrequency": "3", "recurringExpiry":"20261231"}'
{
"errorCode": 0,
"is3DSVer2": true,
"threeDSServerTransId": "3e07d895-8cac-460c-81f3-da6f6389dc11",
"threeDSMethodURLServer": "https://3dsec.berekebank.kz/payment/client/gather?threeDSServerTransID=3e07d895-8cac-460c-81f3-da6f6389dc11",
"threeDSMethodURLServerDirect": "https://3dsec.berekebank.kz/payment/rest/3dsmethod.do"
}
Оплата связкой для рассрочки
Для оплаты заказа cвязкой для рассрочки используйте следующую последовательность запросов:
- Получите список связок, используя запрос getBindigs.do с
bindingType=I
→ получите в ответеbindingId
. - Выполните запрос installmentPayment.do с полученным
bindingId
.
В результате заказ будет оплачен с помощью связки с указанным bindingId
.
Пример запроса installmentPayment.do
:
curl --request POST \
--url https://3dsec.berekebank.kz/payment/installmentPayment.do \
--header 'Content-Type: application/json' \
--data '{
"userName": "test_user",
"password": "test_user_password",
"orderNumber": "UAF-203974-DE-12",
"language": "EN",
"bindingId": "8aa4fa8b-4d8a-76ca-b314-7bcc00b4f820",
"amount": 12300,
"currency": "398",
"description" : "Test description",
"additionalParameters": {
"firstParamName": "firstParamValue",
"secondParamName": "secondParamValue"
}
}'
{
"errorCode": 0,
"errorMessage": "Success",
"orderId": "0e441115-f3bc-711c-8827-2fdc00b4f820",
"orderStatus": {
"errorCode": "0",
"orderNumber": "7033",
"orderStatus": 2,
"actionCode": 0,
"actionCodeDescription": "",
"amount": 12300,
"currency": "398",
"date": 1618340470944,
"orderDescription": "Test description",
"merchantOrderParams": [
{
"name": "firstParamName",
"value": "firstParamValue"
},
{
"name": "secondParamName",
"value": "secondParamValue"
}
],
"transactionAttributes": [],
"attributes": [
{
"name": "mdOrder",
"value": "0e441115-f3bc-711c-8827-2fdc00b4f820"
}
],
"cardAuthInfo": {
"maskedPan": "400000**1118",
"expiration": "203012",
"cardholderName": "TEST CARDHOLDER",
"approvalCode": "123456",
"paymentSystem": "VISA",
"product": "visa-product",
"secureAuthInfo": {
"eci": 7
},
"pan": "400000**1118"
},
"bindingInfo": {
"clientId": "test-client",
"bindingId": "8aa4fa8b-4d8a-76ca-b314-7bcc00b4f820"
},
"authDateTime": 1618340471076,
"authRefNum": "111111111111",
"paymentAmountInfo": {
"paymentState": "DEPOSITED",
"approvedAmount": 12300,
"depositedAmount": 12300,
"refundedAmount": 0,
"totalAmount": 12300
},
"bankInfo": {
"bankName": "ES TEST BANK",
"bankCountryCode": "ES",
"bankCountryName": "Spain"
},
"chargeback": false,
"operations": [
{
"amount": 12300,
"cardHolder": "TEST CARDHOLDER",
"authCode": "123456"
}
]
},
"error": false
}