Serviço de criação de transação

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

Essa chamada é necessária para obter o 3DS Method URL correspondente ao cartão e a versão mais atual do 3DS suportada, além de criar uma transação 3DS Server, que será utilizada nos passos seguintes do fluxo.

Importante: O valor do campo message_version devolvido na resposta deve ser utilizado no passo do CREQ (para transações com desafio).

Detalhes da chamada

<ApiDoc method="post" path="/v2/authentication" apiFile="3DS.yaml" />

• Recurso: /v2/authentication
• Método HTTP: POST
• Formato da requisição: JSON
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no 3DS Server. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
merchant_key	Chave de autenticação da loja no 3DS Server. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
Content-Type	Deve ser enviado com o valor application/json.	= 15 AN	SIM
Authorization	Deve ser enviada a assinatura de autenticação da loja no formato Bearer {assinatura}. Exemplo: Bearer {TOKEN_JWT_EXAMPLE}.	< 2000 AN	COND.*
carat_merchant_id	Deve ser enviado código da loja do Carat apenas se for enviado na requisição o campo token	< 15 AN	COND.
carat_merchant_key	Deve ser enviada a chave de autenticação da loja do Carat apenas se for enviado na requisição o campo token	< 80 AN	COND.

* Nota: Por razões de segurança, para que a autenticação da transação seja realizada, é recomendado informar o valor para o campo Authorization.
Caso a loja tenha cadastrado sua chave pública com o Carat, este campo passa a ser obrigatório.

Para informações sobre a futura v3, veja Quick Start.

Bandeiras Suportadas

ID	Nome
1	Visa
2	Mastercard
41	Elo
3	Amex

Geração da assinatura

Para gerar o valor a ser enviado no header Authorization, é necessário:

• Gerar as chaves pública e privada
  • Consulte a página de Autenticação com assinatura, seção Criando as chaves pública e privada.
  • Enviar somente a chave pública para a nossa equipe de suporte, que associará internamente essa chave ao cadastro de sua loja.
• Seguir as instruções de geração de assinatura descritas na página Autenticação com assinatura, seção Algoritmo de assinatura, com exceção da subseção Segunda parte (payload), que será diferente neste caso - ver mais detalhes a seguir.

Payload

É possível gerar a assinatura utilizando 3 payloads diferentes:

• Payload utilizando cartão para esta funcionalidade deverá ter o seguinte formato:

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

• Payload utilizando token para esta funcionalidade deverá ter o seguinte formato:

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

• [Futura v3] Payload utilizando cartão encriptado para esta funcionalidade deverá ter o seguinte formato:

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

Payload Base64:

{TOKEN_JWT_EXAMPLE}

Composição do payload

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no Carat.	= 15 AN	SIM
merchant_key	Chave de autenticação da loja no Carat.	< 80 AN	SIM
cartao	Número do cartão do comprador (PAN), deve ser enviado sempre no payload o campo cartao ou token.	< 19 AN	COND
token	HASH de um cartão armazenado no Carat, deve ser enviado sempre no payload o campo cartao ou token	= 88 AN	COND
timestamp	Representação em milissegundos do momento de geração da assinatura. Enfatizando que o campo timestamp possui um limite de validade de 10 minutos.	< 13 N	SIM

Exemplos

Abaixo estão alguns exemplos de chamada do serviço de criação de transações utilizando a ferramenta cURL.

Requisição com número de cartão:

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

Resposta:

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

Requisição com token:

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":"{SEU_TOKEN}"
      }
   },
   "brand_id":"2"
}
--verbose

Resposta:

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

[Futura v3] Requisição com cartão encriptado:

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":"{SEU_TOKEN}"
      }
   },
   "brand_id":"2"
}
--verbose

Resposta:

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

Erros HTTP 400

Requisição com número de cartão fora do intervalo de cartões suportados (código retorno erro 305 e status INV): Outros inputs inválidos também resultarão no status INV.

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

Resposta com o código de erro 305 e status INV:

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

Resposta para erro durante a comunicação com o 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"
  }
}

Resposta para quando o DS retorna uma mensagem de erro - 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"
  }
}

Parâmetros de requisição

Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de criação de transações:

Parâmetro	Descrição	Formato	Obrigatório
brand_id	ID da bandeira. Saiba mais.	= 4 N	SIM
cardholder.acct
number	Número do cartão do comprador, deve ser enviado sempre na requisição o campo encrypted_number, number ou token	< 19 N	COND
token	HASH de um cartão armazenado no Carat, deve ser enviado sempre na requisição o campo encrypted_number, number ou token	= 88 AN	COND
encrypted_number	[v3] Número encriptado do cartão do comprador, deve ser enviado sempre na requisição o campo encrypted_number, number ou token		COND
message
version	Versão da mensagem 3DS: 2.1.0 ou 2.2.0.	< 8 AN	NÃO

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 201. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de criação de transações:

Parâmetro	Descrição	Formato
three_ds_method_url	URL do frame invisível a ser exibido no navegador do comprador	< 256 AN
device_channel	Canal do dispositivo. Saiba mais.	< 2 N
message_version	Versão utilizada na transação (essa versão deve ser utilizada na requisição do CRes)	< 8 AN
three_ds_server
trans_id	ID da transação 3DS Server	< 8 AN
status	Status no 3DS Server. Saiba mais.	= 3 AN
acs.protocol_version
start	Versão mais antiga de protocolo 3DS suportada pelo ACS	< 8 AN
end	Versão mais recente de protocolo 3DS suportada pelo ACS	< 8 AN
ds.protocol_version
start	Versão mais antiga de protocolo 3DS suportada pelo DS	< 8 AN
end	Versão mais recente de protocolo 3DS suportada pelo DS	< 8 AN
error
code	Código do erro. Saiba mais.	< 3 N
component	Indica qual componente identificou o erro. C = 3DS SDK S = 3DS Server D = DS A = ACS	= 1 AN
description	Descrição do erro	< 2048 AN
detail	Detalhamento do erro	< 28 AN