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 the following type 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.
Two-phase payments are not allowed for MIT transactions.

The type of a transaction should be passed in the tii (Transaction Intitiator Indicator) parameter of API payment requests. Possible values of tii:

`tii` value	Description	Transaction type	Transaction initiator	Card data for transaction	Card data saved after transaction	Note
Empty		Regular	Customer	Entered by Customer	No	An e-commerce transaction, credential is not stored.
CI	Initial Common CIT	Initiating	Customer	Entered by Customer	Yes	An e-commerce transaction, credential is stored.
F	Unscheduled CIT	Subsequent	Customer	Customer selects card instead of manual entry	No	An e-commerce transaction that uses a stored credential.
U	Unscheduled MIT	Subsequent	Merchant	No manual entry, Merchant passes the data	No	An e-commerce transaction that uses a stored credential. Used for one-phase payments only.
RI	Initial Recurrent CIT	Initiating	Customer	Entered by Customer	Yes	An e-commerce transaction, credential is stored.
R	Recurrent MIT	Subsequent	Merchant	No manual entry, Merchant passes the data	No	A recurrent transaction that uses a stored credential. Used for one-phase payments only.
II	Initial Installment CIT	Initiating	Customer	Entered by Customer	Yes	An e-commerce transaction, credential is stored.
I	Installment MIT	Subsequent	Merchant	No manual entry, Merchant passes the data	No	An installment transaction that uses a stored credential. Used for one-phase payments only.

Managing stored credentials via API

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

Common stored credentials
Recurrent stored credentials
Installment stored credentials

Common stored credentials

Store a common credential

To store a common credential, use the following flow:

Run the register.do request with clientId parameter → get orderId and formUrl in response.

Example of the register.do request for storing a common credential:

curl --request POST \
  --url https://demo-pay.mano.bank/payment/rest/register.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data amount=123456 \
  --data userName=test_user \
  --data password=test_user_password \
  --data orderNumber=1234567890ABCDEF \
  --data returnUrl=https://mybestmerchantreturnurl.com \
  --data failUrl=https://mybestmerchantfailurl.com \
  --data email=test@test.com \
  --data clientId=259753456 \
  --data features=FORCE_CREATE_BINDING \
  --data language=en

{
  "orderId": "01491d0b-c848-7dd6-a20d-e96900a7d8c0",
  "formUrl": "https://demo-pay.mano.bank/payment/payment/merchants/ecom/payment_en.html?mdOrder=01491d0b-c848-7dd6-a20d-e96900a7d8c0"
}

Pass the received orderId value in the MDORDER parameter of the paymentorder.do request.

Example of the paymentorder.do request:

curl --request POST \
  --url https://demo-pay.mano.bank/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=01491d0b-c848-7dd6-a20d-e96900a7d8c0 \
  --data userName=test_user \
  --data password=test_user_password

{
  "redirect": "https://demo-pay.mano.bank/payment/merchants/pay/finish.html?orderId=59e00106-1f69-76a7-b893-b27c00b4f820&lang=en",
  "info": "Your order is proceeded, redirecting...",
  "errorCode": 0
}

As a result, the credential will be stored for the client with the initially specified clientId.

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 → get orderId in response.

Get the list of stored credentials using the getBindings.do request with the same value of clientId and bindingType=C → get bindingId in response.

Example of the getBindings.do request:

curl --request POST \
--url https://demo-pay.mano.bank/payment/rest/getBindings.do \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data userName=test_user \
--data password=test_user_password \
--data clientId=259753456 \
--data bindingType=C

{
    "errorCode":"0",
    "errorMessage":"Success",
    "bindings": [
        {
                "bindingId": "b83317e0-1679-7d85-b375-a63200b4f820",
                "maskedPan": "411111**1111",
                "expiryDate": "203412",
                "paymentWay": "TOKEN_PAY",
                "paymentSystem": "CARD",
                "displayLabel": "XXXXXXXXXXXX1111",
                "bindingCategory": "COMMON"
            }
        ]
     }

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.

Example of the paymentOrderBinding.do request:

curl --request POST \
  --url https://demo-pay.mano.bank/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://demo-pay.mano.bank/payment/merchants/pay/finish.html?orderId=24c3d392-4c60-7f0b-9ff5-b00100b4f820&lang=en",
  "info": "Your order is proceeded, redirecting...",
  "errorCode": 0
}

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

Recurrent stored credentials

Store a recurrent credential

To store a recurrent credential, use the following flow:

Run the register.do request with clientId parameter → get orderId and formUrl in response.

Example of the register.do request:

curl --request POST \
  --url https://demo-pay.mano.bank/payment/rest/register.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data amount=123456 \
  --data userName=test_user \
  --data password=test_user_password \
  --data orderNumber=1234567890ABCDEF \
  --data returnUrl=https://mybestmerchantreturnurl.com \
  --data failUrl=https://mybestmerchantfailurl.com \
  --data email=test@test.com \
  --data clientId=259753456 \
  --data features=FORCE_CREATE_BINDING \
  --data language=en \'

{
  "orderId": "01491d0b-c848-7dd6-a20d-e96900a7d8c0",
  "formUrl": "https://demo-pay.mano.bank/payment/payment/merchants/ecom/payment_en.html?mdOrder=01491d0b-c848-7dd6-a20d-e96900a7d8c0"
}

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).

