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:
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
merchant_id | Merchant code on 3DS Server. The production and certification codes will be different. | < 15 AN | YES |
merchant_key | Merchant authentication key on 3DS Server. The production and certification keys will be different. | < 80 AN | YES |
Content-Type | Fixed value application/json. | = 15 AN | YES |
Authorization | Merchant's signature in the Bearer {signature} format. Example: Bearer JHVGytfdgauygdauiw78264284527852897hagdg. | < 2000 AN | COND.* |
carat_merchant_id | Carat merchant code must be sent only if the token field is sent in the request | < 15 AN | COND. |
carat_merchant_key | The authentication key of the Carat merchant must be sent only if the token field is sent in the request | < 80 AN | COND. |
* Note: For security reasons, for transaction authentication to be performed, it is recommended to inform a value for
Authorizationfield.
If the store has registered its public key through the Carat Portal, this field is mandatory.For more information on the future v3, check Quick Start.
Supported Brands#
| ID | Name |
|---|---|
1 | Visa |
2 | Mastercard |
41 | Elo |
3 | Amex |
Signature generation#
To generate the value to be sent in the Authorization header, it is necessary:
- Generate public and private keys
- See the Signature authentication page, section Creating private and public keys.
- Send only the public key to our support team, who will internally associate that key with your store's registration.
- Follow the signature generation instructions described on Signature authentication page, section Signature algorithm, except the subsection Second part (payload), which will be different in this case - see more details below.
Payload#
It is possible to generate the signature using 3 different payloads:
- Payload using card number for this functionality must have the following format:
- Payload using token for this functionality must have the following format:
- [Future v3] Payload using encrypted card number for this functionality must have the following format:
Payload Base64:
Payload composition#
| 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 |
cartao | Customer's card number (PAN), the card or token field must always be sent in the payload | < 19 AN | COND |
token | HASH of a card stored in Carat, the card or token field must always be sent in the payload | = 88 AN | COND |
timestamp | Represents the moment the signature is generated in milliseconds. The timestamp field has a validity limit of 10 minutes. | < 13 N | YES |
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
Response:
Request with token:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
[Future v3] Request with encrypted card number:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
HTTP 400 Errors#
Request with a card number outside of supported card range (305 error code and INV status):
Other invalid inputs will also result in a INV status.
Response with error code 305 and INV status:
Response for error during communication with DS - Status ERR
Response for when DS returns an error message - Status ERM
Request parameters#
The table below describes the request parameters of the transaction creation service:
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
brand_id | Brand ID. Learn more. | = 4 N | YES |
| cardholder.acct | |||
number | Customer's card number (PAN), the encrypted_number, number or token field must always be sent in the request | < 19 N | COND |
token | HASH of a card stored in Carat, the encrypted_number, number or token field must always be sent in the request | = 88 AN | COND |
encrypted_number | [v3] Encrypted customer's card number (PAN), the encrypted_number, number or token field must always be sent in the request | COND | |
| message | |||
version | 3DS message version: 2.1.0 or 2.2.0. | < 8 AN | NO |
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:
| Parameter | Description | Format |
|---|---|---|
three_ds_method_url | Invisible frame URL to be displayed on the customer's browser | < 256 AN |
device_channel | Device channel.
| < 2 N |
message_version | Transaction Version (This version must be used on CRes request) | < 8 AN |
| three_ds_server | ||
trans_id | 3DS Server transaction ID | < 8 AN |
status | 3DS Server Status. Learn more. | = 3 AN |
| acs.protocol_version | ||
start | The earliest (i.e. oldest) active protocol version that is supported by the ACS. | < 8 AN |
end | The most recent active protocol version that is supported by the ACS. | < 8 AN |
| ds.protocol_version | ||
start | The earliest (i.e. oldest) active protocol version that is supported by the DS. | < 8 AN |
end | The most recent active protocol version that is supported by the DS. | < 8 AN |
| error | ||
code | Error code. Learn more. | < 3 N |
component | Indicates which component identified the error.
| = 1 AN |
description | Error description | < 2048 AN |
detail | Error details | < 28 AN |