Transaction creation service

This call is required to obtain the 3DS Method URL corresponding to the card, besides creating a 3DS Server transaction, which will be used in the following steps of the flow.

Important: The value of the message_version field returned in the response must be used in the CREQ step (for challenge transactions).

Call details#

  • Resource: /v2/authentication
  • HTTP Method: POST
  • Request format: JSON
  • Response format: JSON
  • Header parameters:
ParameterDescriptionFormatMandatory
merchant_idMerchant code on 3DS Server. The production and certification codes will be different.< 15 ANYES
merchant_keyMerchant authentication key on 3DS Server. The production and certification keys will be different.< 80 ANYES
Content-TypeFixed value application/json.= 15 ANYES
AuthorizationMerchant's signature in the Bearer {signature} format. Example: Bearer JHVGytfdgauygdauiw78264284527852897hagdg.< 2000 ANCOND.*
carat_merchant_idCarat merchant code must be sent only if the token field is sent in the request< 15 ANCOND.
carat_merchant_keyThe authentication key of the Carat merchant must be sent only if the token field is sent in the request< 80 ANCOND.

* Note: For security reasons, for transaction authentication to be performed, it is recommended to inform a value for Authorization field.
If the store has registered its public key through the Carat Portal, this field is mandatory.

Available authorizers#

IDName
1Visa
2Mastercard
41Elo
3Amex

Signature generation#

To generate the value to be sent in the Authorization header, it is necessary:

Payload#

It is possible to generate the signature using 2 different payloads:

  • Payload using card number for this functionality must have the following format:
{
"merchant_id": "XXXXX",
"merchant_key": "XXXXXXXXXXXXXXX",
"cartao": "5555555555555555",
"timestamp": "1620952402824"
}
  • Payload using token for this functionality must have the following format:
{
"merchant_id":"XXXXX",
"merchant_key": "XXXXXXXXXXXXXXX",
"token": "er334gvdgdf5dfgdfg63456363434tre345353rg34tb4576jfgrtu464jj56j56u56u56ghhrthrhrthrth467",
"timestamp": "1620952402824"
}

Payload Base64:

eyJhbGciOiJSUzI1NiJ9.eyJtZXJjaGFudF9pZCI6IkRBVEFPTkxZT04iLCJtZXJjaGFudF9rZXkiOiI5QUM0RjVEQTk0NDExODJDMUNEODJEMzlDNDg2ODYzOTNBRkZDNjlGQzRFMDczM0VFNDgyNjRDNjNCODZENUVFIiwiY2FydGFvIjoiNDExMTEyMDAwMDAwMDAwMCIsInRpbWVzdGFtcCI6IjE2MjA5NTEyNDA5NzUifQ.oYlyOKPsJ9aOCrmJcOq024FGnKReevWdSbKXTcopNqp8AT_4dERYD9G4v-h7pq-xbZOGUOO7YpNmGIqmC-oWHLHGdDGenM7bJyuq1QUff3D9WoMNLeBk5wyguVPoaH7QApksWJllp4fUfLz_BDjw5xwc8ksrDQu1M8w-_PP8wWv9f1_A34Lo7dk1FTQwuFNO4ZBfnkTRLfn0_pIypU9h42Sh9Nr4V8_9Xz0TZvbSw5_FNFY_iQAwXs1Ipr0tGHNL1fvKBlgXfB06ouenHIFNhvzdgPjwGZToJo5hG3NSLsRAI-OiXEkK9loPNNNldkSTzbrtYYTD8gDL90dbQe8fIE3fir-48dsGCzyqO7dZigSbSXxRZkHC6ArfIY6MtY9C4pD8Ero4kOXjAMfxfJq7fhsTh7wrnUhkU-hZxl4nGH_0BPWAe7vBqdCw2agOpUzixY1rLtlQlJ41W42rbIL7lSW6zPF1oLtYG73hUjlcmW8aAdoJlQANWK9_dv6gHv0PjV-BS6jZsLT2aL5Mqgi8DCVPg6cRwAfv2DXSizcSX-6a6mpfQ7ZgR0eU0vHgopX_t6jnO3O3v6Lp2vIArrsH8SW0LT1oBDn-9p-SvtMIJQDhejkPuzrVmwNNXMy8Sb6c8LmhfnPhmyeObUbk1I1iCcbIrCdvqteZdrlGMCImo2M

