Signature authentication

In order to guarantee convenience and security to its customers, e-SiTef offers, in addition to the authenticity POST to the merchant's registered URL (learn more), the option of signing messages, in which content and sender are guaranteed integrity and authenticity, respectively. Thus, the store receives the information of the created transaction directly in response to its REST call and no longer through the authenticity POST.

What you'll need

  • Active registration on e-SiTef's homologation environment (obtained with our support team);
  • The creation of a public key and the management of its respective private key;
  • Public key registration on e-SiTef (done through our support team).

Creating private and public keys

Examples of how to create the private and public keys:

  • On Linux (using the terminal):
# creating private key
ssh-keygen -t rsa -b 4096 -m PEM -f jwtRS256.key

# creating a public key using the created private key
openssl rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256.key.pub
  • On Windows:

Use ssh-keygen at the command prompt

# creating private key
ssh-keygen -t rsa -b 4096 -m PEM -f jwtRS256.key

Use a version of openssl for windows, run as administrator and run the following command:

# creating a public key using the created private key
rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256.key.pub

Important:

The jwtRS256.key.pub file is the only one you'll send to our support team. Always keep safe your private key and your password - if you've assigned one.

Signature algorithm

The algorithm supported by the application is RS256 along with the JWT (RFC 7519) standard.

When using this standard, a signature consists of three parts: header, data (payload) and signature verification. Base64 encoding is applied to each of these parts.

First part (header)

The header must contain the following fixed content:

{
  "alg": "RS256",
  "typ": "JWT"
}

Base64 header:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

Second part (payload)

The payload segment varies according to the operation to be signed. e.g.:

{
  "merchant_id":"XXXXX",
  "merchant_key": "XXXXXXXXXXXXXXX",
  "order_id": "182367r12831t29b",
  "merchant_usn" : "92837429837",
  "timestamp": "1605034925174"
}

Base64 payload:

eyJtZXJjaGFudF9pZCI6IlhYWFhYIiwibWVyY2hhbnRfa2V5IjoiWFhYWFhYWFhYWFhYWFhYIiwib3JkZXJfaWQiOiIxODIzNjdyMTI4MzF0MjliIiwibWVyY2hhbnRfdXNuIjoiOTI4Mzc0Mjk4MzciLCJ0aW1lc3RhbXAiOiIxNjA1MDM0OTI1MTc0In0

Payload composition

Depending on the service called, the payload fields will be different. Below are described the required fields for each service.

Merchant creation and listing services

ParameterDescriptionFormatMandatory
merchant_idMerchant code on e-SiTef.= 15 ANYES
merchant_keyMerchant authentication key on e-SiTef.< 80 ANYES
timestampRepresents the moment the signature is generated in milliseconds. The timestamp field has a validity limit of 10 minutes.< 13 NYES
 
{
  "merchant_id":"XXXXX",
  "merchant_key": "XXXXXXXXXXXXXXX",
  "timestamp": "1605034925174"
}

Merchant editing and query services

ParameterDescriptionFormatMandatory
merchant_idMerchant code on e-SiTef. The production and certification codes will be different.= 15 ANYES
merchant_keyMerchant authentication key on e-SiTef. The production and certification keys will be different.< 80 ANYES
timestampRepresents the moment the signature is generated in milliseconds. The timestamp field has a validity limit of 10 minutes.< 13 NYES
registered_merchant_idMerchant code created or to be created on e-SiTef. The production and certification codes will be different.= 15 ANYES
 
{
  "merchant_id":"XXXXX",
  "merchant_key": "XXXXXXXXXXXXXXX",
  "registered_merchant_id": "YYYYYYY",
  "timestamp": "1605034925174"
}

Transaction creation services

ParameterDescriptionFormatMandatory
merchant_idMerchant code on e-SiTef. The production and certification codes will be different.= 15 ANYES
merchant_keyMerchant authentication key on e-SiTef. The production and certification keys will be different.< 80 ANYES
order_idOrder code defined by the merchant.< 40 ANYES
merchant_usnUnique sequential number for each order, created by the merchant.< 12 NYES
timestampRepresents the moment the signature is generated in milliseconds. The timestamp field has a validity limit of 10 minutes.< 13 NYES

