Връзки и типове транзакции

В този раздел се описват поддържаните типове транзакции по връзки.

Типове връзки

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

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

Една карта може да има връзки от различни типове. Освен това картата може да има няколко връзки за различни разсрочвания.

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

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

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 и formUrl.
Предайте получената стойност orderId в параметъра MDORDER на заявката paymentorder.do.

В резултат ще бъде създадено свързване за клиента с първоначално посоченото clientId. Можете да изпълните заявка getBindings.do, за да се уверите, че свързването е създадено.

Пример за заявка paymentorder.do:

curl --request POST \
  --url https://uat.dskbank.bg/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://uat.dskbank.bg/payment/merchants/pay/finish.html?orderId=59e00106-1f69-76a7-b893-b27c00b4f820&lang=en",
  "info": "Your order is proceeded, redirecting...",
  "errorCode": 0
}

Плащане с обикновено свързване

За плащане на поръчка с обикновено свързване използвайте следната последователност от заявки:

Изпълнете заявка register.do с параметър clientId → получете в отговор orderId.
Получете списък със свързвания с помощта на заявка getBindings.do с същата стойност clientId и с bindingType=C → получете в отговора bindingId.
Изпълнете заявка paymentOrderBinding.do. Предайте стойността orderId (получена на Стъпка 1) в параметъра mdOrder, както и предайте получения bindingId. Достъпни стойности tii: F, U.

В резултат поръчката ще бъде платена с помощта на свързването с посоченото bindingId.

Пример за заявка paymentOrderBinding.do:

curl --request POST \
  --url https://uat.dskbank.bg/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://uat.dskbank.bg/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 и formUrl
Предайте получената стойност orderId в параметъра MDORDER на заявката paymentorder.do. Необходимо е да предадете допълнителните параметри recurringFrequency и recurringExpiry (верификация не се провежда, но тази информация се използва от банката, издала картата).

В резултат ще бъде създадена връзка за клиента с първоначално указаното clientId. Можете да изпълните заявка getBindings.do, за да се убедите, че връзката е създадена.

Пример за заявка paymentorder.do:

curl --request POST \
  --url https://uat.dskbank.bg/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://uat.dskbank.bg/payment/client/gather?threeDSServerTransID=efa8e3ce-a4a6-49f8-b422-df781de18119"
}

Плащане с рекурентна връзка

За плащане на поръчка с рекурентна връзка използвайте следната последователност от заявки:

Получете списъка с връзки, използвайки заявка getBindings.do с bindingType=R → получете в отговораbindingId.
Изпълнете заявка recurrentPayment.do с получения bindingId.

В резултат поръчката ще бъде платена с помощта на връзката с указания bindingId.

Пример за заявка recurrentPayment.do:

curl --request POST \
  --url https://uat.dskbank.bg/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": "975",
  "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": "975",
    "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://uat.dskbank.bg/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://uat.dskbank.bg/payment/client/gather?threeDSServerTransID=3e07d895-8cac-460c-81f3-da6f6389dc11",
    "threeDSMethodURLServerDirect": "https://uat.dskbank.bg/payment/rest/3dsmethod.do"
}

Плащане с връзка за разсрочване

За плащане на поръчка с връзка за разсрочване използвайте следната последователност от заявки:

Получете списъка с връзки, използвайки заявка getBindings.do с bindingType=I → получете в отговораbindingId.
Изпълнете заявка installmentPayment.do с получения bindingId.

В резултат поръчката ще бъде платена с помощта на връзката с указания bindingId.

Пример за заявка installmentPayment.do:

curl --request POST \
  --url https://uat.dskbank.bg/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": "975",
  "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": "975",
    "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
}