Autenticação 3DS 2.0

O que é 3DS 2.0?

Com o objetivo de minimizar o índice de fraude sem prejudicar a taxa de conversão, a indústria de meio de pagamento desenvolveu o padrão de autenticação EMV 3DS, também chamado de 3DS 2.0. A nova versão é capaz de analisar dezenas de variáveis que são utilizadas como critérios para determinar se um comprador é de fato o portador cartão, permitindo em alguns casos, a autenticação silenciosa do mesmo (autenticação sem desafio), sem prejuízo à questão do Liability Shift dos estabelecimentos.

Principais benefícios:

Palavras chaves: Autenticação de Cartão de Crédito e Débito, EMVCO, 3DS 2.0, Visa, Mastercard, E-Commerce

Quem pode usar o 3DS 2.0?

O 3DS 2.0 é válido para todas as transações de eCommerce, sejam de débito, crédito ou pré-pago. Aos segmentos que possuem alto índice de chargeback/fraude, a solução tende a ser ainda mais vantajosa frente ao benefício de passar o liability shift ao banco emissor.

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

O estabelecimento comercial deve atender aos requisitos abaixo para a utilização do 3DS 2.0:

O que é o Data Only – Somente Notificação

O Data Only é um campo opcional ao lojista que poderá ser utilizado exclusivamente para cartões Mastercard. Para esses casos, o ECI será sempre 04.

Para utilizá-lo, deverá ser parametrizado 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.0 são mapeados da mesma forma, e enviados para a Mastercard e Bancos Emissores, porém, sem solicitar a autenticação.

O benefício do uso do Data Only é enriquecer o banco de dados dos Bancos Emissores e da Mastercard, que passará a receber mais informações sobre os portadores de cada lojista. Esse campo busca aprimorar a autenticação silenciosa e o índice de aprovação dos Emissores, considerando o contexto atual onde o mercado está evoluindo para a integração com o novo protocolo de autenticação 2.0. Além disso, a partir de Maio de 2019, a bandeira Mastercard cobrará um fee adicional por transação não autenticada do adquirente, que poderá impactar no preço negociado entre a Cielo e o estabelecimento. O Data Only isenta o valor do fee cobrado.

Vale destacar que nesse modelo, visto que não há autenticação do Emissor, o risco de chargeback por fraude permanece com o lojista.

Fluxo de Pagamento 3DS 2.0 com desafio

Fluxo com desafio 01 Fluxo com desafio 02

  1. O Portador preenche os dados do cartão no checkout do estabelecimento.
  2. O Estabelecimento aciona a solução 3DS 2.0 da Cielo via script para autenticação.
  3. A solução 3DS 2.0 da Cielo envia ao MPI (plataforma de autenticação) os dados do comprador.
  4. O MPI se comunica com a Bandeira para processar a autenticação. A Bandeira identifica o emissor do cartão, e envia dos dados do comprador para análise. O emissor identifica o portador como um possível risco, desta forma, exige o desafio e retorna a URL de Autenticação.
  5. A Bandeira retorna a URL de autenticação ao MPI.
  6. O MPI retorna a URL de autenticação à solução 3DS 2.0.
  7. A solução 3DS 2.0 retorna a URL de Autenticação ao estabelecimento via script.
  8. O script apresenta a tela da autenticação via lightbox.
  9. O portador resolve o desafio na tela do emissor.
  10. O emissor retorna o resultado da autenticação à Bandeira.
  11. A Bandeira retorna o resultado da autenticação ao MPI.
  12. O MPI retorna o resultado da autenticação à solução 3DS 2.0.
  13. A solução 3DS 2.0 retorna o resultado da autenticação ao estabelecimento via script (CAVV, ECI e XID).
  14. O estabelecimento envia uma requisição de autorização com os dados da autentiação à API Cielo 3.0.
  15. A API Cielo 3.0 retorna o resultado da autorização ao estabelecimento.
  16. O estabelecimento informa o resultado do pagamento..

Fluxo de Pagamento 3DS 2.0 sem desafio

