Autenticação 3DS

Redirecionando para https://docs.cielo.com.br/gateway/docs/autenticacao-3ds ...

As documentações da Autenticação 3DS estão em um novo portal

Novo portal de desenvolvedores e-commerce Braspag e Cielo

Acesse o novo portal de desenvolvedores E-commerce docs.cielo.com.br.

Atenção: O conteúdo desta página está sendo descontinuado e não receberá atualizações a partir de 14/08/2024. Visite a nova documentação em docs.cielo.br.

Autenticação 3DS

O que é 3D Secure 2.2?

É um protocolo de autenticação que confirma se o comprador é de fato o portador do cartão (de crédito ou débito). O objetivo do 3DS (também chamado de EMV 3DS) é evitar fraudes em transações de cartão não presente (CNP).

Por meio do 3DS, os dados do comprador são enviados para as bandeiras e emissores do cartão, que irão realizar a autenticação.

3DS significa 3-D Secure Protocol e foi desenvolvido pela EMVCo, um corpo técnico formado pelas principais bandeiras de cartão e que cria especificações para a interoperabilidade e aceitação de pagamentos de forma segura no mundo todo.

Para realizar a autenticação, a loja precisa enviar os dados do comprador para a bandeira por meio de um serviço intermediário, o 3DS Server, que faz a comunicação com a bandeira. É possível usar um 3DS Server externo ou o 3DS Server Braspag

Se sua loja usa um 3DS Server externo à Braspag para autenticação de cartões, você deve infomar o Cavv retornado pelo seu 3DS Server na requisição de autorização do Gateway. Para mais informações, pule para a etapa de Autorização com Autenticação.

Principais benefícios:

Palavras chaves: Autenticação de cartão de crédito e débito, EMVCO, 3DS, Visa, Mastercard, Elo, E-commerce.

Importante:

Quem pode usar o 3DS?

Qualquer e-commerce pode usar a solução como uma camada extra de segurança para as suas transações.

Quais são requisitos para a utilização do 3DS?

O e-commerce deve atender aos seguintes requisitos:

Quando usar?

A Autenticação 3DS é obrigatória para todas as transações de cartão de débito e opcional para transações de cartão de crédito.

Como saber se a transação foi autenticada?

Isso irá depender do resultado da Tabela de ECI.

O 3DS autentica o portador em transações recorrentes?

Sim. Se todos os campos obrigatórios forem enviados corretamente, o 3DS 2.2 autentica todas as transações recorrentes. Se algum campo obrigatório não for enviado, acontece o downgrade para 3DS 2.0, que autentica apenas a primeira transação de uma série de transações recorrentes.

Como as transações seguintes (a partir da segunda) não são autenticadas no 3DS 2.0, se houver chargeback a partir da segunda transação, a responsabilidade é da loja. Usando o 3DS 2.2, a responsabilidade do chargeback é sempre do emissor.

Tipos de autenticação do portador

Como funciona a autorização com autenticação via 3D Secure 2.2?

O processo de autorização de cartão autenticada via 3D Secure 2.2 ocorre em duas etapas:

  1. Etapa de autenticação: por meio do protocolo 3DS, a bandeira ou o emissor autentica que o comprador é de fato o titular do cartão. O protocolo é integrado ao e-commerce por meio de um script em JavaScript, que retorna o resultado da autenticação e alguns parâmetros que devem ser enviados na autorização. Saiba mais em Integração do script;
  2. Etapa de autorização: a loja submete a transação para autorização, informando os parâmetros retornados pelo script na etapa de autenticação. Saiba mais em Autorização com Autenticação.

O fluxo a seguir descreve as etapas de autenticação em alto nível:

Fluxo 3DS 2.2

1. O comprador escolhe pagar com cartão de crédito ou débito;
2. A loja executa um script, solicitando à Braspag autenticação através da solução 3DS 2.2;
3. A loja envia requisição com dados do comprador para a bandeira;
4. A bandeira envia a requisição para avaliação de risco do emissor;
5. O emissor avalia as informações e determina se fluxo será com ou sem desafio ao portador;
5.1. Se o emissor solicitar desafio, cria e envia a URL para a loja;
5.2. A loja apresenta lightbox do desafio na página de checkout para obter resposta do comprador;
5.3. O comprador responde o desafio, completando a autenticação;
6. O emissor envia o resultado da autenticação para o 3DS Server;
7. O 3DS Server envia resultado da autenticação. A loja decide seguir ou não para autorização.

A loja pode optar por submeter uma transação não autenticada para autorização; no entanto, nesse caso, a loja será responsável em caso de chargeback.

Adquirentes e bandeiras disponíveis

As adquirentes disponíveis são:

As bandeiras disponíveis para autenticação via 3DS 2.2 são:

Stand-in pela bandeira (válido para Visa e Mastercard): Além das bandeiras, o emissor do cartão também precisa processar o protocolo 3DS 2.2. Caso o emissor ainda não esteja apto a responder um pedido de autenticação usando 3DS 2.2, a bandeira avalia os dados enviados, como por exemplo o histórico transacional e comportamental do portador do cartão, classificando os pedidos de autenticação como “Baixo Risco” e “Não Baixo Risco”. A partir dessas informações, os emissores poderão contar com uma proteção mesmo não possuindo uma solução própria de 3DS 2.2, e terão uma maior confiança nas transações autenticadas. Em casos de stand-in, a autenticação ocorre de forma silenciosa (sem desafio para o portador) e, uma vez que a transação foi autenticada, o liability em caso de fraude ficará com o emissor.

