# 3-D Secure (3DS) (/docs/cartao/three-d-secure) O **3DS** confirma junto ao banco emissor que quem está comprando é o titular do cartão. Autenticar a transação reduz fraude e, quando a autenticação conclui com sucesso, transfere a responsabilidade por chargeback para o emissor ou a bandeira. Durante o processo de autenticação 3DS, informações do comprador são compartilhadas com as bandeiras e o banco emissor, que avaliam o risco da transação e definem se é necessário um **desafio** (como um código por SMS ou autenticação no app do banco) para validar a identidade do portador. ### Vantagens [#vantagens] * Redução de fraudes * **Shift de responsabilidade (liability shift)** nas transações autenticadas: o emissor ou a bandeira assumem a responsabilidade em caso de chargeback * Integração simples via JavaScript * Suporte à autenticação **sem fricção** (sem desafio visível para o comprador), quando o risco da transação é considerado baixo ## Fluxo de autenticação [#fluxo-de-autenticação] Quando a transação é autorizada com as variáveis retornadas no evento `success`, a responsabilidade (liability) é transferida para o emissor do cartão. Nos demais cenários, a responsabilidade permanece com o estabelecimento. ## Integração passo a passo [#integração-passo-a-passo] ### Inicializar o script [#inicializar-o-script] Inclua o seguinte script em sua página web para carregar o script responsável por realizar a comunicação com as bandeiras e os bancos emissores: ```html ``` Após carregar o script em sua página, será necessário inicializá-lo da seguinte maneira: ```javascript const config = { amount: 350, currency: 'BRL', options: { enabled: true, sandbox: true, debug: true, suppressChallenge: false } }; payzu3DS.init(config); ``` | Parâmetro | Descrição | Tipo | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- | | `amount` | Valor total da transação em centavos | inteiro | | `currency` | Código da moeda | Fixo em "BRL" | | `options.enabled` | Define se a transação será submetida ao processo de autenticação 3DS | boolean | | `options.sandbox` | Define se o ambiente de execução utilizado será o sandbox ou de produção | boolean | | `options.debug` | Quando ativado, logs e relatórios serão emitidos no console do navegador | boolean | | `options.suppressChallenge` | Determina se o desafio será suprimido. Caso o desafio seja ignorado e a transação autorizada, a responsabilidade (liability) permanece com o estabelecimento | boolean | ### Registrar os eventos de autenticação [#registrar-os-eventos-de-autenticação] Registre os listeners dos eventos para tratar cada resultado possível da autenticação: ```javascript payzu3DS.on("ready", function (e) { }); ``` #### ready [#ready] Este evento é acionado quando todos os procedimentos de carregamento do script foram concluídos com sucesso, incluindo a validação do token de acesso. Indica que o checkout está pronto para iniciar o processo de autenticação. #### Resultados da autenticação [#resultados-da-autenticação] O liability shift ocorre somente quando a autenticação é concluída com sucesso: nesse caso, a responsabilidade por chargeback é transferida ao emissor ou à bandeira. Em todos os demais cenários, a responsabilidade permanece com o estabelecimento. | Evento | Cenário e retorno | Liability | Ação recomendada | | ------------ | ---------------------------------------------------------------------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------- | | `success` | Cartão elegível e autenticação concluída com sucesso. Retorna `Cavv`, `Xid` e `Eci`. | Transferida ao emissor | Inclua `Cavv`, `Xid` e `Eci` na requisição de autorização. | | `failure` | Cartão elegível, mas a autenticação falhou. Retorna apenas `Eci`. | Permanece com o estabelecimento | Se decidir prosseguir com a autorização, inclua `Eci` na requisição. | | `unenrolled` | Cartão não elegível: o portador e/ou o emissor não participam do programa 3DS. Retorna apenas `Eci`. | Permanece com o estabelecimento | Oriente o comprador a verificar com o emissor se o cartão está habilitado para autenticação em e-commerce. | | `disabled` | Estabelecimento optou por não autenticar, com `options.enabled` como `false`. | Permanece com o estabelecimento | - | | `error` | Erro sistêmico no processo de autenticação. | Permanece com o estabelecimento | - | #### unsupportedBrand [#unsupportedbrand] Este evento é acionado quando a bandeira do cartão utilizado não é compatível com o protocolo 3DS. Nesse caso, a autenticação não é realizada. #### Atributos retornados [#atributos-retornados] | Atributo | Descrição | Tipo | Obrigatório? | | --------------- | ------------------------------------------------- | ------------------------------------------------- | ------------ | | `Cavv` | Dado que representa assinatura da autenticação | string | Sim | | `Xid` | Identificador da transação de autenticação | string | Não | | `Eci` | Código que representa o resultado da autenticação | [Tabela ECI](#tabela-eci) | Sim | | `Version` | Versão do protocolo 3DS utilizada | string | Sim | | `ReferenceId` | Identificador da requisição de autenticação | string | Sim | | `ReturnCode` | Código de retorno da autenticação | [Códigos de retorno 3DS](#códigos-de-retorno-3ds) | Sim | | `ReturnMessage` | Mensagem de retorno da autenticação | [Códigos de retorno 3DS](#códigos-de-retorno-3ds) | Sim | ### Solicitar o desafio [#solicitar-o-desafio] Instancie o objeto `paymentObject`, observando os campos que são expressamente obrigatórios na tabela abaixo. Ao executar o checkout, o processo de autenticação será iniciado e seu resultado será retornado através dos eventos. ```javascript const paymentObject = { installments: '01', cardnumber: '4000000000001091', cardexpirationmonth: '01', cardexpirationyear: '2027', cardalias: 'JOAO SOUZA', paymentmethod: 'Credit' } payzu3DS.checkout(paymentObject) ``` Caso a autenticação seja concluída com sucesso, o evento `success` será acionado. Nesse caso, as variáveis `Cavv`, `Xid` e `Eci` serão retornadas: elas devem ser enviadas ao seu backend e posteriormente incluídas na requisição no momento da autorização. Neste caso, o liability shift é transferido ao emissor. | Nome do Atributo | Descrição | Tipo | Tamanho | Obrigatório | | -------------------------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------- | ----------- | | `installments` | Número de parcelas da transação | number | 2 | Sim | | `cardnumber` | Número do Cartão | number | 19 | Sim | | `cardexpirationmonth` | Mês do vencimento do cartão | number | 2 | Sim | | `cardexpirationyear` | Ano do vencimento do cartão | number | 4 | Sim | | `cardalias` | Nome do titular impresso no cartão | string | 128 | Não | | `paymentmethod` | Tipo do cartão a ser autenticado. No caso do cartão múltiplo, deverá especificar um dos tipos, Credit ou Debit | Credit: cartão de crédito. Debit: cartão de débito | 6 | Sim | | `default_card` | Indica se é um cartão padrão do cliente na loja | boolean | - | Não | | `recurring_enddate` | Identifica a data de término da recorrência | string (AAAA-MM-DD) | 10 | Não | | `recurring_frequency` | Indica a frequência da recorrência | number: 1 = Mensal, 2 = Bimestral, 3 = Trimestral, 4 = Quadrimestral, 6 = Semestral, 12 = Anual | - | Não | | `recurring_originalpurchasedate` | Data da 1ª transação que originou a recorrência | string (AAAA-MM-DD) | 10 | Não | | `order_recurrence` | Indica se é um pedido que gera recorrências futuras | boolean | - | Não | | `order_productcode` | Tipo de compra (PHY, CHA, ACF, QCT, PAL) | string | - | Sim | | `order_countlast24hours` | Pedidos efetuados nas últimas 24h | number | 3 | Não | | `order_countlast6months` | Pedidos efetuados nos últimos 6 meses | number | 4 | Não | | `order_countlast1year` | Pedidos efetuados no último ano | number | 3 | Não | | `order_cardattemptslast24hours` | Transações com o mesmo cartão nas últimas 24h | number | 3 | Não | | `order_marketingoptin` | Aceitou receber ofertas de marketing | boolean | - | Não | | `order_marketingsource` | Origem da campanha de marketing | string | 40 | Não | | `billto_customerid` | CPF/CNPJ do comprador | string | 11-14 | Não | | `billto_contactname` | Nome do contato do endereço de cobrança | string | 120 | Sim | | `billTo_phonenumber` | Telefone do endereço de cobrança | string | 15 | Sim | | `billTo_email` | E-mail do endereço de cobrança | string | 255 | Sim | | `billTo_street1` | Logradouro e Número do endereço de cobrança | string | 60 | Sim | | `billTo_street2` | Complemento e bairro do endereço de cobrança | string | 60 | Sim | | `billTo_city` | Cidade do endereço de cobrança | string | 50 | Sim | | `billTo_state` | Sigla do estado do endereço de cobrança | string | 2 | Sim | | `billto_zipcode` | CEP do endereço de cobrança | string | 8 | Sim | | `billto_country` | País do endereço de cobrança | string Ex: BR | 2 | Sim | | `shipto_sameasbillto` | Mesmo endereço de cobrança e entrega | boolean | - | Não | | `shipto_addressee` | Nome do contato do endereço de entrega | string | 60 | Não | | `shipTo_phonenumber` | Telefone do endereço de entrega | string | 15 | Não | | `shipTo_email` | E-mail do endereço de entrega | string | 255 | Não | | `shipTo_street1` | Logradouro e Número do endereço de entrega | string | 60 | Não | | `shipTo_street2` | Complemento e bairro do endereço de entrega | string | 60 | Não | | `shipTo_city` | Cidade do endereço de entrega | string | 50 | Não | | `shipTo_state` | Sigla do estado do endereço de entrega | string | 2 | Não | | `shipto_zipcode` | CEP do endereço de entrega | string | 8 | Não | | `shipto_country` | País do endereço de entrega | string Ex: BR | 2 | Não | | `shipTo_shippingmethod` | Tipo do método de envio (lowcost, sameday, oneday, twoday, etc.) | string | - | Não | | `shipto_firstusagedate` | Data da primeira utilização do endereço de entrega | string (AAAA-MM-DD) | 10 | Não | A coluna Tipo reproduz a documentação de origem. No exemplo oficial acima, `installments`, `cardnumber`, `cardexpirationmonth` e `cardexpirationyear` são enviados como string; siga o exemplo, em especial no `cardnumber`, para evitar perda de precisão numérica. ### Utilizar o resultado na cobrança [#utilizar-o-resultado-na-cobrança] Para criar uma cobrança utilizando o 3DS, é necessário definir o campo `authenticate` como `true`, além de informar o campo `externalAuthentication` dentro de `creditCardPayment`: ```json { "creditCardPayment": { "authenticate": true, "externalAuthentication": { "cavv": "Ag5zZ2ElCIUbLFj6gS0J9gByv//rRg5qGTqWqf8vTjt5", "xid": "198b924ea7db1014b64c8b426a0e6f1e", "eci": "05", "version": "2.2", "referenceId": "abcd1234-efgh-5678-ijkl-9012mnopqrst" } } } ``` Consulte [Criar cobrança](/docs/cartao/endpoints/charges/post_charges) para os demais campos da requisição. ## Códigos de retorno e ECI [#códigos-de-retorno-e-eci] ### Códigos de retorno 3DS [#códigos-de-retorno-3ds] Códigos retornados no fluxo de autenticação 3DS. | Código 3DS | Descrição | Ação possível | | ---------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | `100` | Transação realizada com sucesso. | - | | `101` | Está faltando um ou mais campos obrigatórios na requisição. | Confira os campos `missingField_0` até `missingField_N` na resposta. Envie a requisição novamente. | | `102` | Um ou mais campos da requisição contêm dados inválidos. | Confira os campos `invalidField_0` até `invalidField_N` na resposta. Reenvie a requisição. | | `150` | Erro: falha geral no sistema. | Aguarde alguns minutos e envie a requisição novamente. | | `151` | Erro: a requisição foi recebida, mas houve time-out do servidor. | Aguarde alguns minutos e envie a requisição novamente. | | `152` | Erro: a requisição foi recebida, mas houve time-out de serviço. | Aguarde alguns minutos e envie a requisição novamente. | | `234` | Há um problema na sua configuração de merchant. | Não envie a requisição novamente. Entre em contato com o suporte. | | `475` | O cliente está registrado na autenticação do pagante. | Faça a autenticação do portador do cartão antes de prosseguir com a transação. | | `476` | O cliente não pode ser autenticado. | Revise o pedido do cliente. | | `MPI901` | Erro inesperado. | - | | `MPI902` | Resposta inesperada da autenticação. | - | | `MPI900` | Ocorreu um erro. | - | | `MPI601` | Desafio omitido. | - | | `MPI600` | Bandeira não suporta a autenticação. | - | ### Tabela ECI [#tabela-eci] A tabela ECI indica, por bandeira, o resultado da autenticação e quem assume o risco de chargeback: | Mastercard | Visa | Elo | Amex | Resultado da autenticação | A transação foi autenticada? | | ------------------------------ | ------------------------ | ------------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------- | ---------------------------- | | `02` | `05` | `05` | `05` | Autenticada pelo emissor: risco de chargeback passa a ser do emissor. | Sim | | `01` | `06` | `06` | `06` | Autenticada pela bandeira: risco de chargeback passa a ser do emissor. | Sim | | Diferente de `01`, `02` e `04` | Diferente de `05` e `06` | Diferente de `05` e `06` | Diferente de `05` e `06` | Não autenticada: risco de chargeback permanece com o estabelecimento. | Não | | `04` | `7` | - | - | Não autenticada, transação caracterizada como Data Only: risco de chargeback permanece com o estabelecimento. | Não | Quando a transação não é autenticada, o risco de chargeback permanece com o estabelecimento. Consulte os valores de ECI da tabela acima antes de decidir prosseguir com a cobrança. ## Referências [#referências] * Cartões para simular os cenários de autenticação 3DS no sandbox: [Cartões de teste](/docs/cartao/test-cards)