Example:

{
  "merchant_id":"XXXXX",
  "merchant_key": "XXXXXXXXXXXXXXX",
  "order_id": "182367r12831t29b",
  "merchant_usn" : "92837429837",
  "timestamp": "1605034925174"
}

Other services

ParameterDescriptionFormatMandatory
nitTransaction identifier on e-SiTef.= 64 ANYES
merchant_idMerchant code on e-SiTef. The production and certification codes will be different.= 15 ANYES
merchant_keyMerchant authentication key on e-SiTef. The production and certification keys will be different.< 80 ANYES
timestampRepresents the moment the signature is generated in milliseconds. The timestamp field has a validity limit of 10 minutes.< 13 NYES

Example:

{
  "nit":"asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678",
  "merchant_id":"XXXXX",
  "merchant_key": "XXXXXXXXXXXXXXX",
  "timestamp": "1605034925174"
}

Third part (verification)

The third and final part is the result of the encryption of the two previous parts separately coded in Base64 and concatenated by a period (".").

Two previous parts coded separately in Base64 and concatenated by a period ("."), where the first segment of the text - before the period - corresponds to the header and the second corresponds to the payload:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudF9pZCI6IlhYWFhYIiwibWVyY2hhbnRfa2V5IjoiWFhYWFhYWFhYWFhYWFhYIiwib3JkZXJfaWQiOiIxODIzNjdyMTI4MzF0MjliIiwibWVyY2hhbnRfdXNuIjoiOTI4Mzc0Mjk4MzciLCJ0aW1lc3RhbXAiOiIxNjA1MDM0OTI1MTc0In0

Finally, this content must be RSA encrypted using the merchant's private key. Example:

LLQ2kaC3dG0tsu78JyEIbvd8c1G05lo-1qLDBb0lBXsS2lrJ98-rcusEhuodhHDBE701a_RZwCfOH9ebPZXYdEtuLldqp_Q47y_AYOBYuz3eexuVC0sH3MvmljjHEiMYEIKtFyhsSFrBuQBFvBOT4tJCA779j_cP-JnW4MeDazDehsydEa6phsmkGg_0YfN2xdRzaaTrQqldYibUeI7_YEwLTYrZg0Ys7r45quT7veAzNFLEL4I3iJmMJUcBaCfIQl6NKvX7meoSBeFBaj_MRw8WwXnNTjCFXjU6w_iUiYPg0VVAAKGaEYKP7sHUcw1hn-BawMDMorLcvT9YwP4OxQ

Final signature

The final signature is the concatenation of the 3 parts separated by ("."):

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudF9pZCI6IkxPSkFURVNURSIsIm1lcmNoYW50X2tleSI6IkYxOURFMDAxNzdDMzAxREYyNEE4NjVGMTFBQTlCMjU2N0Y2MDQ4OTFGMEY0NEREQUVGRDY5RTMzOTlFMEI3RTEiLCJvcmRlcl9pZCI6IjE4MjM2N3IxMjgzMXQyOWIiLCJtZXJjaGFudF91c24iOiI5MjgzNzQyOTgzNyIsInRpbWVzdGFtcCI6IjE2MDUwMzQ5MjUxNzQifQ.tCRZhbix7x2X_Iz7FBgQOBa18hutPqm3t3mJAnW3_2o

These three parts of the signature, represented by the previous example, must be sent in the Authorization header with value Bearer <signature>. Thus, e-SiTef will be able to validate the signature using the merchant's public key.

Using JWT site for testing

You can use the JWT website to create a valid signature for testing. For that, it is necessary to select the RS256 algorithm and pass the respective payload and a public and private key. "Jwt"

If the public key is not valid, the message "Invalid Signature" will be displayed. "Jwt"

← Soft DescriptorBatch Store Registration →