Example of the paymentorder.do request:

curl --request POST \
  --url https://demo-pay.mano.bank/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=01491d0b-c848-7dd6-a20d-e96900a7d8c0 \
  --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://demo-pay.mano.bank/payment/client/gather?threeDSServerTransID=efa8e3ce-a4a6-49f8-b422-df781de18119"
}

As a result, the credential will be stored for the client with the initially specified clientId.

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 getBindings.do request with the same clientId and bindingType=R → get bindingId in response.

Example of te getBindings.do request:

curl --request POST \
--url https://demo-pay.mano.bank/payment/rest/getBindings.do \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data userName=test_user \
--data password=test_user_password \
--data clientId=259753456 \
--data bindingType=R

{
"errorCode":"0",
"errorMessage":"Success",
"bindings": [
    {
            "bindingId": "44779116-41a5-7798-b072-c0a30760e2b0",
            "maskedPan": "411111**1111",
            "expiryDate": "203412",
            "paymentWay": "TOKEN_PAY",
            "paymentSystem": "CARD",
            "displayLabel": "XXXXXXXXXXXX1111",
            "bindingCategory": "RECURRENT"
        }
    ]
 }

Run recurrentPayment.do request with the received bindingId.

Example of the recurrentPayment.do request:

curl --request POST \
  --url https://demo-pay.mano.bank/payment/recurrentPayment.do \
  --header 'Content-Type: application/json' \
  --data '{
  "userName": "test_user",
  "password": "test_user_password",
  "orderNumber": "UAF-203974-DE-12",
  "language": "EN",
  "bindingId": "44779116-41a5-7798-b072-c0a30760e2b0",
  "amount": 12300,
  "currency": "978",
  "description" : "Test description",
  "additionalParameters": {
    "firstParamName": "firstParamValue",
    "secondParamName": "secondParamValue"
  }
 }'

{
  "success": true,
  "data": {
    "orderId": "44779116-41a5-7798-b072-c0a30760e2b0"
  },
  "orderStatus": {
    "errorCode": "0",
    "orderNumber": "9003",
    "orderStatus": 2,
    "actionCode": 0,
    "actionCodeDescription": "",
    "amount": 12300,
    "currency": "978",
    "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"
      }
    ]
  }
}

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

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 → get orderId in response.

Example of the register.do request:

curl --request POST \
  --url https://demo-pay.mano.bank/payment/rest/register.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data amount=123456 \
  --data userName=test_user \
  --data password=test_user_password \
  --data orderNumber=1234567890ABCDEF \
  --data returnUrl=https://mybestmerchantreturnurl.com \
  --data failUrl=https://mybestmerchantfailurl.com \
  --data email=test@test.com \
  --data clientId=259753456 \
  --data features=FORCE_CREATE_BINDING \
  --data language=en \'

{
  "orderId": "01491d0b-c848-7dd6-a20d-e96900a7d8c0",
  "formUrl": "https://demo-pay.mano.bank/payment/payment/merchants/ecom/payment_en.html?mdOrder=01491d0b-c848-7dd6-a20d-e96900a7d8c0"
}

Pass the received orderId value in the MDORDER parameter of the paymentorder.do request. The installments, totalInstallmentAmount, recurringFrequency, and recurringExpiry additional paramenters are required.

Example of the paymentorder.do request:

curl --request POST \
  --url https://demo-pay.mano.bank/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=01491d0b-c848-7dd6-a20d-e96900a7d8c0 \
  --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://demo-pay.mano.bank/payment/client/gather?threeDSServerTransID=3e07d895-8cac-460c-81f3-da6f6389dc11",
    "threeDSMethodURLServerDirect": "https://demo-pay.mano.bank/payment/rest/3dsmethod.do"
}

As a result, a credential will be stored for the client with the initially specified clientId.

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 getBindings.do request with the same clientId and bindingType=I → get bindingId in response.

Example of the getBindings.do request:

curl --request POST \
--url https://demo-pay.mano.bank/payment/rest/getBindings.do \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data userName=test_user \
--data password=test_user_password \
--data clientId=259753456 \
--data bindingType=I

{
"errorCode":"0",
"errorMessage":"Success",
"bindings": [
    {
            "bindingId": "44779116-41a5-7798-b072-c0a30760e2b0",
            "maskedPan": "411111**1111",
            "expiryDate": "203412",
            "paymentWay": "TOKEN_PAY",
            "paymentSystem": "CARD",
            "displayLabel": "XXXXXXXXXXXX1111",
            "bindingCategory": "INSTALLMENT"
        }
    ]
 }

Run installmentPayment.do request with the received bindingId.

Example of the installmentPayment.do request:

curl --request POST \
  --url https://demo-pay.mano.bank/payment/installmentPayment.do \
  --header 'Content-Type: application/json' \
  --data '{
  "userName": "test_user",
  "password": "test_user_password",
  "orderNumber": "UAF-203974-DE-12",
  "language": "EN",
  "bindingId": "44779116-41a5-7798-b072-c0a30760e2b0",
  "amount": 12300,
  "currency": "978",
  "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": "978",
    "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
}

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