O que é o Data Only – somente notificação

O que é?

O Data Only é um campo opcional que poderá ser utilizado para contribuir para o banco de dados da bandeira e emissor, melhorando a performance da autenticação.

O Data Only pode ser usado quando o emissor não realiza a autenticação. Nesse caso, se o campo Data only foi parametrizado no script, a bandeira vai receber os dados parametrizados e vai compartilhar essas informações com o emissor. Com o tempo, o emissor terá mais dados de transações daquele cartão e da pessoa titular do cartão e terá mais elementos para realizar a autenticação.

Como usar o Data Only?

Basta parametrizar o bpmpi_auth_notifyonly. A autorização ocorre da mesma forma que qualquer [Autorização com Autenticação].

Para usar o Data Only, na Integração do script parametrize o campo bpmpi_auth_notifyonly descrito no item Etapa de Autenticação – passo 3 – Mapeamento de classes.

No modelo Data Only, os campos adicionais do 3DS 2.2 são mapeados da mesma forma, e enviados para a bandeira, porém, sem solicitar a autenticação.

O Data Only é válido para as bandeiras Mastercard e Visa.

Para Data Only Mastercard, o ECI será sempre 4;
Para Data Only Visa, o ECI será sempre 7.

Qual é o benefício?

Importante:

Integração do script via Javascript

O protocolo de autenticação 3DS 2.2 está disponível na versão browser-based, ou seja, a loja deverá incluir o script do 3DS no arquivo HTML da página de pagamento (checkout). O protocolo 3DS, ao processar o script, permite a troca de dados entre a loja e o emissor para autenticar o portador do cartão.

A integração do script do protocolo de autenticação é composta pelas seguintes etapas:

  1. Criação do token de acesso: o token de acesso deverá ser inserido no script (JavaScript) e no HTML na classe bpmpi_accesstoken. Veja as tabelas XXX para mais informações;
  2. Mapeamento de classes: aqui você deve preparar o seu ambiente para coletar os dados do comprador e executar o script no navegador do comprador;
  3. Implementação do script: insira as classes no HTML (tag body) e referencie o arquivo JavaScript com as classes mapeadas.
  4. Implementação da chamada ao evento de autenticação: usando os dados retornados no resultado da autenticação, envie a transação para autorização (aprovação da adquirente).

1. Criando o token de acesso

Obtenha o valor do Authorization concatenando o valor do “ClientID”, sinal de dois-pontos (“:”) e “ClientSecret”.

Ex: dba3a8db-fa54-40e0-8bab-7bfb9b6f2e2e:D/ilRsfoqHlSUChwAMnlyKdDNd7FMsM7cU/vo02REag=

Em seguida, codifique o resultado na base 64. Esse código alfanumérico será utilizado na requisição do access token:

Ambiente Endpoint Credenciais
SANDBOX https://mpisandbox.braspag.com.br Para teste em sandbox, use:
ClientID: dba3a8db-fa54-40e0-8bab-7bfb9b6f2e2e
ClientSecret: D/ilRsfoqHlSUChwAMnlyKdDNd7FMsM7cU/vo02REag=
PRODUÇÃO https://mpi.braspag.com.br Solicite os dados ClientID e ClientSecret à equipe de suporte após concluir o desenvolvimento em sandbox.

Requisição

{
     "EstablishmentCode":"1006993069",
     "MerchantName": "Loja Exemplo Ltda",
     "MCC": "5912"
}
curl
--request POST "https://mpisandbox.braspag.com.br/v2/auth/token"
--header "Content-Type: application/json"
--header "Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
--data-binary
--verbose
{
     "EstablishmentCode":"1006993069",
     "MerchantName": "Loja Exemplo Ltda",
     "MCC": "5912"
}
Campo Descrição Tipo Tamanho
EstablishmentCode Código do Estabelecimento do Cielo E-Commerce 3.0 ou Getnet, ou PV na Rede numérico 10 posições
MerchantName Nome do estabelecimento registrado na adquirente alfanumérico até 25 posições
MCC Código de Categoria do estabelecimento numérico 4 posições

Response

