Transaction creation service

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:

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 {TOKEN_JWT_EXAMPLE}`.	< 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 Authorization field.
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:

{
   "cardholder":{
      "acct":{
         "number":"1234123412341234"
      }
   },
   "brand_id":"2"
}

Payload using token for this functionality must have the following format:

{
   "cardholder":{
      "acct":{
         "token":"er334gvdgdf5dfgdfg63456363434tre345353rg34tb4576jfgrtu464jj56j56u56u56ghhrthrhrthrth467"
      }
   },
   "brand_id":"2"
}

[Future v3] Payload using encrypted card number for this functionality must have the following format:

{
   "cardholder":{
      "acct":{
         "encrypted_number":"er334gvdgdf5dfgdfg63456363434tre345353rg34tb4576jfgrtu464jj56j56u56u56ghhrthrhrthrth467"
      }
   },
   "brand_id":"2"
}

Payload Base64:

{TOKEN_JWT_EXAMPLE}

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

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 {TOKEN_JWT_EXAMPLE}'
--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 {TOKEN_JWT_EXAMPLE}'
--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"
}

[Future v3] Request with encrypted 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 "Client-Request-Id: a5179032-71cf-4320-b171-69629b1db4b8"
--header "Auth-Token-Type: HMAC"
--header "Authorization: {HMAC signature}"
--header "api-key: {HMAC key}"
--data-binary
{
   "cardholder":{
      "acct":{
         "encrypted_number":"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"
}

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.

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 {TOKEN_JWT_EXAMPLE}'
--data-binary
{
   "cardholder":{
      "acct":{
         "number":"1111120000001000"
      }
   },
   "brand_id":"2"
}
--verbose

Response with error code 305 and INV status:

{
  "three_ds_server": {
    "trans_id": "9f289031-3f9e-4874-afa8-db6fb7a4207c",
    "status": "INV"
  },
  "device_channel": "02",
  "error": {
    "code": "305",
    "component": "S",
    "description": "Cardholder Account Number is not in a range belonging to Issuer",
    "detail": "acctNumber"
  }
}

Response for error during communication with DS - Status ERR

{
  "three_ds_server": {
    "trans_id": "9f289031-3f9e-4874-afa8-db6fb7a4207c",
    "status": "ERR"
  },
  "device_channel": "02",
  "error": {
    "code": "405",
    "component": "S",
    "description": "DS communication failure",
    "detail": "acctNumber"
  }
}

Response for when DS returns an error message - Status ERM

{
  "three_ds_server": {
    "trans_id": "9f289031-3f9e-4874-afa8-db6fb7a4207c",
    "status": "ERM"
  },
  "device_channel": "02",
  "error": {
    "code": "",
    "component": "S",
    "description": "3DS Server received an error message from DS",
    "detail": "acctNumber"
  }
}

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. `01` = application (APP) `02` = browser (BRW)	< 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. `C` = 3DS SDK `S` = 3DS Server `D` = DS `A` = ACS	= 1 AN
`description`	Error description	< 2048 AN
`detail`	Error details	< 28 AN