For any question, we are one click away

Contact us

Stored credentials and transactions types

This section describes supported types of stored-credential transactions.

Types of stored credentials

Payment Gateway allows to create and use three types of stored credentials:

One card can have stored credentals of different types associated with it. Moreover, it can have multiple stored credentials for different installment.

Transaction types

Stored-credential transactions belong to either of the two groups depending on the initiator of a transaction:

The type of a transaction should be passed in the tii parameter of API payment requests. Read more about the tii parameter values here.

Managing stored credentials via API

Below you can find examples of storing and using payment credentials of different types via API:

Common stored credentials

Store a common credential

To store a common credential, use the following flow:

  1. Run the register.do request with clientId parameter → get orderId in response.
  2. Pass the received orderId value in the MDORDER parameter of the paymentorder.do request.

As a result, the credential will be stored for the client with the initially specified clientId. You can run the getBindigs.do request to make sure that the credential was stored.

Example of the paymentorder.do request:

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
}

Pay with a common stored credential

To pay for an order with a common stored credential, use the following flow:

  1. Run the register.do request with clientId parameter → get orderId in response.
  2. Get the list of stored credentials using the getBindigs.do request with the same value of clientId and bindingType=C → get bindingId in response.
  3. Run paymentOrderBinding.do request. Pass the orderId value (received on the step 1) in the mdOrder parameter, pass the received bindingId. Available tii values: F, U.

As a result, the order will be payed using the stored credential with the specified bindingId.

Example of the paymentOrderBinding.do request:

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
}

Recurrent stored credentials

Store a recurrent credential

To store a recurrent credential, use the following flow:

  1. Run the register.do request with clientId parameter → get orderId in response.
  2. Pass the received orderId value in the MDORDER parameter of the paymentorder.do request. It is necessary to pass recurringFrequency and recurringExpiry additional parameters (no verification, but this information is used by the bank that issued the card).

As a result, the credential will be stored for the client with the initially specified clientId. You can run the getBindigs.do request to make sure that the credential was stored.

Example of the paymentorder.do request:

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":"20241231"}'
{
  "errorCode": 0,
  "is3DSVer2": true,
  "threeDSServerTransId": "efa8e3ce-a4a6-49f8-b422-df781de18119",
  "threeDSMethodURLServer": "https://uat.dskbank.bg/payment/client/gather?threeDSServerTransID=efa8e3ce-a4a6-49f8-b422-df781de18119"
}

Pay with a recurrent stored credential

To pay for an order with a recurrent stored credential, use the following flow:

  1. Get the list of stored credentials using the getBindigs.do request with bindingType=R → get bindingId in response.
  2. Run recurrentPayment.do request with the received bindingId.

As a result, the order will be payed using the stored credential with the specified bindingId.

Example of the recurrentPayment.do request:

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": "202412",
      "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"
      }
    ]
  }
}

Installment stored credentials

Store an installment credential

To create an installment stored credential, use the following flow:

  1. Run the register.do request with the clientId parameter → get orderId in response.
  2. Pass the received orderId value in the MDORDER parameter of the paymentorder.do request. The installments additional paramenter is required. The recurringFrequency and recurringExpiry additional parameters are recommended. Moreover, they are required if 3DS2 is used (no verification, but this information is used by the bank that issued the card).

As a result, a credential will be stored for the client with the initially specified clientId. You can run the getBindigs.do request to make sure that the credential was stored.

Example of the paymentorder.do request:

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", "recurringFrequency": "3", "recurringExpiry":"20241231"}'
{
    "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"
}

Pay with an installment stored credential

To pay for an order with an installment stored credential, use the following flow:

  1. Get the list of stored credentials using the getBindigs.do request with bindingType=I → get bindingId in response.
  2. Run installmentPayment.do request with the received bindingId.

As a result, the order will be payed using the stored credential with the specified bindingId.

Example of the installmentPayment.do request:

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
}
Categories:
eCommerce API V1
Categories
Search results