{
      "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjbGllbnRfbmFtZSI6IlFBXzNEU19BdXRoZW50aWNhdG9yIiwiY2xpZW50X2lkIjoiZGJhM2E4ZGItZmE1NC00MGUwLThiYWItN2JmYjliNmYyZTJlIiwic2NvcGVzIjoie1wiU2NvcGVcIjpcIjNEU0F1dGhlbnRpY2F0b3JcIixcIkNsYWltc1wiOlt7XCJOYW1lXCI6XCJNZXJjaGFudE5hbWVcIixcIlZhbHVlc1wiOFwiVmFsdWVzXCI6W1wiNTU1NVwiXX0se1wiTmFtZVwiOlwiUmVmZXJlbmNlSWRcIixcIlZhbHVlc1wiOltcImY3MjE1YmQ3LWM0OTQtNGQ5Yi1NzEyfQ.daMqXko3dZOV0TzNFQ2vSsVSKqOsrwuswg7RB82ecAASSSSSSSSSSSSFFFFFFFFFFFFFGGGGGGGGGGGGGGGGGGGGGGGG",
      "token_type": "bearer",
      "expires_in": "2018-07-23T11:29:32"
}
--header "Content-Type: application/json"
--data-binary
{
      "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjbGllbnRfbmFtZSI6IlFBXzNEU19BdXRoZW50aWNhdG9yIiwiY2xpZW50X2lkIjoiZGJhM2E4ZGItZmE1NC00MGUwLThiYWItN2JmYjliNmYyZTJlIiwic2NvcGVzIjoie1wiU2NvcGVcIjpcIjNEU0F1dGhlbnRpY2F0b3JcIixcIkNsYWltc1wiOlt7XCJOYW1lXCI6XCJNZXJjaGFudE5hbWVcIixcIlZhbHVlc1wiOFwiVmFsdWVzXCI6W1wiNTU1NVwiXX0se1wiTmFtZVwiOlwiUmVmZXJlbmNlSWRcIixcIlZhbHVlc1wiOltcImY3MjE1YmQ3LWM0OTQtNGQ5Yi1NzEyfQ.daMqXko3dZOV0TzNFQ2vSsVSKqOsrwuswg7RB82ecAASSSSSSSSSSSSFFFFFFFFFFFFFGGGGGGGGGGGGGGGGGGGGGGGG",
      "token_type": "bearer",
      "expires_in": "2018-07-23T11:29:32"
}
Campo Descrição Tipo/Tamanho
access_token Token necessário para realizar a autenticação. alfanumérico [tamanho variável]
token_type Fixo "bearer" alfanumérico
expires_in Tempo em minutos para expirar o token. numérico

2. Mapeando as classes

A solução disponibiliza dezenas de classes que devem ser mapeadas em seu código HTML.

Uma vez que a classe é mapeada em determinado campo, o script é capaz de recuperar o valor contido no campo e submetê-lo para compor a requisição de autenticação.

O caracter # indicado no campo deve ser substituído pelo número que representa o índice do item. Exemplo: bpmpi_item_1_productName representa o nome do item 1 do carrinho