Fluxo se desafio

  1. O Portador preenche os dados do cartão no checkout do estabelecimento
  2. O Estabelecimento aciona a solução 3DS 2.0 da Cielo via script para autenticação
  3. A solução 3DS 2.0 da Cielo envia ao MPI (plataforma de autenticação) os dados do comprador
  4. O MPI se comunica com a Bandeira para processar a autenticação. A Bandeira identifica o emissor do cartão, e envia dos dados do comprador para análise.
  5. A Bandeira retorna o resultado da autenticação silenciosa (CAVV e ECI)
  6. O MPI retorna o resultado da autenticação silenciosa à solução 3DS 2.0
  7. A solução 3DS 2.0 retorna o resultado da autenticação silenciona ao estabelecimento via script
  8. O estabelecimento envia uma requisição de autorização com os dados da autentiação à API Cielo 3.0
  9. A API Cielo 3.0 retorna o resultado da autorização ao estabelecimento
  10. O estabelecimento informa o resutlado do pagamento

Como funciona a autorização com autenticação via 3DS 2.0?

O processo de autorização de cartão autenticada via 3DS 2.0 ocorre em duas etapas:

  1. Etapa 1: Autenticação
  2. Etapa 2: Autorização

O fluxo abaixo descreve as etapas em alto nível:

Fluxo 3DS 2.0

  1. O portador escolhe pagar com cartão de crédito ou débito
  2. O estabelecimento solicita a autenticação através da solução Cielo
  3. A plataforma de autenticação poderá seguir um dos dois fluxos: requisitar a autenticação do portador ou realizar a autenticação de forma silenciosa. No primeiro caso, a plataforma retornará a URL de Autenticação ao estabelecimento. No segundo caso, o passo seguinte já é o retorno com o resultado da autenticação.
  4. O estabelecimento apresenta a interface de autenticação no lightbox (URL de Autenticação do emissor)
  5. O portador se autentica no emissor (processo conhecido como realizar o desafio )
  6. O emissor retorna o resultado da autenticação à plataforma 3DS, que por sua vez repassa para o estabelecimento
  7. O estabelecimento poderá ou não, seguir com o processo de autorização. Quando optar por autorizar deverá submeter o resultado da autenticação no contrato técnico de autorização
  8. A Cielo retorna o resultado da autorização para o estabelecimento, que por sua vez, retorna para o portador

E-Commerce Indicator (ECI)

O E-Commerce Indicator (ECI) é retornado no processo de autenticação. Este código é um indicador do que exatamente ocorreu no processo de autenticação da transação.

Por meio do ECI, pode-se verificar se a transação foi autenticada e quem foi o agente responsável por aquela autenticação. Confira a tabela de ECI.

Integração 3DS via Javascript

1. Solicitando o Token de Acesso

A solução é composta pelo passo de solicitação de token de acesso via API e solicitação de autenticação via Java Script.

Ambiente Endpoint Authorization
SANDBOX https://mpisandbox.braspag.com.br Basic (Authorization)
O valor do Authorization deve ser obtido concatenando-se o valor do “ClientID”, sinal de dois-pontos (“:”) e “ClientSecret”
Ex. dba3a8db-fa54-40e0-8bab-7bfb9b6f2e2e:D/ilRsfoqHlSUChwAMnlyKdDNd7FMsM7cU/vo02REag=
e na sequência, codificar o resultado na base 64.
Com isso, será gerado um código alphanumérico que será utilizado na requisição de access token. Para efeitos de teste, utilize os dados abaixo:
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 Numérico [10 posições]
MerchantName Nome do estabelecimento registrado na Cielo Alfanumérico [até 25 posições]
MCC Código de Categoria do estabelecimento Numérico [4 posições]

