Autenticar 3DS

Valida a participação do cartão em um programa de autenticação 3DS e confirma os dados da transação. Se a transação se qualificar para um fluxo sem atrito, a resposta retornará o resultado da autenticação 3DS e concluirá o processo de autenticação. Se um fluxo de desafio for necessário, a resposta incluirá os parâmetros necessários para iniciar e executar o challenge 3DS.

Tipos de Autenticação

O fluxo do 3DS pode ocorrer com desafio (challenge) ou sem desafio/atrito (frictionless). No fluxo com desafio, é exigida uma confirmação adicional do portador do cartão, como a validação via aplicativo bancário ou selfie, por exemplo, sendo essa etapa de responsabilidade do emissor. Já o fluxo frictionless autentica o usuário sem a necessidade de um desafio, retornando diretamente os dados de autenticação.

Autenticação sem atrito (frictionless)

O endpoint setup recebe o número do cartão, a data de expiração e o nome do portador, retornando um código de espera de autenticação, um access token e um device data collection.

Esses dados, juntamente com o reference_id e request_id, são usados no endpoint de authentication, que requer informações detalhadas como endereço de cobrança, dados do navegador e informações da compra.

Exemplo de retorno no authentication:

HTTP Response
  {
    "code": "ACCEPTED",
    "access_token": "string",
    "device_data_collection_url": "https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect",
    "reference_id": "963341e8-b4d9-405c-9f59-80065c339563",
    "request_id": "42C46CD74D1845D698107DAAD84875DF20240222154543979"
  }

Autenticação com desafio (challenge)

Se a autenticação indicar a necessidade de um desafio, o endpoint de authenticaion retornará WAITING_3DS_AUTHENTICATION, e o cliente precisará fornecer dados do navegador via device information.

O processo envolve um callback para uma URL do cliente(return_url), onde a resposta do desafio é recebida de um provedor terceiro.

Sugerimos a utilização de um webhook para que a URL de callback receba a resposta do 3DS. Essa URL não precisa ser registrada previamente, apenas informada na return_url.

Após o desafio ser concluído, os dados recebidos via webhook devem ser usados para chamar o endpoint /v1/card_payments/threeds_challenge_result, que retornará os dados finais do 3DS para uso na venda, que devem ser passados no objeto three_ds_data.

Fazendo Requisição

A chamada deverá ser feita utilizando o método POST.

POST/v1/card_payments/threeds_authentication

Campos da Requisição

Campo	Tipo	Descrição	Obrigatório
`card_number`	string	O número do cartão que será autenticado. Obrigatório apenas em transações sem `slug_token` e `slug_stored_card`.	Sim
`card_expiration_date`	string	Data de validade do cartão. Obrigatório apenas em transações sem `slug_token` e `slug_stored_card`.	Sim
`card_holder_name`	string	Nome do titular do cartão conforme impresso no cartão. Obrigatório somente em transações sem `slug_token` e `slug_stored_card`.	Sim
`slug_token`	string	Uma sequência alfanumérica de 32 caracteres que representa um cartão tokenizado pelo endpoint `/v1/card_payments/tokenize_card`. Pode ser usada em vez de `card_number`, `card_expiration_date` e `card_holder_name`.	Parcial
`slug_stored_card`	string	Uma sequência alfanumérica de 32 caracteres que representa um cartão tokenizado pelo endpoint `/v1/card_payments/tokenize_card`. Pode ser usada em vez de `card_number`, `card_expiration_date` e `card_holder_name`.	Parcial
`request_id`	string	ID da solicitação para a transação de autenticação.	Sim
`reference_id`	string	Valor de referência da transação de autenticação.	Sim
`sale_type`	string	Especifica com qual tipo de conta a transação deve ser processada. permitidos: `CREDIT` ou `DEBIT`	Sim
`amount`	string	O valor total da transação.	Sim
`currency`	string	Moeda da transação. permitidos: `BRL`	Sim
`street`	string	Rua	Sim
`neighborhood`	string	Bairro	Sim
`state`	string	Estado	Sim
`country`	string	Abreviação do País Exemplo: `BR`, `USA`	Sim
`city`	string	Cidade	Sim
`zip_code`	string	CEP	Sim
`first_name`	string	Primeiro nome do proprietário do cartão	Sim
`last_name`	string	Sobrenome do proprietário do cartão	Sim
`phone_number`	string	Número de celular do titular do cartão com código de país e área. Exemplo: `+5511989999999`	Sim
`email`	string	email do proprietário do cartão	Sim
`transaction_mode`	string	Identifica o canal de onde a transação se origina. Permitidos: `M: MOTO (Mail Order Telephone Order)`, `R: Retail`, `S: eCommerce`, `P: Mobile Device`, `T: Tablet`	Não
`acs_window_size`	string	Defina o tamanho da janela de desafio a ser exibida ao titular do cartão final. Permitidos: `01` for 250x400, `02` for 390x400, `03` for 500x600, `04` for 500x600, `05` for Full Page	Não
`device_channel`	string	Determina o canal pelo qual a transação ocorreu. Permitidos: `SDK`, `Browser`, `3RI`	Sim
`http_browser_java_enabled`	boolean	Se o Java estiver habilitado no navegador.	Sim
`http_browser_language`	string	Idioma do navegador.	Sim
`http_browser_color_depth`	string	Profundidade de cor do navegador.	Sim
`http_browser_screen_height`	string	Altura da tela do navegador.	Sim
`http_browser_screen_width`	string	Largura da tela do navegador.	Sim
`http_browser_time_difference`	string	Diferença de tempo entre o horário UTC e o horário local do navegador do titular do cartão, em minutos.	Sim
`user_agent_browser`	string	Valor do cabeçalho User-Agent enviado pelo navegador do cliente.	Sim
`http_accept_content`	string	O cabeçalho HTTP 'Accept' do navegador do usuário, indicando os tipos de conteúdo suportados.	Sim
`merchant_url`	string	Endereço do site da empresa fornecido pelo comerciante.	Sim
`return_url`	string	URL para recuperação do TransactionId após a conclusão do desafio. Esta informação será necessária para recuperar o resultado do desafio.	Sim