Categoria dos dados Campo Descrição Tipo/Tamanho Obrigatório
Parametrização bpmpi_auth Booleano que indica se a transação é submetida ou não para o processo de autenticação Booleano:
true – submeter à autenticação
false – não submeter à autenticação
Sim
Parametrização bpmpi_auth_notifyonly Booleano que indica se a transação com cartão será submetida no modo “somente notificação”. Neste modo, o processo de autenticação não será acionado, porém, os dados serão submetidos à bandeira. VÁLIDO SOMENTE PARA CARTÕES MASTERCARD Booleano:
true – modo somente notificação;
false – modo com autenticação
Recomendado
Parametrização bpmpi_auth_suppresschallenge Booleano que indica se ignora ou não o desafio quando houver. Se uma transação autorizada após ignorar o desafio, o liability permanece com o estabelecimento. Booleano:
true – ignorar desafios se houver;
false – apresentar desafio se houver
Recomendado
Parametrização bpmpi_accesstoken Token gerado pela API de Token de Acesso (etapa 1) Alfanumérico [varivável] Sim
Pedido bpmpi_ordernumber Código do pedido no estabelecimento Alphanumérico [até 50 posições] Sim
Pedido bpmpi_currency Código da moeda Fixo "BRL" Sim
Pedido bpmpi_totalamount Valor total da transação, enviado em centavos Numérico [até 15 posições] Sim
Pedido bpmpi_installments Número de parcelas da transação Numérico [até 2 posições] Sim
Pedido bpmpi_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
Sim
Pedido bpmpi_cardnumber Número do Cartão Numérico [até 19 posições] Sim
Pedido bpmpi_cardexpirationmonth Mês do vencimento do cartão Numérico [2 posições] Sim
Pedido bpmpi_cardexpirationyear Ano do vencimento do cartão Numérico [4 posições] Sim
Pedido bpmpi_cardalias Alias do cartão Alphanumérico [até 128 posições] Recomendado
Pedido bpmpi_default_card Indica se é um cartão padrão do cliente na loja Booleano
true - sim
false - não
Recomendado
Características do pedido bpmpi_recurring_enddate Identifica a data de término da recorrência Texto (AAAA-MM-DD) Recomendado
Características do pedido bpmpi_recurring_frequency Indica a frequência da recorrência Número
1 - Mensal
2 - Bimestral
3 - Trimestral
4 - Quadrimestral
6 - Semestral
12 - Anual
Recomendado
Características do pedido bpmpi_recurring_originalpurchasedate Identifica a data da 1ª transação que originou a recorrência Texto (AAAA-MM-DD) Recomendado
Características do pedido bpmpi_order_recurrence Indica se é um pedido que gera recorrências futuras Booleano
true
false
Recomendado
Características do pedido bpmpi_order_productcode Tipo da compra PHY: compra de mercadorias
CHA: Check acceptance
ACF: Financiamento de conta
QCT: Transação quase-dinheiro
PAL: recarga
Sim
Características do pedido bpmpi_order_countlast24hours Quantidade de pedidos efetuados por este comprador nas últimas 24h Numérico [até 3 posições] Recomendado
Características do pedido bpmpi_order_countlast6months Quantidade de pedidos efetuados por este comprador nos últimos 6 meses Numérico [até 4 posições] Recomendado
Características do pedido bpmpi_order_countlast1year Quantidade de pedidos efetuados por este comprador no último ano Numérico [até 3 posições] Recomendado
Características do pedido bpmpi_order_cardattemptslast24hours Quantidade de transações com o mesmo cartão nas últimas 24h Numérico [até 3 posições] Recomendado
Características do pedido bpmpi_order_marketingoptin Indica se o comprador aceitou receber ofertas de marketing Booleano
true – sim
false – não
Recomendado
Características do pedido bpmpi_order_marketingsource Identifica a origem da campanha de marketing Alfanumérico [até 40 posições] Recomendado
Características do pedido bpmpi_transaction_mode Identifica o canal que originou a transação M: MOTO
R: Varejo
S: E-Commerce
P: Mobile
T: Tablet
Recomendado
Características do pedido bpmpi_merchant_url Endereço do site do estabelcimento Alphanumérico [100] Exemplo: http://www.exemplo.com.br Sim
Cartões pré-pagos bpmpi_giftcard_amount O total do valor da compra para cartões-presente pré-pagos em valor arredondado Numérico [até 15 posições],
exemplo: R$ 125,54 = 12554
Recomendado
Cartões pré-pagos bpmpi_giftcard_currency Código da moeda da transação paga com cartão do tipo pré-pago Fixo "BRL" Recomendado
Endereço de cobrança bpmpi_billto_customerid Identifica o CPF/CNPJ do comprador Numérico [11 a 14 posições]
99999999999999
Recomendado
Endereço de cobrança bpmpi_billto_contactname Nome do contato do endereço de cobrança Alfanumérico [até 120] Sim
Endereço de cobrança bpmpi_billto_phonenumber Telefone de contato do endereço de cobrança Numérico [até 15 posições], no formato: 5511999999999 Sim
Endereço de cobrança bpmpi_billto_email E-mail do contato do endereço de cobrança Alfanumérico [até 255], no formato nome@exemplo.com Sim
Endereço de cobrança bpmpi_billto_street1 Logradouro e Número do endereço de cobrança Alfanumérico [até 60] Sim
Endereço de cobrança bpmpi_billto_street2 Complemento e bairro do endereço de cobrança Alfanumérico [até 60] Sim
Endereço de cobrança bpmpi_billto_city Cidade do endereço de cobrança Alfanumérico [até 50] Sim
Endereço de cobrança bpmpi_billto_state Sigla do estado do endereço de cobrança Texto [2 posições] Sim
Endereço de cobrança bpmpi_billto_zipcode CEP do endereço de cobrança Alfanumérico [até 8 posições], no formato: 99999999 Sim
Endereço de cobrança bpmpi_billto_country País do endereço de cobrança Texto [2 posições] Ex. BR Sim
Endereço de entrega bpmpi_shipto_sameasbillto Indica se utiliza o mesmo endereço fornecido para endereço de cobrança Booleano
true
false
Recomendado
Endereço de entrega bpmpi_shipto_addressee Nome do contato do endereço de entrega Alfanumérico [até 60] Recomendado
Endereço de entrega bpmpi_shipTo_phonenumber Telefone de contato do endereço de entrega Numérico [até 15 posições], no formato: 5511999999999 Recomendado
Endereço de entrega bpmpi_shipTo_email E-mail do contato do endereço de entrega Alfanumérico [até 255], no formato nome@exemplo.com Recomendado
Endereço de entrega bpmpi_shipTo_street1 Logradouro e Número do endereço de entrega Alfanumérico [até 60] Recomendado
Endereço de entrega bpmpi_shipTo_street2 Complemento e bairro do endereço de entrega Alfanumérico [até 60] Recomendado
Endereço de entrega bpmpi_shipTo_city Cidade do endereço de entrega Alfanumérico [até 50] Recomendado
Endereço de entrega bpmpi_shipTo_state Sigla do estado do endereço de entrega Texto [2 posições] Recomendado
Endereço de entrega bpmpi_shipto_zipcode CEP do endereço de entrega Alfanumérico [até 8 posições], no formato: 99999999 Recomendado
Endereço de entrega bpmpi_shipto_country País do endereço de cobrança Texto [2 posições] Ex. BR Recomendado
Endereço de entrega bpmpi_shipTo_shippingmethod Tipo do método de envio lowcost: envio econômico
sameday: envio no mesmo dia
oneday: envio no dia seguinte
twoday: envio em dois dias
threeday: envio em três dias
pickup: retirada na loja
other: outrosnone: não há envio
Recomendado
Endereço de entrega bpmpi_shipto_firstusagedate Indica a data de quando houve a primeira utilização do endereço de entrega Texto
AAAA-MM-DD – data da criação
Recomendado
Carrinho de compras bpmpi_cart_#_description Descrição do item Alfanumérico [até 255 posições] Recomendado
Carrinho de compras bpmpi_cart_#_name Nome do item Alfanumérico [até 255 posições] Recomendado
Carrinho de compras bpmpi_cart_#_sku SKU do item Alfanumérico [até 255 posições] Recomendado
Carrinho de compras bpmpi_cart_#_quantity Quantidade do item no carrinho Numérico [até 10 posições] Recomendado
Carrinho de compras bpmpi_cart_#_unitprice Valor unitário do item do carrinho em centavos Numérico [até 10 posições] Recomendado
Usuário bpmpi_useraccount_guest Indica se o comprador é um comprador sem login (guest) Booleano
true – sim
false – não
Recomendado
Usuário bpmpi_useraccount_createddate Indica a data de quando houve a criação da conta do comprador Texto
AAAA-MM-DD – data da criação
Recomendado
Usuário bpmpi_useraccount_changeddate Indica a data de quando houve a última alteração na conta do comprador Texto
AAAA-MM-DD – data da última alteração
Recomendado
Usuário bpmpi_useraccount_passwordchangeddate Indica a data de quando houve a alteração de senha da conta do comprador Texto
AAAA-MM-DD – data da última alteração de senha
Recomendado
Usuário bpmpi_useraccount_authenticationmethod Método de autenticação do comprador na loja 01- Não houve autenticação
02- Login da própria loja
03- Login com ID federado
04- Login com autenticador FIDO
Recomendado
Usuário bpmpi_useraccount_authenticationprotocol Dado que representa o protocolo de login efetuado na loja Alfanumérico [até 2048 posições] Recomendado
Usuário bpmpi_useraccount_authenticationtimestamp A data e hora que o login foi efetuado na loja Texto [19 posições] YYYY-MM-ddTHH:mm:SS Recomendado
Usuário bpmpi_merchant_newcustomer Identifica se um comprador novo na loja Booleano
true – sim
false – não
Recomendado
Dispositivo bpmpi_device_ipaddress Endereço IP da máquina do comprador Alfanumérico [até 45] Condicional - obrigatório somente para Visa
Dispositivo bpmpi_device_#_fingerprint Id retornado pelo Device Finger Print Alfanumérico [sem limitação] Recomendado
Dispositivo bpmpi_device_#_provider Nome do provedor do Device Finger Print Alfanumérico [até 32 posições] cardinal
inauth
threatmetrix
Recomendado
Dispositivo bpmpi_device_channel Canal por onde chegou a transação. Valores possíveis:
- Browser
- SDK
- 3RI
Alfanúmerico [até 7 posições] Recomendado
Recorrência bpmpi_recurring_type Tipo de pagamento recorrente. Número
1 - Primeira transação
2 - Transação subsequente
3 - Modificação
4 - Cancelamento
Recomendado
Recorrência bpmpi_recurring_validationIndicator Indica se a transação de pagamento recorrente foi validada ou não Número
0 - Não validado
1 - Validado
Recomendado
Recorrência bpmpi_recurring_maximumAmount Valor máximo acordado pelo titular do cartão. numérico [até 12 posições] Recomendado
Recorrência bpmpi_recurring_referenceNumber Número de referência exclusivo para a transação de pagamento recorrente. Alfanumérico [até 35 posições] Recomendado
Recorrência bpmpi_recurring_occurrence Indica a frequência com que ocorre um pagamento recorrente. Número
01 - Diariamente
02 - Duas vezes por semana
03 - Semanal
04 - Dez dias
05 - A cada 2 semanas
06 - Mensal
07 - Bimestral
08 - Trimestral
09 - Quadrimestral
10 - Semestral
11 - Anual
12 - Não programado.
Recomendado
Recorrência bpmpi_recurring_numberOfPayments Número total de pagamentos durante a assinatura recorrente. Numérico [até 2 posições] Recomendado
Recorrência bpmpi_recurring_amountType Indica o tipo de valor recorrente acordado pelo titular do cartão. Valores suportados:
1 - Pagamento recorrente de valor fixo
2 - Pagamento recorrente com valor máximo.
Recomendado
Companhias aéreas bpmpi_airline_travelleg_#_carrier Código IATA para o trecho Alfanumérico [2 posições] Recomendado
Companhias aéreas bpmpi_airline_travelleg_#_departuredate Data de partida Texto
AAAA-MM-DD
Recomendado
Companhias aéreas bpmpi_airline_travelleg_#_origin Código IATA do aeroporto de origem Alfanumérico [5 posições] Recomendado
Companhias aéreas bpmpi_airline_travelleg_#_destination Código IATA do aeroporto de destino Alfanumérico [5 posições] Recomendado
Companhias aéreas bpmpi_airline_passenger_#_name Nome do passageiro Alfanumérico [até 60 posições] Recomendado
Companhias aéreas bpmpi_airline_passenger_#_ticketprice O valor da passagem em centavos Numérico [até 15 posições],
exemplo: R$ 125,54 = 12554
Recomendado  
Companhias aéreas bpmpi_airline_numberofpassengers Número de passageiros Numérico [3 posições] Recomendado
Companhias aéreas bpmpi_airline_billto_passportcountry Código do país que emitiu o passaporte (ISO Standard Country Codes) Texto [2 posições] Recomendado
Companhias aéreas bpmpi_airline_billto_passportnumber Número do passaporte Alfanumérico [40 posições] Recomendado
Estabelecimento bpmpi_mdd1 Dado Extra definido pelo lojista Alfanumérico [até 255 posições] Recomendado
Estabelecimento bpmpi_mdd2 Dado Extra definido pelo lojista Alfanumérico [até 255 posições] Recomendado
Estabelecimento bpmpi_mdd3 Dado Extra definido pelo lojista Alfanumérico [até 255 posições] Recomendado
Estabelecimento bpmpi_mdd4 Dado Extra definido pelo lojista Alfanumérico [até 255 posições] Recomendado
Estabelecimento bpmpi_mdd5 Dado Extra definido pelo lojista Alfanumérico [até 255 posições] Recomendado
Estabelecimento bpmpi_brand_establishment_code Código de estabelecimento (EC) Amex. Obrigatório em autenticações Amex Texto [10 posições] Obrigatório em autenticações Amex

