Serviço de criação de transação
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#
- 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 JHVGytfdgauygdauiw78264284527852897hagdg. | < 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:
- Payload utilizando token para esta funcionalidade deverá ter o seguinte formato:
- [Futura v3] Payload utilizando cartão encriptado para esta funcionalidade deverá ter o seguinte formato:
Payload Base64:
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:
Resposta:
Requisição com token:
Resposta:
[Futura v3] Requisição com cartão encriptado:
Resposta:
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.
Resposta com o código de erro 305 e status INV:
Resposta para erro durante a comunicação com o DS - Status ERR
Resposta para quando o DS retorna uma mensagem de erro - Status ERM
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.
| = 1 AN |
description | Descrição do erro | < 2048 AN |
detail | Detalhamento do erro | < 28 AN |