Resposta

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjbGllbnRfbmFtZSI6IlFBXzNEU19BdXRoZW50aWNhdG9yIiwiY2xpZW50X2lkIjoiZGJhM2E4ZGItZmE1NC00MGUwLThiYWItN2JmYjliNmYyZTJlIiwic2NvcGVzIjoie1wiU2NvcGVcIjpcIjNEU0F1dGhlbnRpY2F0b3JcIixcIkNsYWltc1wiOlt7XCJOYW1lXCI6XCJNZXJjaGFudE5hbWVcIixcIlZhbHVlc1wiOFwiVmFsdWVzXCI6W1wiNTU1NVwiXX0se1wiTmFtZVwiOlwiUmVmZXJlbmNlSWRcIixcIlZhbHVlc1wiOltcImY3MjE1YmQ3LWM0OTQtNGQ5Yi1NzEyfQ.daMqXko3dZOV0TzNFQ2vSsVSKqOsrwuswg7RB82ecAASSSSSSSSSSSSFFFFFFFFFFFFFGGGGGGGGGGGGGGGGGGGGGGGG",
  "token_type": "barear",
  "expires_in": "2018-07-23T11:29:32"
}
--header "Content-Type: application/json"
--data-binary
{
      "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjbGllbnRfbmFtZSI6IlFBXzNEU19BdXRoZW50aWNhdG9yIiwiY2xpZW50X2lkIjoiZGJhM2E4ZGItZmE1NC00MGUwLThiYWItN2JmYjliNmYyZTJlIiwic2NvcGVzIjoie1wiU2NvcGVcIjpcIjNEU0F1dGhlbnRpY2F0b3JcIixcIkNsYWltc1wiOlt7XCJOYW1lXCI6XCJNZXJjaGFudE5hbWVcIixcIlZhbHVlc1wiOFwiVmFsdWVzXCI6W1wiNTU1NVwiXX0se1wiTmFtZVwiOlwiUmVmZXJlbmNlSWRcIixcIlZhbHVlc1wiOltcImY3MjE1YmQ3LWM0OTQtNGQ5Yi1NzEyfQ.daMqXko3dZOV0TzNFQ2vSsVSKqOsrwuswg7RB82ecAASSSSSSSSSSSSFFFFFFFFFFFFFGGGGGGGGGGGGGGGGGGGGGGGG",
      "token_type": "barear",
      "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. Implementando o script

Neste passo, é implementado o script e o mapeamento de classes responsáveis pela comunicação com as plataformas de autenticação das bandeiras e emissor. Siga o exemplo abaixo, 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, Acesse aqui

Fluxo 3DS 2.0

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 que indica se a transação foi autenticada ou não e de quem é o risco de chargeback é o valor retornado no ECI (E-commerce Indicator). 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 incluir 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 retornados. Estes dados devem ser enviados na requisição no momento da 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 não teve o processo de autenticação falhou por algum motivo. Neste caso, somente a variável ECI será retornado. Caso haja a decisão de seguir com a autorização mesmo assim, o ECI deverá ser enviado no momento da requisiçã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á retornado. Caso haja a decisão de seguir com a autorização mesmo assim, o ECI deverá ser enviado no momento da requisiçã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 é suportado pelo 3DS 2.0

Descrição dos Parâmetros de entrada

Parâmetro Descrição Tipo/Tamanho
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 é ativado ou não. Quando true, a plataforma emitirá o relatório no mecanismo de debug do browser. Booleanotrue – modo debug ativadofalse – modo debug desativado

IMPORTANTE!

O arquivo JavaScript deve ser salvo no servidor onde está a aplicação da loja. Para baixar o arquivo no Sandbox, 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 Numérico [1 posição]1 – 3DS 1.02 – 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 [varivável]

Nota: No caso de uma transação submetida como Data Only (bpmpi_auth_notifyonly como true), mesmo que bem-sucedida, não serão retornados os campos CAVV e XID (campos não necessários para uma transação no modelo Data Only).

3. Mapeando 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.

Categoria dos dados Campos Descrição Tipo/Tamanho Obrigatório
Parametrização bpmpi_auth Booleano que indica se a transação é submetida o 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” - Data Only. 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
Não
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
Não
Parametrização bpmpi_accesstoken Token gerado pela API de Token de Acesso (etapa 1) Alfanumérico (variável) Sim
Parametrização bpmpi_challenge_window_size Parametrização do tamanho da janela do desafio string
Valores aceitos:
250x400
390x400
500x600
600x400
FullPage
Não
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] Não
Pedido bpmpi_default_card Indica se é um cartão padrão do cliente na loja Booleano
true - sim
false - não
Não
Características do pedido bpmpi_recurring_enddate Identifica a data de término da recorrência Texto (AAAA-MM-DD) Não
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
Não
Características do pedido bpmpi_recurring_originalpurchasedate Identifica a data da 1ª transação que originou a recorrência Texto (AAAA-MM-DD) Não
Características do pedido bpmpi_order_recurrence Indica se é um pedido que gera recorrências futuras Booleano
true
false
Não
Características do pedido bpmpi_order_productcode Tipoda 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] Não
Características do pedido bpmpi_order_countlast6months Quantidade de pedidos efetuados por este comprador nos últimos 6 meses Numérico [até 4 posições] Não
Características do pedido bpmpi_order_countlast1year Quantidade de pedidos efetuados por este comprador no último ano Numérico [até 3 posições] Não
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] Não
Características do pedido bpmpi_order_marketingoptin Indica se o comprador aceitou receber ofertas de marketing Booleano
true – sim
false – não
Não
Características do pedido bpmpi_order_marketingsource Identifica a origem da campanha de marketing Alfanumérico [até 40 posições] Não
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
Não
Características do pedido bpmpi_merchant_url Endereço do site do estabelcimento Alphanumérico [100] Exemplo: http://www.exemplo.com.br Sim
Cartão pré-pago 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
Não
Cartão pré-pago bpmpi_giftcard_currency Código da moeda da transação paga com cartão do tipo pré-pago Fixo "BRL" Não
Endereço de cobrança bpmpi_billto_customerid Identifica o CPF/CNPJ do comprador Numérico [11 a 14 posições]
99999999999999
Não
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
Não
Endereço de entrega bpmpi_shipto_addressee Nome do contato do endereço de entrega Alfanumérico [até 60] Não
Endereço de entrega bpmpi_shipTo_phonenumber Telefone de contato do endereço de entrega Numérico [até 15 posições], no formato: 5511999999999 Não
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 Não
Endereço de entrega bpmpi_shipTo_street1 Logradouro e Número do endereço de entrega Alfanumérico [até 60] Não
Endereço de entrega bpmpi_shipTo_street2 Complemento e bairro do endereço de entrega Alfanumérico [até 60] Não
Endereço de entrega bpmpi_shipTo_city Cidade do endereço de entrega Alfanumérico [até 50] Não
Endereço de entrega bpmpi_shipTo_state Sigla do estado do endereço de entrega Texto [2 posições] Não
Endereço de entrega bpmpi_shipto_zipcode CEP do endereço de entrega Alfanumérico [até 8 posições], no formato: 99999999 Não
Endereço de entrega bpmpi_shipto_country País do endereço de cobrança Texto [2 posições] Ex. BR Não
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
Não
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
Não
Carrinho de compras bpmpi_cart_#_description Descrição do item Alfanumérico [até 255 posições] Não
Carrinho de compras bpmpi_cart_#_name Nome do item Alfanumérico [até 255 posições] Não
Carrinho de compras bpmpi_cart_#_sku SKU do item Alfanumérico [até 255 posições] Não
Carrinho de compras bpmpi_cart_#_quantity Quantidade do item no carrinho Numérico [até 10 posições] Não
Carrinho de compras bpmpi_cart_#_unitprice Valor unitário do item do carrinho em centavos Numérico [até 10 posições] Não
Usuário bpmpi_useraccount_guest Indica se o comprador é um comprador sem login (guest) Booleano
true – sim
false – não
Não
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
Não
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
Não
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
Não
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
Não
Usuário bpmpi_useraccount_authenticationprotocol Dado que representa o protocolo de login efetuado na loja Alfanumérico [até 2048 posições] Não
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 Não
Usuário bpmpi_merchant_newcustomer Identifica se um comprador novo na loja Booleano
true – sim
false – não
Não
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] Não
Dispositivo bpmpi_device_#_provider Nome do provedor do Device Finger Print Alfanumérico [até 32 posições] cardinal
inauth
threatmetrix
Não
Dispositivo bpmpi_device_channel Canal por onde chegou a transação. Valores possíveis:
- Browser
- SDK
- 3RI
Alfanúmerico [até 7 posições] Não
Companhias Aéreas bpmpi_airline_travelleg_#_carrier Código IATA para o trecho Alfanumérico [2 posições] Não
Companhias Aéreas bpmpi_airline_travelleg_#_departuredate Data de partida Texto
AAAA-MM-DD
Não
Companhias Aéreas bpmpi_airline_travelleg_#_origin Código IATA do aeroporto de origem Alfanumérico [5 posições] Não
Companhias Aéreas bpmpi_airline_travelleg_#_destination Código IATA do aeroporto de destino Alfanumérico [5 posições] Não
Companhias Aéreas bpmpi_airline_passenger_#_name Nome do passageiro Alfanumérico [até 60 posições] Não
Companhias Aéreas bpmpi_airline_passenger_#_ticketprice O valor da passagem em centavos Numérico [até 15 posições],
exemplo: R$ 125,54 = 12554
Não  
Companhias Aéreas bpmpi_airline_numberofpassengers Número de passageiros Numérico [3 posições] Não
Companhias Aéreas bpmpi_airline_billto_passportcountry Código do país que emitiu o passaporte (ISO Standard Country Codes) Texto [2 posições] Não
Companhias Aéreas bpmpi_airline_billto_passportnumber Número do passaporte Alfanumérico [40 posições] Não
Dados definidos pela loja bpmpi_mdd1 Dado Extra definido pelo lojista Alfanumérico [até 255 posições] Não
Dados definidos pela loja bpmpi_mdd2 Dado Extra definido pelo lojista Alfanumérico [até 255 posições] Não
Dados definidos pela loja bpmpi_mdd3 Dado Extra definido pelo lojista Alfanumérico [até 255 posições] Não
Dados definidos pela loja bpmpi_mdd4 Dado Extra definido pelo lojista Alfanumérico [até 255 posições] Não
Dados definidos pela loja bpmpi_mdd5 Dado Extra definido pelo lojista Alfanumérico [até 255 posições] Não

