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

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

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

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

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

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

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

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

CIT (cardholder-initiated transactions) – транзакции за електронна търговия, в които притежателят на картата участва в плащането. Тази група включва 4 вида транзакции:
- C/CI – инициираща транзакция със запазване на обичайна връзка за по-нататъшни плащания.
- RI – инициираща транзакция със запазване на връзка за рекурентни плащания.
- II – инициираща транзакция със запазване на връзка за плащания на изплащане.
- F – извънпланова транзакция, извършвана от притежателя на картата с използване на обичайна връзка.
MIT (Merchant-initiated Transactions) – транзакции за електронна търговия, извършвани от продавача без участието на притежателя на картата. В тази група влизат 3 типа транзакции:
- U – извънпланова транзакция с използване на обичайна връзка. Например, начисляване на неустойка. Обърнете внимание, че за такава операция няма CVC или 3DS верификация, тъй като собственикът на картата не участва в нея и не може да въвежда никакви данни.
- R – последваща рекурентна транзакция с използване на рекурентна връзка.
- I – последваща транзакция на изплащане с използване на връзка за изплащане.
За MIT транзакции двуетапните плащания са забранени.

Типът транзакция трябва да се предава в параметъра 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
}