Запазени платежни данни и типове транзакции

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

Типове запазени платежни данни

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

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

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

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

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

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
}