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:
- Integração facilitada via Java Script;
- Possibilidade de autenticação "silenciosa" (isenção do desafio);
- Minimiza transações com fraudes;
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:
- Ter afiliação da API E-Commerce Cielo;
- Ter o cadastro de 3DS 2.0 (solicitar para o Suporte E-commerce);
- Concluir a integração técnica do fluxo de autenticação;
- Concluir a integração técnica do fluxo de autorização;
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
- O Portador preenche os dados do cartão no checkout do estabelecimento.
- O Estabelecimento aciona a solução 3DS 2.0 da Cielo via script para autenticação.
- A solução 3DS 2.0 da Cielo envia ao MPI (plataforma de autenticação) os dados do comprador.
- 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.
- A Bandeira retorna a URL de autenticação ao MPI.
- O MPI retorna a URL de autenticação à solução 3DS 2.0.
- A solução 3DS 2.0 retorna a URL de Autenticação ao estabelecimento via script.
- O script apresenta a tela da autenticação via lightbox.
- O portador resolve o desafio na tela do emissor.
- O emissor retorna o resultado da autenticação à Bandeira.
- A Bandeira retorna o resultado da autenticação ao MPI.
- O MPI retorna o resultado da autenticação à solução 3DS 2.0.
- A solução 3DS 2.0 retorna o resultado da autenticação ao estabelecimento via script (CAVV, ECI e XID).
- O estabelecimento envia uma requisição de autorização com os dados da autentiação à API Cielo 3.0.
- A API Cielo 3.0 retorna o resultado da autorização ao estabelecimento.
- O estabelecimento informa o resultado do pagamento..
Fluxo de Pagamento 3DS 2.0 sem desafio
- O Portador preenche os dados do cartão no checkout do estabelecimento
- O Estabelecimento aciona a solução 3DS 2.0 da Cielo via script para autenticação
- A solução 3DS 2.0 da Cielo envia ao MPI (plataforma de autenticação) os dados do comprador
- 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.
- A Bandeira retorna o resultado da autenticação silenciosa (CAVV e ECI)
- O MPI retorna o resultado da autenticação silenciosa à solução 3DS 2.0
- A solução 3DS 2.0 retorna o resultado da autenticação silenciona ao estabelecimento via script
- O estabelecimento envia uma requisição de autorização com os dados da autentiação à API Cielo 3.0
- A API Cielo 3.0 retorna o resultado da autorização ao estabelecimento
- 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:
- Etapa 1: Autenticação
- Etapa 2: Autorização
O fluxo abaixo descreve as etapas em alto nível:
- O portador escolhe pagar com cartão de crédito ou débito
- O estabelecimento solicita a autenticação através da solução Cielo
- 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.
- O estabelecimento apresenta a interface de autenticação no lightbox (URL de Autenticação do emissor)
- O portador se autentica no emissor (processo conhecido como realizar o desafio )
- O emissor retorna o resultado da autenticação à plataforma 3DS, que por sua vez repassa para o estabelecimento
- 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
- 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
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:
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