4. Implementando chamada ao evento de autenticação

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

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

ECI (E-commerce Indicator)

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. Confira na tabela a seguir os ECIs correspondentes à cada bandeira e o resultado da autenticação.

Posteriormente, o valor do ECI deverá ser enviado 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 - - - Não autenticada, transação caracterizada como Data Only – risco de chargeback permanece com o estabelecimento. Não

Cartões de Teste

Utilize os cartões de teste abaixo para simular diversos cenários no ambiente de SANDBOX.

Cartões de Teste com Desafio

CARTÃO BANDEIRA RESULTADO DESCRIÇÃO
4000000000001091
5200000000001096
6505050000001091
VISA
MASTER
ELO
SUCCESS Autenticação com desafio e portador autenticou com sucesso
4000000000001109
5200000000001104
6505050000001109
VISA
MASTER
ELO
FAILURE Autenticação com desafio e portador autenticou 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 DESCRIÇÃO
4000000000001000
5200000000001005
6505050000001000
VISA
MASTER
ELO
SUCCESS Autenticação sem desafio e portador autenticou com sucesso
4000000000001018
5200000000001013
6505050000001018
VISA
MASTER
ELO
FAILURE Autenticação sem desafio e portador autenticou com falha

Autorização com Autenticação

Após autenticação ser concluída, submete-se ao processo de autorização, enviando os dados de autenticação no modelo de "autenticação externa" (nó ExternalAuthentication ). Este procedimento é válido também para estabelecimentos que realizaram a autenticação fora da Cielo (MPI Externo).