Payload composition#

ParameterDescriptionFormatMandatory
merchant_idMerchant code on Carat Portal.= 15 ANYES
merchant_keyMerchant authentication key on Carat Portal.< 80 ANYES
cartaoCustomer's card number (PAN), the card or token field must always be sent in the payload< 19 ANCOND
tokenHASH of a card stored in Carat, the card or token field must always be sent in the payload= 88 ANCOND
timestampRepresents the moment the signature is generated in milliseconds. The timestamp field has a validity limit of 10 minutes.< 13 NYES

Examples#

Below are some examples of the transaction creation service using the cURL tool.

Request with card number:

To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br

curl
--request POST "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJtZXJjaGFudF9pZCI6IkRBVEFPTkxZT04iLCJtZXJjaGFudF9rZXkiOiI5QUM0RjVEQTk0NDExODJDMUNEODJEMzlDNDg2ODYzOTNBRkZDNjlGQzRFMDczM0VFNDgyNjRDNjNCODZENUVFIiwiY2FydGFvIjoiNDExMTEyMDAwMDAwMDAwMCIsInRpbWVzdGFtcCI6IjE2MjA5NTEyNDA5NzUifQ.oYlyOKPsJ9aOCrmJcOq024FGnKReevWdSbKXTcopNqp8AT_4dERYD9G4v-h7pq-xbZOGUOO7YpNmGIqmC-oWHLHGdDGenM7bJyuq1QUff3D9WoMNLeBk5wyguVPoaH7QApksWJllp4fUfLz_BDjw5xwc8ksrDQu1M8w-_PP8wWv9f1_A34Lo7dk1FTQwuFNO4ZBfnkTRLfn0_pIypU9h42Sh9Nr4V8_9Xz0TZvbSw5_FNFY_iQAwXs1Ipr0tGHNL1fvKBlgXfB06ouenHIFNhvzdgPjwGZToJo5hG3NSLsRAI-OiXEkK9loPNNNldkSTzbrtYYTD8gDL90dbQe8fIE3fir-48dsGCzyqO7dZigSbSXxRZkHC6ArfIY6MtY9C4pD8Ero4kOXjAMfxfJq7fhsTh7wrnUhkU-hZxl4nGH_0BPWAe7vBqdCw2agOpUzixY1rLtlQlJ41W42rbIL7lSW6zPF1oLtYG73hUjlcmW8aAdoJlQANWK9_dv6gHv0PjV-BS6jZsLT2aL5Mqgi8DCVPg6cRwAfv2DXSizcSX-6a6mpfQ7ZgR0eU0vHgopX_t6jnO3O3v6Lp2vIArrsH8SW0LT1oBDn-9p-SvtMIJQDhejkPuzrVmwNNXMy8Sb6c8LmhfnPhmyeObUbk1I1iCcbIrCdvqteZdrlGMCImo2M'
--data-binary
{
"cardholder":{
"acct":{
"number":"1234123412341234"
}
},
"brand_id":"2"
}
--verbose

Response:

{
"three_ds_method_url": "https://www.example.com",
"three_ds_server": {
"trans_id": "12341234-1234-1234-1234-123412341234",
"status": "NEW"
},
"acs": {
"protocol_version": {
"start": "2.1.0",
"end": "2.2.0"
}
},
"device_channel": "02",
"ds": {
"protocol_version": {
"start": "2.1.0",
"end": "2.2.0"
}
},
"message_version": "2.2.0"
}

Request with token: To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br

