Home

    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):
    # 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 Carat Portal.= 15 ANYES
    merchant_keyMerchant authentication key on Carat Portal.< 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 Carat Portal. The production and certification codes will be different.= 15 ANYES
    merchant_keyMerchant authentication key on Carat Portal. 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 Carat Portal. The production and certification codes will be different.= 15 ANYES
    {
    "merchant_id": "XXXXX",
    "merchant_key": "XXXXXXXXXXXXXXX",
    "registered_merchant_id": "YYYYYYY",
    "timestamp": "1605034925174"
    }

    Transaction cancellation service#

    ParameterDescriptionFormatMandatory
    merchant_idMerchant code on Carat Portal. The production and certification codes will be different.= 15 ANYES
    merchant_keyMerchant authentication key on Carat Portal. 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 NConditional
    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 Carat Portal.= 64 ANYES
    merchant_idMerchant code on Carat Portal. The production and certification codes will be different.= 15 ANYES
    merchant_keyMerchant authentication key on Carat Portal. 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, 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. &quot;Jwt&quot;

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