Veja exemplo abaixo, descrito o envio dos dados de autenticação da requisição de autorização da API E-commerce Cielo:

Requisição

{
   "MerchantOrderId":"2017051002",
   "Customer":
   {
     (...)
   },
   "Payment":
   {
     (...)
     "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"
     }
   }
}
curl
--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":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.Authenticate Booleano que define se o comprador será direcionado ao Banco emissor para autenticação do cartão - Sim, para que a autenticação seja realizada é obrigatório enviar como true
Payment.ExternalAuthentication.Cavv Assinatura que é retornada nos cenários de sucesso na autenticação Texto Sim, quando a autenticação foi um sucesso
Payment.ExternalAuthentication.Xid XID retornado no processo de autenticação Texto Sim, quando a versão do 3DS for "1"
Payment.ExternalAuthentication.Eci E-Commerce Indicator retornado no processo de autenticação Numérico [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"
Payment.ExternalAuthentication.ReferenceId RequestID retornado no processo de autenticação GUID [36 posições] Sim, quando a versão do 3DS for "2"

Resposta

Veja mais: https://developercielo.github.io/manual/cielo-ecommerce#resposta

Autorização para transações Data Only

Após ter sido realizada a etapa de autenticação no modelo data only (enviando o campo bpmpi_auth_notifyonly como true) submete-se ao processo de autorização, enviando os dados de autenticação no modelo de "autenticação externa" (nó ExternalAuthentication ).

Veja exemplo abaixo, descrito o envio dos dados de autenticação da requisição de autorização da API E-commerce Cielo:

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
     }
   }
}
curl
--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 Booleano que define se o comprador será direcionado ao Banco emissor para autenticação do cartão - 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 Numérico [1 posição] Sim
Payment.ExternalAuthentication.ReferenceId RequestID retornado no processo de autenticação GUID [36 posições] Sim
Payment.ExternalAuthentication.DataOnly Booleano que define se é uma transação Data Only - Sim, no caso de transação Data Only é obrigatório enviar como true

Resposta

Veja mais: https://developercielo.github.io/manual/cielo-ecommerce#resposta