Transaction creation service

Online Payments - 3DS 2.0 API Transparent Checkout

Brazil

import ApiDoc from '../../../../../src/components/api-doc/ApiDoc';

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

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

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.
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

Did this page help you?