Signature authentication
In order to guarantee convenience and security to its customers, Carat Portal offers, in addition to the authenticity POST to the merchant's registered URL ([learn more](/en/docs/e-sitef/recarga-rest-begin#parameters-sent-by-Carat Portal-on-https-post)), 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 Carat Portal'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 Carat Portal (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):
- On Windows:
Use ssh-keygen at the command prompt
Use a version of openssl for windows, run as administrator and run the following command:
Important:
The
jwtRS256.key.pubfile 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:
Base64 header:
Second part (payload)#
The payload segment varies according to the operation to be signed. e.g.:
Base64 payload:
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#
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
merchant_id | Merchant code on Carat Portal. | = 15 AN | YES |
merchant_key | Merchant authentication key on Carat Portal. | < 80 AN | YES |
timestamp | Represents the moment the signature is generated in milliseconds. The timestamp field has a validity limit of 10 minutes. | < 13 N | YES |
Merchant editing and query services#
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
merchant_id | Merchant code on Carat Portal. The production and certification codes will be different. | = 15 AN | YES |
merchant_key | Merchant authentication key on Carat Portal. The production and certification keys will be different. | < 80 AN | YES |
timestamp | Represents the moment the signature is generated in milliseconds. The timestamp field has a validity limit of 10 minutes. | < 13 N | YES |
registered_merchant_id | Merchant code created or to be created on Carat Portal. The production and certification codes will be different. | = 15 AN | YES |
Transaction creation services#
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
merchant_id | Merchant code on Carat Portal. The production and certification codes will be different. | = 15 AN | YES |
merchant_key | Merchant authentication key on Carat Portal. The production and certification keys will be different. | < 80 AN | YES |
order_id | Order code defined by the merchant. | < 40 AN | Conditional |
merchant_usn | Unique sequential number for each order, created by the merchant. | < 12 N | Conditional |
timestamp | Represents the moment the signature is generated in milliseconds. The timestamp field has a validity limit of 10 minutes. | < 13 N | YES |
Important:
The
order_idandmerchant_usnfields are not mandatory for some transaction creation services and, therefore, they must follow the same rule, being informed with the same values contained in the request body.
Example:
Other services#
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
nit | Transaction identifier on Carat Portal. | = 64 AN | YES |
merchant_id | Merchant code on Carat Portal. The production and certification codes will be different. | = 15 AN | YES |
merchant_key | Merchant authentication key on Carat Portal. The production and certification keys will be different. | < 80 AN | YES |
timestamp | Represents the moment the signature is generated in milliseconds. The timestamp field has a validity limit of 10 minutes. | < 13 N | YES |
Example:
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:
Finally, this content must be RSA encrypted using the merchant's private key. Example:
Final signature#
The final signature is the concatenation of the 3 parts separated by ("."):
These three parts of the signature, represented by the previous example, must be sent in the Authorization header with value Bearer <signature>. Thus, Carat Portal 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.
If the public key is not valid, the message "Invalid Signature" will be displayed.