HTTP Request Body
  {
    "slug_token": "abc123xyz",
    "slug_stored_card": "stored-card-789",
    "card_number": "4111111111111111",
    "card_expiration_date": "122028",
    "card_holder_name": "John Doe",
    "request_id": "42C46CD74D1845D698107DAAD84875DF20240222154543979",
    "reference_id": "963341e8-b4d9-405c-9f59-80065c339563",
    "sale_type": "CREDIT",
    "amount": 15075,
    "currency": "BRL",
    "street": "Rua A 1",
    "neighborhood": "Bairro 1",
    "state": "SP",
    "country": "BR",
    "city": "São Paulo",
    "first_name": "Jon",
    "last_name": "Doe",
    "phone_number": "+5581989999999",
    "email": "john@example.com",
    "zip_code": "00000000",
    "transaction_mode": "M: MOTO (Mail Order Telephone Order)",
    "acs_window_size": "01 for 250x400",
    "device_channel": "Browser",
    "http_browser_java_enabled": false,
    "http_browser_language": "pt-BR",
    "http_browser_color_depth": 24,
    "http_browser_screen_height": 1080,
    "http_browser_screen_width": 1920,
    "http_browser_time_difference": 300,
    "user_agent_browser": "Mozilla/5.0 (Macintosh; Intel Mac OS X 15_5)",
    "http_accept_content": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
    "merchant_url": "https://lojaexemplo.com.br/checkout",
    "return_url": "https://lojaexemplo.com.br/pagamento/retorno"
  }

Campos da Resposta

Campo	Tipo	Descrição
`code`	string	Código de resposta do resultado da transação. exemplos: `WAITING_3DS_AUTHENTICATION`, `ACCEPTED`
`msg`	string	Mensagem de resposta do resultado da transação.
`access_token`	string	Caso o desafio seja necessário, este token deve ser enviado para iniciá-lo.
`step_up_url`	string	Caso o desafio seja necessário, esta é a URL para iniciá-lo.
`authentication_id`	string	Caso o desafio seja necessário, este ID deve ser enviado para iniciá-lo.
`iframe_dimensions`	object	Caso o desafio seja necessário, estas devem ser as dimensões do iframe em que o desafio será realizado.
`iframe_dimension_width`	string	Largura do iframe
`iframe_dimension_height`	string	Altura do iframe
`cavv`	string	O valor de autenticação do titular do cartão para a sessão de autenticação 3D Secure.
`xid`	string	O identificador de transação atribuído pelo Directory Server para autenticação. Only used for Visa transactions.
`specification_version`	string	A versão 3DS usada para autenticação.
`directory_server_transaction_id`	string	O ID da transação do servidor de diretório é gerado pelo servidor de diretório durante a autenticação.
`three_ds_server_transaction_id`	string	O ID de transação do servidor threeDS é gerado pelo servidor de diretório durante a autenticação.
`multiacq_id`	string	Um identificador para o autorizador.

Sucesso

Exemplo de Resposta - Frictionless

Após a chamada, é retornado um JSON com o status 200.

HTTP 200 Response Body - Exemplo
{
  "code": "ACCEPTED",
  "xid": "AJkBBkhgQQAAAE4gSEJydQAAAAA=",
  "cavv": "AJkBBkhgQQAAAE4gSEJydQAAAAA=",
  "specification_version": "2.2.0",
  "directory_server_transaction_id": "318d16b4-f741-45f2-8f0a-026c4b79a596",
  "authentication_id": "7612476846306645104807",
  "multiacq_id": "001"
}

Exemplo de Resposta - Challenge

Após a chamada, é retornado um JSON com o status 200.

Quando a transação exigir autenticação adicional por parte do portador do cartão (3-D Secure), a API retornará uma resposta com o seguinte formato:

