Связки и типы транзакций

В этом разделе описываются поддерживаемые типы транзакций по связкам.

Типы связок

Платежный шлюз позволяет создавать и использовать три типа связок:

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

Одна карта может иметь связки разных типов. Более того, у карты может несколько связок для разных рассрочек.

Тип транзакций

Транзакции по связкам принадлежат к одной из двух групп в зависимости от инициатора транзакции:

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 и c bindingType=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 (верификация не проводится, но эта информация используется банком, выпустившим карту).

Пример запроса 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.

Пример запроса 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
}

Связки и типы транзакций

Типы связок

Тип транзакций

Управление связками через API

Обычные связки

Рекуррентные связки

Связки для рассрочки

Свяжитесь с нами

Спасибо!