Cartão de crédito

Autenticação 3DS

Protocolo que confirma o portador do cartão e transfere o risco de chargeback por fraude ao emissor.

O 3-D Secure (EMV 3DS) confirma se quem paga é o portador do cartão, no crédito ou no débito, em venda sem o cartão presente. Os dados do comprador seguem para a bandeira e para o emissor.

A BW disponibiliza o protocolo 3DS 2.2.0. A integração é feita com um script no checkout. Há autenticação silenciosa, sem desafio, e autenticação com desafio (código no aplicativo do banco ou SMS).

Quando a transação é autenticada, o risco de chargeback por fraude passa ao emissor ou à bandeira. Essa transferência se chama liability shift. Qualquer e-commerce pode usar o 3DS como camada extra. É preciso ter o cartão habilitado na BW e concluir os fluxos de autenticação e de autorização.

Bandeiras no 3DS

Versão	Bandeiras
3DS 2.2	Visa e Mastercard
3DS 2.1	Elo e American Express

Script e inicialização

O endereço do script é informado na habilitação do cartão. Referencie esse endereço na página. Não baixe o arquivo para o seu servidor: assim o checkout permanece na versão atual.

O objeto global exposto pelo script é BW.Mpi.

JavaScript

var config = {
  IsEnabled: true,
  IsSandbox: true,
  IsDebug: true,
  IsChallengeSuppressed: false
};

BW.Mpi.Init(config, 150.35);

Atributo	Tipo	Descrição
IsEnabled	boolean	Envia ou não a transação para autenticação.
IsSandbox	boolean	true usa sandbox. false usa produção.
IsDebug	boolean	true escreve o relatório no console do navegador.
IsChallengeSuppressed	boolean	true ignora o desafio. Se a venda for autorizada mesmo assim, o risco permanece com o estabelecimento.
Amount	decimal	Valor total da transação, segundo argumento de Init.

Eventos

Os eventos acompanham o processo. Quem define se houve autenticação, e de quem é o risco, é o ECI. Dá para autorizar uma transação não autenticada; nesse caso o chargeback fica com o estabelecimento.

Evento	Quando ocorre	Risco se autorizar
onReady	O script carregou e o token de acesso foi validado. O checkout pode autenticar.	—
onSuccess	Cartão elegível e autenticação concluída. Voltam Cavv, Xid e Eci.	Emissor
onFailure	Cartão elegível, autenticação falhou. Volta o Eci.	Estabelecimento
onUnenrolled	Portador ou emissor não participam do 3DS. Oriente o comprador a verificar o cartão no banco.	Estabelecimento
onDisabled	A loja desligou a autenticação (bpmpi_auth = false).	Estabelecimento
onError	Erro sistêmico na autenticação. A resposta traz ReturnCode e ReturnMessage.	Estabelecimento
onUnsupportedBrand	A bandeira não entra no 3DS.	—

JavaScript

BW.Mpi.addEventListener("onSuccess", function (e) {
  var cavv = e.Cavv;
  var xid = e.Xid;
  var eci = e.Eci;
  var version = e.Version;
  var referenceId = e.ReferenceId;
});

Atributo	Tipo	Descrição
Cavv	texto	Assinatura da autenticação.
Xid	texto	Identificador da requisição de autenticação.
Eci	número	Resultado da autenticação.
Version	número	Versão do 3DS usada.
ReferenceId	guid	Request ID da autenticação.
ReturnCode	texto	Código de retorno, em erro.
ReturnMessage	texto	Mensagem de retorno, em erro.

Em Data Only (bpmpi_auth_notifyonly = true), mesmo com sucesso, Cavv e Xid não voltam. Esses campos não são usados nesse modelo.

Solicitar a autenticação

Monte o objeto com os campos obrigatórios e chame BW.Mpi.Checkout. O resultado chega nos eventos. Envie Cavv, Xid, Eci, Version e ReferenceId ao backend e, de lá, para PaymentObject.ExternalAuthentication na criação da cobrança.

JavaScript

var paymentObject = {
  currency: "BRL",
  installments: "01",
  cardnumber: "4000000000001091",
  cardexpirationmonth: "01",
  cardexpirationyear: "2028",
  cardalias: "JOAO DA SILVA"
};

BW.Mpi.Checkout(paymentObject);

Quanto mais campos o emissor recebe, maior a chance de autenticação silenciosa. Os obrigatórios do pedido e da cobrança estão abaixo. Os demais aumentam a qualidade da análise.

