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.

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

* 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 his public key with e-SiTef, this field is mandatory.

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

The payload for this feature must have the following format:

{
  "merchant_id":"XXXXX",
  "merchant_key": "XXXXXXXXXXXXXXX",
  "cartao": "5555555555555555",
  "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

Parameter	Description	Format	Mandatory
`merchant_id`	Merchant code on e-SiTef.	= 15 AN	YES
`merchant_key`	Merchant authentication key on e-SiTef.	< 80 AN	YES
`cartao`	Customer's card number (PAN).	< 19 AN	YES
`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:

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"
        }
    }
}

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)	< 19 N	YES
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
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