3. Implementando o script

Neste passo, implemente o script e faça o mapeamento de classes responsáveis pela comunicação com as plataformas de autenticação das bandeiras e emissor. Siga o exemplo a seguir, que demonstra a implementação básica. Recomenda-se que o trecho seja colocado no final do código HTML de seu checkout:

Para baixar o código HTML de exemplo completo, no GitHub Braspag

A imagem mostra um trecho HTML de uma implementação básica:

Fluxo 3DS 2.2

Descrição dos eventos

Os eventos são ações que o script toma como resposta para acompanhamento do processo de autenticação, mas não indicam se a transação foi autenticada com sucesso.

O valor retornado no ECI (E-commerce Indicator) é o que indica se a transação foi autenticada ou não e de quem é o risco de chargeback. Para submeter a transação para autorização, considere o valor do ECI e use os eventos apenas como complemento para auxiliar na tomada de decisão.

Evento Descrição
onReady É acionado quando todos os procedimentos de carregamento do script da solução foram concluídos com sucesso, o que inclui a validação do token de acesso, indicando que o checkout está pronto para iniciar a autenticação.
onSuccess É acionado quando o cartão é elegível e teve o processo de autenticação finalizado com sucesso. Neste caso, as variáveis CAVV, XID e ECI serão retornadas. Estas variáveis devem ser enviadas na requisição de autorização. Neste cenário, se a transação é autorizada, o liability shift é transferido ao emissor.
onFailure É acionado quando o cartão é elegível, porém o processo de autenticação falhou por algum motivo. Neste caso, somente a variável ECI será retornada. Caso haja a decisão de seguir com a autorização mesmo assim, o ECI deverá ser enviado no momento da autorização. Neste cenário, se a transação é autorizada, o liability shift permanece com o estabelecimento.
onUnenrolled É acionado quando o cartão não é elegível, ou seja, o portador e/ou emissor não participam do programa de autenticação. Neste caso, orientar o comprador a verificar junto ao emissor se o cartão está habilitado para realizar autenticação no e-commerce. Somente a variável ECI será retornada. Caso haja a decisão de seguir com a autorização mesmo assim, o ECI deverá ser enviado no momento da autorização. Neste cenário, se a transação é autorizada, o liability shift permanece com o estabelecimento.
onDisabled É acionado quando o estabelecimento optou por não submeter o portador ao processo de autenticação (classe bpmpi\_auth como false). Neste cenário, se a transação é autorizada, o liability shift permanece com o estabelecimento.
onError É acionado quando o processo de autenticação recebeu um erro sistêmico. Neste cenário, se a transação é autorizada, o liability shift permanece com o estabelecimento.
onUnsupportedBrand É acionado quando a bandeira do cartão não é suportada pelo 3DS 2.2

