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:
- Common – for payments that are not related to any plan or schedule. For example, when a customer makes a new order and pays for it using previously saved card data.
- Recurrent – for payments that occurs on a fixed schedule. For example, monthly utility bills.
- Installment – for payment by installments, when a customer pays a bill in small portions throughout a fixed period of time according to a payment plan.
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:
- CIT (Cardholder-initiated Transactions) – e-commerce transactions where a cardholder takes part in the payment. This group includes 4 types of transactions:
- C/CI – common initial transaction, when a common credential is stored for further payments.
- RI – recurrent initial transaction, when a recurrent credential is stored for further recurring payments.
- II – installment initial transaction, when an installment credential is stored for further payments by installments.
- F – unscheduled transaction, performed by a cardholder using a common stored credential.
-
MIT (Merchant-initiated Transactions) – e-commerce transactions performed by the merchant without participation of a cardholder. This group includes 3 types of transactions:
- U – unscheduled transaction performed using a common stored credential. For example, penalty charge. Note that there is no CVC or 3DS verification for such operation as a cardholder does not take part in it and cannot enter any data.
- R - subsequent recurrent transaction that uses a recurrent stored credential.
- I – subsequent installment transaction that uses an installment stored credential.
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:
- Run the register.do request with
clientId
parameter → getorderId
in response. - Pass the received
orderId
value in theMDORDER
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:
- Run the register.do request with
clientId
parameter → getorderId
in response. - Get the list of stored credentials using the getBindigs.do request with the same value of
clientId
andbindingType=C
→ getbindingId
in response. - Run paymentOrderBinding.do request. Pass the
orderId
value (received on the step 1) in themdOrder
parameter, pass the receivedbindingId
. Availabletii
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:
- Run the register.do request with
clientId
parameter → getorderId
in response. - Pass the received
orderId
value in theMDORDER
parameter of the paymentorder.do request. It is necessary to passrecurringFrequency
andrecurringExpiry
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:
- Get the list of stored credentials using the getBindigs.do request with
bindingType=R
→ getbindingId
in response. - 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:
- Run the register.do request with the
clientId
parameter → getorderId
in response. - Pass the received
orderId
value in theMDORDER
parameter of the paymentorder.do request. Theinstallments
additional paramenter is required. TherecurringFrequency
andrecurringExpiry
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:
- Get the list of stored credentials using the getBindigs.do request with
bindingType=I
→ getbindingId
in response. - 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
}