curl
--request POST "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--header "carat_merchant_id: yyyyyyyyyyyyyyy"
--header "carat_merchant_key: zzzzzzzzzzzzzz"
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJtZXJjaGFudF9pZCI6IkRBVEFPTkxZT04iLCJtZXJjaGFudF9rZXkiOiI5QUM0RjVEQTk0NDExODJDMUNEODJEMzlDNDg2ODYzOTNBRkZDNjlGQzRFMDczM0VFNDgyNjRDNjNCODZENUVFIiwiY2FydGFvIjoiNDExMTEyMDAwMDAwMDAwMCIsInRpbWVzdGFtcCI6IjE2MjA5NTEyNDA5NzUifQ.oYlyOKPsJ9aOCrmJcOq024FGnKReevWdSbKXTcopNqp8AT_4dERYD9G4v-h7pq-xbZOGUOO7YpNmGIqmC-oWHLHGdDGenM7bJyuq1QUff3D9WoMNLeBk5wyguVPoaH7QApksWJllp4fUfLz_BDjw5xwc8ksrDQu1M8w-_PP8wWv9f1_A34Lo7dk1FTQwuFNO4ZBfnkTRLfn0_pIypU9h42Sh9Nr4V8_9Xz0TZvbSw5_FNFY_iQAwXs1Ipr0tGHNL1fvKBlgXfB06ouenHIFNhvzdgPjwGZToJo5hG3NSLsRAI-OiXEkK9loPNNNldkSTzbrtYYTD8gDL90dbQe8fIE3fir-48dsGCzyqO7dZigSbSXxRZkHC6ArfIY6MtY9C4pD8Ero4kOXjAMfxfJq7fhsTh7wrnUhkU-hZxl4nGH_0BPWAe7vBqdCw2agOpUzixY1rLtlQlJ41W42rbIL7lSW6zPF1oLtYG73hUjlcmW8aAdoJlQANWK9_dv6gHv0PjV-BS6jZsLT2aL5Mqgi8DCVPg6cRwAfv2DXSizcSX-6a6mpfQ7ZgR0eU0vHgopX_t6jnO3O3v6Lp2vIArrsH8SW0LT1oBDn-9p-SvtMIJQDhejkPuzrVmwNNXMy8Sb6c8LmhfnPhmyeObUbk1I1iCcbIrCdvqteZdrlGMCImo2M'
--data-binary
{
"cardholder":{
"acct":{
"token":"er334gvdgdf5dfgdfg63456363434tre345353rg34tb4576jfgrtu464jj56j56u56u56ghhrthrhrthrth467"
}
},
"brand_id":"2"
}
--verbose

Response:

{
"three_ds_method_url": "https://www.example.com",
"three_ds_server": {
"trans_id": "12341234-1234-1234-1234-123412341234",
"status": "NEW"
},
"acs": {
"protocol_version": {
"start": "2.1.0",
"end": "2.2.0"
}
},
"device_channel": "02",
"ds": {
"protocol_version": {
"start": "2.1.0",
"end": "2.2.0"
}
},
"message_version": "2.2.0"
}

Request parameters#

The table below describes the request parameters of the transaction creation service:

ParameterDescriptionFormatMandatory
brand_idBrand ID. Learn more.= 4 NYES
cardholder.acct
numberCustomer's card number (PAN), the number or token field must always be sent in the request< 19 NCOND
tokenHASH of a card stored in Carat, the number or token field must always be sent in the request= 88 ANCOND
message
version3DS message version: 2.1.0 or 2.2.0.< 8 ANNO

Response parameters#

If successful, the HTTP response code will be 201. Any other code must be interpreted as an error. The table below describes the response parameters of the transaction creation service:

ParameterDescriptionFormat
three_ds_method_urlInvisible frame URL to be displayed on the customer's browser< 256 AN
device_channelDevice channel.
  • 01 = application (APP)
  • 02 = browser (BRW)
< 2 N
message_versionTransaction Version (This version must be used on CRes request)< 8 AN
three_ds_server
trans_id3DS Server transaction ID< 8 AN
status3DS Server Status. Learn more.= 3 AN
acs.protocol_version
startThe earliest (i.e. oldest) active protocol version that is supported by the ACS.< 8 AN
endThe most recent active protocol version that is supported by the ACS.< 8 AN
ds.protocol_version
startThe earliest (i.e. oldest) active protocol version that is supported by the DS.< 8 AN
endThe most recent active protocol version that is supported by the DS.< 8 AN
error
codeError code. Learn more.< 3 N
componentIndicates which component identified the error.
  • C = 3DS SDK
  • S = 3DS Server
  • D = DS
  • A = ACS
= 1 AN
descriptionError description< 2048 AN
detailError details< 28 AN