Descrição dos parâmetros de entrada

Parâmetro Descrição Tipo
Environment Indica o ambiente a ser utilizado (Sandbox ou Produção) SDB – Sandbox (ambiente de teste)
PRD – Produção (ambiente de produção)
Debug Booleano que indica se o modo debug está ativado ou não. Quando true, a plataforma emitirá o relatório no mecanismo de debug do browser.Não é recomendado deixar o modo debug ativado no ambiente de produção. Booleano
true – modo debug ativado
false – modo debug desativado

IMPORTANTE: O arquivo JavaScript deve ser salvo no servidor onde está a aplicação da loja. Para baixar o arquivo, acesse https://bit.ly/2CSOp2n.

Descrição das saídas

Saída Descrição Tipo Tamanho
Cavv Dado que representa assinatura da autenticação Texto -
Xid ID que representa a requisição da autenticação Texto -
Eci Código indicador do e-commerce, que representa o resultado da autenticação Numérico até 2 posições
Version Versão do 3DS aplicado. Para 3DS 2.2, inserir apenas “2”. Numérico 1 posição – 3DS 2.0
ReferenceID ID que representa a requisição de autenticação GUID 36 posições
ReturnCode Código de retorno da requisição de autenticação Alfanumérico até 5 posições
ReturnMessage Mensagem de retorno da requisição de autenticação Alfanumérico variável

Exemplo de retorno do script

Exemplo de evento OnSuccess

{
  Cavv: 'Y2FyZGluYWxjb21tZXJjZWF1dGg=',
  Xid: null,
  Eci: '01',
  Version: '2',
  ReferenceId: '973cf83d-b378-43d5-84b6-ce1531475f2a'
}

Exemplo de evento OnFailure

