Serviço de autenticação
Após a criação da transação, é necessário chamar o serviço de autenticação para dar continuidade ao fluxo. Caso seja retornado o status AUC, será preciso iniciar um desafio. Para o status AUD, deve ser seguido o fluxo "decoupled". Nos demais casos, não serão necessárias mais chamadas.
Detalhes da chamada#
- Recurso:
/v2/authentication/{ID da transação 3DS Server} - Método HTTP:
PUT - 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 |
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. |
Exemplos#
Abaixo estão alguns exemplos de chamada do serviço de autenticação utilizando a ferramenta cURL.
Fluxo Frictionless#
Requisição com número de cartão:
Resposta:
Requisição com token:
Resposta:
Fluxo Challenge#
Requisição:
Resposta:
Parâmetros de requisição#
Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de autenticação:
| Parâmetro | Descrição | Formato | Obrigatório |
|---|---|---|---|
device_channel | Canal do dispositivo. Valor padrão: 02corresponde a Browser (BRW). Saiba mais. | = 2 N | SIM |
three_ri_ind | Indica o tipo de requisição 3RI.
device_channel = 03. | = 2 N | COND. |
three_ds_comp_ind | Indica se o 3DS Method foi executado com sucesso.
device_channel = 02. | = 1 A | COND. |
pay_token_ind | O valor true indica que a transação foi "destokenizada" antes do recebimento pelo ACS. | < 5 AN | NÃO |
pay_token_source | Indica onde ocorreu a "destokenização".
| = 2 N | NÃO |
notification_url | URL completa do 3DS Requestor para receber a mensagem CRes. Campo obrigatório para device_channel = 02. | < 256 AN | COND. |
trans_type | Identifica o tipo de transação sendo autenticada.
| = 2 N | SIM |
broad_info | Informação não-estruturada enviada entre 3DS Server, DS e ACS. | Object | NÃO |
| three_ds_requestor | |||
authentication_ind | Indica o tipo da requisição de autenticação.
| = 2 N | SIM |
challenge_ind | Este campo sinaliza a preferência do comércio para a realização (ou não) do desafio mas, a menos que as partes estejam alinhadas, o emissor pode não acatar esta solicitação. Caso este campo não seja enviado, será interpretado como “01 = Sem preferência”
| = 2 N | NÃO |
id | Identificador do 3DS Requestor designado pelo DS. | < 35 AN | SIM |
name | Nome do 3DS Requestor designado pelo DS. | < 40 AN | SIM |
url | URL completa do site do 3DS Requestor ou site de atendimento ao cliente. | < 2048 AN | SIM |
| three_ds_requestor. authentication_info | Informações sobre como o 3DS Requestor autenticou o portador do cartão antes ou durante a transação. | ||
data | Dado que documenta e auxilia um processo específico de autenticação. | < 20000 AN | NÃO |
method | Mecanismo usado pelo portador do cartão para se autenticar no 3DS Requestor.
| = 2 N | NÃO |
timestamp | Data e hora UTC da autenticação do portador em formato AAAAMMDDHHMM. | = 12 N | NÃO |
| three_ds_requestor. prior_authentication_info | Informações sobre como o 3DS Requestor autenticou o portador do cartão como parte de uma transação 3DS prévia. | ||
data | Dado que documenta e auxilia um processo específico de autenticação. | < 2048 AN | NÃO |
method | Mecanismo usado anteriormente pelo portador para se autenticar no 3DS Requestor.
| = 2 N | NÃO |
timestamp | Data e hora UTC da autenticação prévia do portador em formato AAAAMMDDHHMM. | = 12 N | NÃO |
reference | Este elemento fornece informações adicionais para que o ACS determine a melhor forma de tratar uma requisição. | < 36 AN | NÃO |
| acquirer | |||
bin | Código da rede adquirente conforme definida pelo DS. | < 11 AN | SIM |
merchant_id | Identificador da loja designado pelo adquirente. | < 35 AN | SIM |
| browser | Estes parâmetros são obrigatórios caso device_channel = 02. | ||
accept_header | Conteúdo exato do cabeçalho HTTP "Accept" conforme enviado para o 3DS Requestor pelo navegador do comprador. | < 2048 AN | COND. |
ip | Endereço IP do comprador. | < 45 AN | COND. |
java_enabled | Valor booleano que representa a habilidade do navegador do comprador em executar Java. Este valor é retornado pela propriedade navigator.javaEnabled. | < 5 AN | COND. |
javascript_enabled | Valor booleano que representa a habilidade do navegador do portador em executar JavaScript. | < 5 AN | COND. |
language | Valor que representa a linguagem do navegador conforme definido na IETF BCP47. Retornado pela propriedade navigator.language. | < 8 AN | COND. |
color_depth | Valor que representa a quantidade bits de cor para exibição de imagens, em bits por pixel. Valor obtido pela propriedade screen.colorDepth.
Observação: Se o valor na request for diferente dos especificados acima, será selecionado o valor mais próximo, sempre optando pelo menor. Ex.:30 vai ser 24 | < 2 N | COND. |
screen_height | Altura da tela do portador. Valor retornado pela propriedade screen.height. | < 6 N | COND. |
screen_width | Comprimento da tela do portador. Valor retornado pela propriedade screen.width. | < 6 AN | COND. |
tz | Fuso horário em minutos entre UTC e o horário do navegador do comprador. Valor retornado pelo método getTimezoneOffset(). | < 5 AN | COND. |
user_agent | User agent do comprador. | < 2048 AN | COND. |
| cardholder | |||
card_expiry_date | Data de validade do cartão no formato AAMM. | = 4 N | SIM |
addr_match | Indica se o endereço de entrega e de cobrança do portador são iguais.
| = 1 AN | NÃO |
email | Embora não seja obrigatório, é recomendável enviar esse campo, pois ajuda na avaliação de risco – aumentando as chances de se obter uma autenticação silenciosa. | < 256 AN | SIM |
name | Nome do portador. | < 45 AN | SIM |
| cardholder. home_phone | Número de telefone residencial do portador. | ||
cc | DDI | < 3 N | SIM |
subscriber | DDD + Telefone | < 15 N | SIM |
| cardholder. mobile_phone | É recomendável enviar esse campo, pois ajuda na avaliação de risco, aumentando as chances de se obter uma autenticação silenciosa. | ||
cc | DDI | < 3 N | SIM |
subscriber | DDD + Telefone | < 15 N | SIM |
| cardholder. work_phone | Número de telefone comercial do portador. | ||
cc | DDI | < 3 N | SIM |
subscriber | DDD + Telefone | < 15 N | SIM |
| cardholder. acct | |||
type | Indica o tipo de conta. Por exemplo, para um cartão múltiplo.
| = 2 N | SIM |
number | Número do cartão (PAN), deve ser enviado sempre na requisição o campo number ou token | < 19 N | COND |
token | HASH de um cartão armazenado no Carat, deve ser enviado sempre na requisição o campo number ou token | = 88 AN | COND |
id | Informações adicionais sobre a conta fornecidas opcionalmente pelo 3DS Requestor. | < 64 AN | NÃO |
| cardholder. acct. info | |||
ch_acc_age_ind | Período de tempo que o portador teve conta no 3DS Requestor.
| = 2 N | NÃO |
ch_acc_change | Data da última alteração da conta do comprador em formato AAAAMMDD. | = 8 N | NÃO |
ch_acc_change_ind | Período de tempo desde a última alteração na conta do portador.
| = 2 N | NÃO |
ch_acc_date | Data em que o portador abriu a conta no 3DS Requestor no formato AAAAMMDD. | = 8 N | NÃO |
ch_acc_pw_change | Data em que o comprador alterou sua senha no formato AAAAMMDD. | = 8 N | NÃO |
ch_acc_pw_change_ind | Indica o período de tempo desde a última alteração de senha do portador.
| = 2 N | NÃO |
nb_purchase_account | Número de compras com esta conta durante os últimos 6 meses. | < 4 N | NÃO |
provision_attempts_day | Número de tentativas de adição de cartão nas últimas 24 horas. | < 3 N | NÃO |
txn_activity_day | Número de transações (confirmadas e abandonadas) para este portador com o 3DS Requestor nas últimas 24 horas. | < 3 N | NÃO |
txn_activity_year | Número de transações (confirmadas e abandonadas) para este portador com o 3DS Requestor no último ano. | < 3 N | NÃO |
payment_acc_age | Data em que a conta de pagamento foi registrada na conta do portador com o 3DS Requestor no formato AAAAMMDD. | = 8 N | NÃO |
payment_acc_ind | Indica o período de tempo que a conta de pagamento foi registrada no 3DS Requestor.
| = 2 N | NÃO |
ship_address_usage | Data do primeiro uso do endereço de entrega no formato AAAAMMDD. | = 8 N | NÃO |
ship_address_usage_ind | Indica quando foi primeiramente utilizado o endereço de entrega.
| = 2 N | NÃO |
ship_name_indicator | Indica se nome do portador do cartão é idêntico ao nome de entrega utilizada para esta transação.
| = 2 N | NÃO |
suspicious_acc_activity | Indica se o 3DS Requestor teve experiências suspeitas (incluindo fraude prévia) com a conta do comprador.
| = 2 N | NÃO |
| cardholder. bill_addr | Endereço de cobrança do portador. | ||
city | Cidade. | < 50 AN | SIM |
country | Código numérico ISO 3166-1 de três dígitos do país. | = 3 N | SIM |
line1 | Primeira linha do endereço. | < 50 AN | SIM |
line2 | Segunda linha do endereço. | < 50 AN | SIM |
line3 | Terceira linha do endereço. | < 50 AN | SIM |
post_code | CEP. | < 16 AN | SIM |
state | Sigla do estado. | < 3 AN | SIM |
| cardholder. ship_addr | Endereço de entrega do portador. | ||
city | Cidade. | < 50 AN | SIM |
country | Código numérico ISO 3166-1 de três dígitos do país. | = 3 N | SIM |
line1 | Primeira linha do endereço. | < 50 AN | SIM |
line2 | Segunda linha do endereço. | < 50 AN | SIM |
line3 | Terceira linha do endereço. | < 50 AN | SIM |
post_code | CEP. | < 16 AN | SIM |
state | Sigla do estado. | < 3 AN | SIM |
| merchant | |||
mcc | Código específico do DS que descreve o tipo de negócio/produto/serviço da loja. Antes de enviar a requisição para o DS, o 3DS verifica automaticamente o tamanho do campo mcc inserido. Se o tamanho for menor que 4 caracteres, o 3DS adicionará zeros à esquerda até que o campo atinja um tamanho total de 4 caracteres. | = 4 N | SIM |
country_code | Código numérico ISO 3166-1 de três dígitos do país da loja. | = 3 N | SIM |
name | Nome da loja designado pelo adquirente ou sistema de pagamento. | < 40 AN | SIM |
| merchant. risk_indicator | Avaliação da loja sobre o nível de risco de fraude para a autenticação específica para o portador e a autenticação sendo conduzida. | ||
delivery_email_address | Para entrega eletrônica, o endereço de e-mail para qual a mercadoria foi entregue. | < 254 AN | NÃO |
delivery_timeframe | Indica o período de tempo de entrega da mercadoria.
| = 2 N | NÃO |
gift_card_amount | Para compra com cartão presente ou pré-pago, o valor total da compra em números inteiros (por exemplo, 123.45 é 123). | < 15 N | NÃO |
gift_card_count | Para compra com cartão presente ou pré-pago, contagem de cartões pré-pagos/presentes comprados. | < 2 N | NÃO |
gift_card_curr | Para compra com cartão presente ou pré-pago, código de moeda ISO 4217 de três dígitos do cartão presente. | = 3 N | NÃO |
pre_order_date | Para uma pré-venda, a data esperada de disponibilidade da mercadoria no formato AAAAMMDD. | = 8 N | NÃO |
pre_order_purchase_ind | Indica se o portador está fazendo um pedido para uma mercadoria com disponibilidade futura.
| = 2 N | NÃO |
reorder_items_ind | Indica se o portador está pedindo uma mercadoria comprada anteriormente.
| = 2 N | NÃO |
ship_indicator | Indica a forma de entrega escolhida para a transação.
| = 2 N | NÃO |
| message | |||
category | Identifica a categoria da mensagem para um caso de uso específico.
| = 2 N | SIM |
| message. extension[] | Dados necessários para auxiliar em requisitos não definidos na mensagem 3DS são carregados numa extensão de mensagem. | ||
criticality_indicator | Um valor booleano que indica se o destinatário deve entender os conteúdos da extensão para interpretar a mensagem inteira. | < 5 AN | NÃO |
data | Dados carregados na extensão. | Object | NÃO |
id | Identificador único da extensão. | < 64 AN | NÃO |
name | Nome da extensão. | < 64 AN | NÃO |
| purchase | |||
amount | Valor total da compra em centavos. | < 48 N | SIM |
currency | Código da moeda ISO 4217 de três dígitos da compra. | = 3 N | SIM |
exponent | Número de casas decimais da moeda conforme definido na ISO 4217. | = 1 N | SIM |
date | Data e hora UTC da compra no formato AAAAMMDDHHMMSS. | = 12 N | SIM |
instal_data | Número máximo de parcelas da compra. O valor deve ser maior que 1. | < 3 N | NÃO |
| recurring | Dados para transações recorrentes. | ||
expiry | Data em que não serão feitas mais autorizações no formato AAAAMMDD. Obrigatório quando three_ds_requestor. authentication_ind = 02 ou 03. | = 8 N | COND. |
frequency | Indica o número mínimo de dias entre autorizações. Obrigatório quando three_ds_requestor. authentication_ind = 02 ou 03. | < 4 N | COND. |
| sdk | Estes campos são obrigatórios para 3DS SDKs (device_channel = 01). | ||
app_id | GUID criado para todas as instalações do aplicativo do 3DS Requestor num dispositivo do consumidor. Este será gerado e armazenado pelo 3DS SDK para cada instalação. | = 36 AN | COND. |
enc_data | Objeto JWE (representado como uma string) contendo dados criptografados pelo SDK para que o DS descriptografe. | < 64000 AN | COND. |
ephem_pub_key | Chave pública gerada pelo 3DS SDK para comunicação com o ACS. | Object | COND. |
max_timeout | Indica o máximo de tempo (em minutos) para cada troca de mensagem. | < 2 N | COND. |
trans_id | GUID da transação do 3DS SDK. | = 36 AN | COND. |
iface | Lista todos os tipos de interface SDK suportadas pelo dispositivo para exibição de interfaces específicas de desafio.
| = 2 N | COND. |
ui_type[] | Lista todos os tipos de interface de usuário que o dispositivo suporta para exibição de interfaces específicas de desafio dentro da SDK.
| = 2 N[] | COND. |
| white_list | |||
status | Permite a comunicação de status de lista branca entre ACS, DS e 3DS Requestor.
| = 1 AN | NÃO |
status_source | Este campo será preenchido pelo sistema que configura o status de lista branca.
| = 2 N | NÃO |
Parâmetros de resposta#
Em caso de sucesso, o código de resposta HTTP será 200. 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 autenticação:
| Parâmetro | Descrição | Formato |
|---|---|---|
eci | Electronic Commerce Indicator | = 2 N |
broad_info | Informação não-estruturada enviada entre 3DS Server, DS e ACS. | Object |
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 | = 36 AN |
status | Status no 3DS Server. Saiba mais. | = 3 AN |
| acs | ||
challenge_mandated | Indicação de caso o desafio é requerido para a transação a ser autorizada.
| = 1 AN |
operator_id | Identificador do ACS designado pelo DS. | < 32 AN |
reference_number | Identificador único designado pela EMVCo. | < 32 AN |
trans_id | ID da transação no ACS. | = 36 AN |
url | URL completa de desafio do ACS. | < 2048 AN |
decoupled_confirmation_ind | Indica se o ACS confirma a utilização de autenticação decoupled e concorda com o seu uso para autenticar o comprador.
| = 1 AN |
signed_content | Contém o objeto JWS criado pelo ACS para a mensagem ARes. | var. AN |
iface | Esta é a interface ACS em que o desafio será apresentado ao portador.
| = 2 N |
ui_template | Identifica o formato de interface de usuáro que o ACS apresenta primeiramente ao consumidor.
| = 2 N |
| authentication | ||
type | Indica o tipo de forma de autenticação que o emissor utilizará para desafiar o portador.
| = 2 N |
value | Valor específico ao sistema de pagamento fornecido pelo ACS ou o DS usando um algoritmo definido pelo sistema de pagamento. Valor de autenticação que será usado para fornecer prova de autenticação (CAVV). | = 28 AN |
| cardholder | ||
info | Texto fornecido pelo ACS/Emissor para o portador do cartão durante uma transação frictionless ou decoupled. | < 128 AN |
| ds | ||
reference_number | Identificador único do DS designado pela EMVCo. | < 32 AN |
trans_id | ID da transação no DS. | = 36 AN |
| message. extension[] | Dados necessários para auxiliar em requisitos não definidos na mensagem 3DS são carregados numa extensão de mensagem. | |
criticality_indicator | Um valor booleano que indica se o destinatário deve entender os conteúdos da extensão para interpretar a mensagem inteira. | < 5 AN |
data | Dados carregados na extensão. | Object |
id | Identificador único da extensão. | < 64 AN |
name | Nome da extensão. | < 64 AN |
| transaction | ||
status | Status da transação segundo o protocolo 3DS 2.0.
| = 1 AN |
status_reason | Fornece informação sobre o motivo do valor do transaction.status.
| = 2 N |
| white_list | ||
status | Permite a comunicação de status de lista branca entre ACS, DS e 3DS Requestor.
| = 1 AN |
status_source | Este campo será preenchido pelo sistema que configura o status de lista branca.
| = 2 N |
| sdk | ||
trans_id | ID da transação 3DS SDK. | = 36 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 |