seToken generation

What is seToken

seToken (Self Encrypted Token) is a cryptogram used for safe card data transfer. It can be used in the following requests when the card data is collected on merchant's side:

Below it is described how to create a seToken and send it in a payment request.

Format of seToken before encryption

An unencrypted seToken is a string that includes from 5 to 9 parameters separated by "/".

Parameters involved in the formation of seToken

The table below lists the parameters that can be used in the seToken string. The parameters must be arranged in a strict sequence according to the order in this table.

Required	Name	Type	Description
Yes	`timestamp`	String	The date of the request according to ISO 8601:2004 in the format `YYYY-MM-DDThh:mm:ss±hh:mm`.

Yes	`uuid`	String [1..32]	The identifier in the UUID standard formed in accordance with the document

Conditional*	`PAN`	Integer [1..19]	Number of the card to be debited. A request must have `PAN` or `bindingId`.

Conditional (see description)	`CVV`	Integer	Verification code of a card. This parameter is mandatory if permission Can process payments without confirmation of CVC is not enabled.

Conditional*	`EXPDATE`	Integer	Card expiration in the following format: `YYYYMM`, where `YYYY` - a year, `MM` - a month.

Conditional*	`mdOrder`	String [1..36]	Order id to be paid with a cryptogram.

Conditional*	`bindingId`	String [1..255]	Identifier of an already existing stored credential. This is the card ID tokenized by the Gateway. Can be used only if the merchant has the permission to work with stored credentials. The request must have `PAN` or `bindingId`.

No	`cardholder`	String	Cardholder's name in Latin characters. This parameter is passed only after an order is paid.

No	`registeredFrom`	String	SDK that was used for order registration. Allowed values are: `MSDK_CORE`, `MSDK_FORMS`, `MSDK_PAYMENT`, `WSDK_CORE`, `WSDK_PAYMENT`

* Mandatory for particular methods. The list of mandatory parameters for seToken used in a particular method is specified in the corresponding method's description in API Reference.

Example of a generated string:

2020-09-15T10:00:33+03:00/9bb1501a-1547-425a-a022-1db5ff8f72c4/5555555555555599/123/202412

where:

the corresponding time is 2020-09-15T10:00:33+03:00
uuid
PAN is 5555555555555599
CVV is 123
expiration date of the card is December 2024

Algorithm for a payment request creation

Make a key request

To do this, open the link https://uat.dskbank.bg/payment/se/keys.do.

As a result, we get the key in the following format:

{
"keys": [
    {
        "keyValue": "-----BEGIN PUBLIC KEY-----{PUBLIC KEY BODY}-----END PUBLIC KEY-----",
        "protocolVersion": "RSA",
        "keyExpiration": 1893456000000
     },
    {
        "keyValue": "-----BEGIN PUBLIC KEY-----{PUBLIC KEY BODY}-----END PUBLIC KEY-----",
        "protocolVersion": "RSA",
        "keyExpiration": 1924992000000
    }
]
}

Where:

keyValue - string representation of the RSA 2048 public key
keyExpiration - planned key expiration date, date in seconds according to the UNIX time standard
protocolVersion - version of the encryption algorithm

Register an order
- Registration of an order
- Registration of an order with preauthorization
Generate a string that needs to be encrypted

In our example above orderId=b94eac90-e487-796a-8ed2-cf5a00096352 is specified as UUID. We get the string:

2020-09-15T10:00:33+03:00/9bb1501a-1547-425a-a022-1db5ff8f72c4/5555555555555599/123/202412
Encrypt the received string

The received string must be encrypted using the RSA encryption algorithm "RSA/None/PKCS1Padding" with a key length of 2048.

Example of encryption result: Cfqv4t2XHBb9k8ixM7jxxCvziETS4koa3bV3F0QUvGVY47nKyMBqjGzV/rvmCAw6KzwoBDzeLsqwBLEzvQhaF627ZS0OJnhttBi4fL3/h/sBSwFtxr3s+oVUeoE3e4SNVUq9vciinOyNCIKqfpeQya+pOUYt3MgrtSeu66Ar12XEj4k6lecZN7Ffquj9RqhZsYhP63np5VCxJR90cNQG+TMWIFU6rqxLAe4gzCJtcXNrPT8aDOI201Zwd+e4K1YnrI7dZGlibO7MVMPB9m7NJaJTHko/MiJNWumAjS4yDDovLraIKMwOFTvAhqXsHslthpcUO0GZXEIaDRgERD7+jw==

Before passing in a REST request, the encrypted string should be URL-encoded:
Cfqv4t2XHBb9k8ixM7jxxCvziETS4koa3bV3F0QUvGVY47nKyMBqjGzV%2FrvmCAw6KzwoBDzeLsqwBLEzvQhaF627ZS0OJnhttBi4fL3%2Fh%2FsBSwFtxr3s%2BoVUeoE3e4SNVUq9vciinOyNCIKqfpeQya%2BpOUYt3MgrtSeu66Ar12XEj4k6lecZN7Ffquj9RqhZsYhP63np5VCxJR90cNQG%2BTMWIFU6rqxLAe4gzCJtcXNrPT8aDOI201Zwd%2Be4K1YnrI7dZGlibO7MVMPB9m7NJaJTHko%2FMiJNWumAjS4yDDovLraIKMwOFTvAhqXsHslthpcUO0GZXEIaDRgERD7%2Bjw%3D%3D
Make a payment request with seToken.

See example of the payment request with seToken here.