{
  Xid: null,
  Eci: null,
  ReturnCode: '231',
  ReturnMessage: 'Unexpected error ocurred',
  ReferenceId: null
}

Exemplo de retorno para bandeira não suportada

Quando a bandeira não é suportada pelo 3DS, o MPI retorna o código “MPI 600” e a mensagem “Brand not supported for authentication”.

{
  Xid: null,
  Eci: null,
  ReturnCode: 'MPI600',
  ReturnMessage: 'Brand not supported for authentication',
  ReferenceId: null
}

Confira os valores possíveis de ReturnCodes na tabela Lista de Return Codes.

Tabela de ECI

O ECI (Electronic Commerce Indicator) é um código retornado pelas bandeiras e indica o resultado da autenticação 3DS do portador do cartão junto ao emissor ou bandeira.

Com base no resultado do ECI a loja deve decidir se vai prosseguir com a transação submetendo-a para autorização ou não. É possível enviar uma transação não autenticada para autorização, mas a responsabilidade em caso de chargeback é do estabelecimento.

Confira na tabela a seguir os ECIs correspondentes à cada bandeira e o resultado da autenticação.

Posteriormente, envie o valor do ECI na requisição da transação no campo Payment.ExternalAuthentication.Eci.

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 07 - - Não autenticada, transação caracterizada como Data Only – risco de chargeback permanece com o estabelecimento. Não

4. Implementando chamada ao evento de autenticação

O evento **bpmpi_Authenticate()** deve ser chamado no momento de finalização do checkout (finalização da compra). Vide exemplo abaixo:

<input type="button"onclick="bpmpi_authenticate()" />

Autorização com Autenticação

Após a conclusão da autenticação do portador do cartão, a loja deve submeter a transação ao processo de autorização, enviando os dados de autenticação no modelo de “autenticação externa” (nó ExternalAuthentication), tanto para 3DS Server Braspag quanto para 3DS Server externo.

Veja a seguir um exemplo de requisição de autorização à API do Pagador:

Requisição

{  
   "MerchantOrderId":"2017051002",
   "Customer":
   {  
     (...)
   },
   "Payment":
   {  
     (...)
     "Provider":"Cielo30",
     "Authenticate":true,
     "ReturnUrl":"http://www.loja.com.br",
     "CreditCard":{  
         "CardNumber":"4000000000001000",
         "Holder":"Nome do Portador",
         "ExpirationDate":"12/2021",
         "SecurityCode":"123",
         "Brand":"Visa",
         "SaveCard":"false"
     },
     "ExternalAuthentication":{
       "Cavv":"AAABB2gHA1B5EFNjWQcDAAAAAAB=",
       "Xid":"Uk5ZanBHcWw2RjRCbEN5dGtiMTB=",
       "Eci":"5",
       "Version":"2",
       "ReferenceID":"a24a5d87-b1a1-4aef-a37b-2f30b91274e6"
     }
   }
}
--request POST "https://apisandbox.braspag.com.br/v2/sales"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
--header "MerchantKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
--data-binary
--verbose
{  
   "MerchantOrderId":"2017051002",
   "Customer":
   {  
     (...)
   },
   "Payment":
   {  
     (...)
     "Provider":"Cielo30",
     "Authenticate":true,
     "ReturnUrl":"http://www.loja.com.br",
     "CreditCard":{  
         "CardNumber":"4000000000001000",
         "Holder":"Nome do Portador",
         "ExpirationDate":"12/2021",
         "SecurityCode":"123",
         "Brand":"Visa",
         "SaveCard":"false"
     },
     "ExternalAuthentication":{
       "Cavv":"AAABB2gHA1B5EFNjWQcDAAAAAAB=",
       "Xid":"Uk5ZanBHcWw2RjRCbEN5dGtiMTB=",
       "Eci":"5",
       "Version":"2",
       "ReferenceID":"a24a5d87-b1a1-4aef-a37b-2f30b91274e6"
     }
   }
}
Campo Descrição Tipo Tamanho Obrigatório
Payment.Provider Nome do provedor do meio de pagamento: Cielo30, Getnet ou Rede. texto 15 posições Sim.
Payment.Authenticate Define se o comprador será direcionado ao emissor para autenticação do cartão. booleano (“true” / “false”) - Sim, caso a autenticação seja validada.
Payment.ExternalAuthentication.ReturnUrl URL de retorno aplicável somente se a versão for “1”. alfanumérico 1024 posições Sim.
Payment.ExternalAuthentication.Cavv Assinatura retornada nos cenários de sucesso na autenticação. texto - Sim, caso a autenticação seja validada.
Payment.ExternalAuthentication.Xid XID retornado no processo de autenticação. texto - Sim, quando a versão do 3DS for “1”.
Payment.ExternalAuthentication.Eci Electronic Commerce Indicator retornado no processo de autenticação. número 1 posição Sim.
Payment.ExternalAuthentication.Version Versão do 3DS utilizado no processo de autenticação. alfanumérico 1 posição Sim, quando a versão do 3DS for “2” ou maior.
Payment.ExternalAuthentication.ReferenceID RequestID retornado no processo de autenticação. GUID 36 posições Sim, quando a versão do 3DS for “2” ou maior.

Resposta