HTTP 200 Response Body - Exemplo
{
  "code": "WAITING_3DS_AUTHENTICATION",
  "msg": "CONSUMER_AUTHENTICATION_REQUIRED : The cardholder is enrolled in Payer Authentication. Please authenticate the cardholder before continuing with the transaction.",
  "access_token": "5ecCI6IkpXVJhbGciOiJIUzI1NyRiIsInCJ9.eyJqdGkiOiIyMjkxYmNhYS02NDMxNDIsImlzcyI6IjVkZDgzYmYwMGU0MjNkMTQ5OGRjYmFjYSIsImV4cCIM2ZmE0YjkzNmI5MGQ2IiwiUGF5bG9hZCI6eyJBQ1NVcmwiOiJodHRwczovLzBtZXJjaGFudGFjc3N0YWcuY2FyZGluYWxjb21tZXJjZS5jb20vTWVyY2hhbnRBQ1NXZWIvY3JlcS5qc3AiLCJQYXlsb2FkIzNDI1LTRkMTktOTdlNy1mNDU5ZmIxNjM4MGIiLCJpYXQiOjE3NjAjoiZXlKdFp6MTc2MDY0Njc0MiwiT3JnVW5pdElkIjoiNjQ3NTA0ZmQ2NWYTnpZV2RsVkhsd1pTSTZJa05TWlhFaUxDSnRaWE56WVdkbFZtVnljMmx2YmlJNklqSXVNUzR3SWl3aWRHaHlaV1ZFVlMwMFpXUmxMVGs1TWpNdE1UbGtObUU0WldVeE1EQmlJaXdpWTJoaGJHeGxibWTFObGNuWmxjbFJ5WVc1elNVUWlPaUl3WldNM1l6YzFNeTAwWW1aaUxUUTJPVGd0WVRabVpTMWxaRGxrTVRoaU56SmxNMllpTENKaFkzTlVjbUZ1YzBsRUlqb2lZbVUxT1dKbE9URXRPVGt6TRsVjJsdVpHOTNVMmw2WlNJNklqQXlJbjAiLCJUcmFuc2FjdGlvbklkIjoiZFpzejBBWlhYNmhvWVZCSmhWazAifSwiT2JqZWN0aWZ5UGF5bG9hZCI6dHJ1ZSwiUmV0dXJuVXJsIjoiaHR0cDovL3Rlc3RlLnRocmVlZHMuY29tL2NoYWxsZW5nZSJ9._-Ocb9KJyusTaXx_gPMRSZFKEGAt5x0",
  "step_up_url": "https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp",
  "authentication_id": "7606431418396443903814",
  "iframe_dimensions": {
    "iframe_dimension_width": "390",
    "iframe_dimension_height": "400"
  },
  "multiacq_id": "001"
}

Esta resposta indica que o emissor do cartão solicitou um desafio de autenticação 3-D Secure (3DS Step-Up).

O cliente(comerciante) deve utilizar os dados fornecidos para apresentar a etapa de autenticação ao portador do cartão antes de prosseguir com a autorização da transação.

Deve ser exibido a tela de autenticação 3DS em um iframe seguro dentro de seu ambiente (checkout, aplicação ou página web), utilizando os parâmetros fornecidos.

Passo a passo(desafio):

Receber a resposta com WAITING_3DS_AUTHENTICATION.
Renderizar um iframe com as dimensões informadas (iframe_dimensions) e carregar a URL de autenticação (step_up_url).
Incluir o access_token no corpo da requisição ou como parâmetro da chamada ao endpoint 3DS, conforme especificação do provedor.
Aguardar o resultado da autenticação (sucesso, falha ou cancelamento).
Prosseguir com a autorização da transação somente após a conclusão do desafio.
Após o desafio concluído com sucesso, uma chamada será feita para o return_url fornecido, informando o transactionId

Erros

Em caso de erros, será retornado um json com o atributo error especificando o motivo de a operação ter sido invalidada.

HTTP 400 Response Body - Exemplo
{
  "errors": [
    {
      "code": "MSG_NOT_SUPPORTED",
      "msg": "Not supported"
    }
  ],
  "request_token": "EE4F8B5BC25A46B080F11D34B9CFAFFF",
  "multiacq_id": "001"
}

HTTP 422 Response Body - Exemplo
{
  "errors": [
    {
      "code": "INVALID_INPUT_CARD_METHOD",
      "msg": "request must include only slugToken, slugStoredCard, or card data. Please refer to the documentation."
    }
  ],
  "request_token": "7C2E9D3869F34F3CA5CC2C5CFAB4B6E2",
  "transaction_status": "REJECTED",
  "multiacq_id": "001"
}

Tipos de Autenticação​

Autenticação sem atrito (frictionless)​

Autenticação com desafio (challenge)​

Fazendo Requisição​

Sucesso​

Exemplo de Resposta - Frictionless​

Exemplo de Resposta - Challenge​

Erros​