Campo	Obrigatório	Descrição
installments	Sim	Parcelas, até 2 dígitos.
cardnumber	Sim	Número do cartão, até 19 dígitos.
cardexpirationmonth	Sim	Mês de validade, 2 dígitos.
cardexpirationyear	Sim	Ano de validade, 4 dígitos.
cardalias	Não	Nome impresso, até 128 caracteres.
order_productcode	Sim	PHY mercadoria, CHA cheque, ACF financiamento, QCT quase-dinheiro, PAL recarga.
billto_contactname	Sim	Nome do contato de cobrança, até 120 caracteres.
billTo_phonenumber	Sim	Telefone com DDI e DDD, até 15 dígitos. Ex.: 5551999999999.
billTo_email	Sim	E-mail de cobrança.
billTo_street1	Sim	Logradouro e número, até 60 caracteres.
billTo_street2	Sim	Complemento e bairro, até 60 caracteres.
billTo_city	Sim	Cidade, até 50 caracteres.
billTo_state	Sim	UF, 2 letras.
billto_zipcode	Sim	CEP, 8 dígitos.
billto_country	Sim	País, 2 letras. Ex.: BR.
order_recurrence	Sim	true quando o pedido gera cobranças futuras.
recurring_occurrence	Na recorrência	03 semanal, 06 mensal, 10 semestral, 11 anual.

Campos opcionais

Campo	Descrição
default_card	Cartão padrão do cliente na loja.
order_countlast24hours	Pedidos deste comprador nas últimas 24 horas.
order_countlast6months	Pedidos deste comprador nos últimos 6 meses.
order_countlast1year	Pedidos deste comprador no último ano.
order_cardattemptslast24hours	Tentativas com o mesmo cartão nas últimas 24 horas.
order_marketingoptin	Comprador aceitou ofertas.
order_marketingsource	Origem da campanha, até 40 caracteres.
billto_customerid	CPF ou CNPJ, 11 a 14 dígitos.
shipto_sameasbillto	Entrega no mesmo endereço de cobrança.
shipto_addressee	Nome de quem recebe.
shipTo_phonenumber	Telefone de entrega.
shipTo_email	E-mail de entrega.
shipTo_street1	Logradouro e número de entrega.
shipTo_street2	Complemento e bairro de entrega.
shipTo_city	Cidade de entrega.
shipTo_state	UF de entrega.
shipto_zipcode	CEP de entrega.
shipto_country	País de entrega.
shipTo_shippingmethod	lowcost, sameday, oneday, twoday, threeday, pickup, other ou none.
shipto_firstusagedate	Primeiro uso desse endereço, AAAA-MM-DD.
recurring_type	1 na primeira transação da recorrência.
recurring_maximumAmount	Valor máximo acordado com o titular.
recurring_referenceNumber	Referência da recorrência, até 35 caracteres.
recurring_numberOfPayments	Quantidade de pagamentos da assinatura.
recurring_amountType	1 para recorrência de valor fixo.

Tabela do ECI

O ECI (Electronic Commerce Indicator) é o código da bandeira com o resultado da autenticação. A loja decide se segue para autorização. Sem autenticação, o risco de chargeback continua com o estabelecimento. Envie o ECI em PaymentObject.ExternalAuthentication.Eci.

Resultado	Autenticada	Mastercard	Visa	Elo	Amex
Autenticada pelo emissor. Risco do emissor.	Sim	02	05	05	05
Autenticada pela bandeira. Risco do emissor.	Sim	01	06	06	06
Não autenticada. Risco do estabelecimento.	Não	Diferente de 01, 02 e 04	Diferente de 05 e 06	Diferente de 05 e 06	Diferente de 05 e 06
Não autenticada, Data Only. Risco do estabelecimento.	Não	04	7	—	—

Downgrade de ECI

No 3DS 2.0 o ECI final pode ser diferente do ECI com que a autenticação começou. Isso é downgrade: a transação saiu como autenticada (por exemplo ECI 02 na Mastercard) e a resposta de autorização chega como não autenticada (ECI 7 ou 0). O emissor ou o diretório não autenticou o cartão.

O downgrade é síncrono. A resposta da autorização já traz o ECI final. Não há consulta posterior para descobrir esse valor.

Códigos de retorno

Estes códigos voltam na execução do script e também depois da autorização.

Código	Significado	O que fazer
100	Transação realizada com sucesso.	Seguir o fluxo.
101	Falta um ou mais campos obrigatórios.	Leia missingField_0 até missingField_N e reenvie completo.
102	Um ou mais campos têm dado inválido.	Leia invalidField_0 até invalidField_N e corrija.
150	Falha geral no sistema.	Aguarde alguns minutos e tente de novo.
151	A requisição chegou, mas o servidor estourou o tempo.	Aguarde alguns minutos e tente de novo.
152	A requisição chegou, mas um serviço estourou o tempo.	Aguarde alguns minutos e tente de novo.
234	Problema na configuração da conta.	Não reenvie. Fale com o suporte da BW.
475	O cliente está inscrito na autenticação do pagador.	Autentique o portador antes de autorizar.
476	O cliente não pôde ser autenticado.	Revise o pedido.
MPI900	Ocorreu um erro.	Trate como falha de autenticação.
MPI901	Erro inesperado.	Trate como falha de autenticação.
MPI902	Resposta inesperada da autenticação.	Trate como falha de autenticação.
MPI600	A bandeira não suporta a autenticação.	Siga sem 3DS e assuma o risco, ou troque o meio.
MPI601	Desafio omitido.	O risco permanece com o estabelecimento.