Consulte o Manual do Pagador para exemplos detalhados de resposta de autorização com autenticação.

Autorização para transações Data Only

Após a conclusão da autenticação do portador do cartão no modelo Data Only (com o campo bpmpi_auth_notifyonly como “true”), a loja deve submeter a transação ao processo de autorização, enviando os dados de autenticação no modelo de “autenticação externa” (nó ExternalAuthentication), tanto para 3DS Server Braspag quanto para 3DS Server externo.

Veja a seguir um exemplo de requisição de autorização à API do Pagador:

Requisição

{  
   "MerchantOrderId":"2017051002",
   "Customer":
   {  
     (...)
   },
   "Payment":
   {  
     (...)
     "Authenticate":false,
     "ReturnUrl":"http://www.loja.com.br",
     "CreditCard":{  
         "CardNumber":"4000000000001000",
         "Holder":"Nome do Portador",
         "ExpirationDate":"12/2021",
         "SecurityCode":"123",
         "Brand":"Visa",
         "SaveCard":"false"
     },
     "ExternalAuthentication":{
       "Eci":"4",
       "ReferenceID":"a24a5d87-b1a1-4aef-a37b-2f30b91274e6",
       "dataonly":true
     }
   }
}
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
--header "MerchantKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
--data-binary
--verbose
{  
   "MerchantOrderId":"2017051002",
   "Customer":
   {  
     (...)
   },
   "Payment":
   {  
     (...)
     "Authenticate":false,
     "ReturnUrl":"http://www.loja.com.br",
     "CreditCard":{  
         "CardNumber":"4000000000001000",
         "Holder":"Nome do Portador",
         "ExpirationDate":"12/2021",
         "SecurityCode":"123",
         "Brand":"Visa",
         "SaveCard":"false"
     },
     "ExternalAuthentication":{
       "Eci":"4",
       "ReferenceID":"a24a5d87-b1a1-4aef-a37b-2f30b91274e6",
       "dataonly":true
     }
   }
}
Campo Descrição Tipo Tamanho Obrigatório
Payment.Authenticate Define se o comprador será direcionado ao emissor para autenticação do cartão. booleano (“true” / “false”) - Sim. No caso de transação Data Only, é obrigatório enviar como “false”.
Payment.ExternalAuthentication.Eci E-Commerce Indicator retornado no processo de autenticação. número 1 posição Sim.
Payment.ExternalAuthentication.ReferenceId RequestID retornado no processo de autenticação. GUID 36 posições Sim.
Payment.ExternalAuthentication.DataOnly Define se é uma transação Data Only. booleano (“true” / “false”) - Sim. No caso de transação Data Only, é obrigatório enviar como “true”.

Resposta

Consulte o Manual do Pagador para exemplos detalhados de resposta de autorização com autenticação.

Cartões de teste

Use os cartões de teste a seguir para simular diversos cenários no ambiente sandbox.

Cartões de teste com desafio

CARTÃO BANDEIRA RESULTADO CENÁRIO
4000000000001091
5200000000001096
6505290000001234
VISA
MASTER
ELO
SUCCESS Autenticação com desafio e portador autenticado com sucesso.
4000000000001109
5200000000001104
6505050000001109
VISA
MASTER
ELO
FAILURE Autenticação com desafio e portador autenticado com falha.
4000000000001117
5200000000001112
6505050000001117
VISA
MASTER
ELO
UNENROLLED Autenticação com desafio indisponível no momento.
4000000000001125
5200000000001120
6505050000001125
VISA
MASTER
ELO
UNENROLLED Erro de sistema durante a etapa de autenticação.

Cartões de Teste sem desafio

CARTÃO BANDEIRA RESULTADO CENÁRIO
4000000000001000
5200000000001005
6505050000001000
VISA
MASTER
ELO
SUCCESS Autenticação sem desafio e portador autenticado com sucesso.
4000000000001018
5200000000001013
6505050000001018
VISA
MASTER
ELO
FAILURE Autenticação sem desafio e portador autenticado com falha.

ANEXO

Lista de Return Codes

São retornados como resposta à execução do script e também após autorização.

Na tabela a seguir, apresentamos os Return Codes que podem retornar como resultado de uma requisição.

Reason Code Descrição
100 Transação realizada com sucesso.
101 Está faltando um ou mais campos obrigatórios na requisição.
Ação possível: confira os campos missingField_0 até missingField_N na resposta. Envie a requisição novamente com a informação completa.
102 Um ou mais campos da requisição contêm dados inválidos.
Ação possível: confira os campos invalidField_0 até invalidField_N na resposta. Reenvie a requisição com a informação correta.
150 Erro: falha geral no sistema.
Ação possível: aguarde alguns minutos e envie a requisição novamente.
151 Erro: a requisição foi recebida, mas houve time-out do servidor. Esse erro não inclui time-outs entre cliente e servidor.
Ação possível: aguarde alguns minutos e envie a requisição novamente.
152 Erro: a requisição foi recebida, mas houve time-out de serviço.
Ação possível: aguarde alguns minutos e envie a requisição novamente.
234 Há um problema na sua configuração de merchant.
Ação possível: não envie a requisição novamente. Entre em contato com o suporte da Braaspag para corrigir o problema de configuração.
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.
Ação possível: 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.