O que é 3DS 2.0?
Para maiores detalhes sobre o 3DS 2.0, acesse: https://developercielo.github.io/manual/3ds
Passo 1 - Solicitação de 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. |
Request
{
"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] |
Response
{
"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 |
Passo 2 - Implementação do 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
| 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, 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).
Passo 3 - Mapeamento de 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.
| Dados de Parametrização | Descrição | Tipo/Tamanho | Obrigatório |
|---|---|---|---|
| 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 |
| 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 |
| 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 |
| bpmpi_accesstoken | Token gerado pela API de Token de Acesso (etapa 1) | Alfanumérico [varivável] | Sim |
| Dados de Pedido | Descrição | Tipo/Tamanho | Obrigatório |
|---|---|---|---|
| bpmpi_ordernumber | Código do pedido no estabelecimento | Alphanumérico [até 50 posições] | Sim |
| bpmpi_currency | Código da moeda | Fixo "BRL" | Sim |
| bpmpi_totalamount | Valor total da transação, enviado em centavos | Numérico [até 15 posições] | Sim |
| bpmpi_installments | Número de parcelas da transação | Numérico [até 2 posições] | Sim |
| 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 |
| bpmpi_cardnumber | Número do Cartão | Numérico [até 19 posições] | Sim |
| bpmpi_cardexpirationmonth | Mês do vencimento do cartão | Numérico [2 posições] | Sim |
| bpmpi_cardexpirationyear | Ano do vencimento do cartão | Numérico [4 posições] | Sim |
| bpmpi_cardalias | Alias do cartão | Alphanumérico [até 128 posições] | Não |
| bpmpi_default_card | Indica se é um cartão padrão do cliente na loja | Booleano true - sim false - não |
Não |
| Dados das características do pedido | Descrição | Tipo/Tamanho | Obrigatório |
|---|---|---|---|
| bpmpi_recurring_enddate | Identifica a data de término da recorrência | Texto (AAAA-MM-DD) | Não |
| 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 |
| bpmpi_recurring_originalpurchasedate | Identifica a data da 1ª transação que originou a recorrência | Texto (AAAA-MM-DD) | Não |
| bpmpi_order_recurrence | Indica se é um pedido que gera recorrências futuras | Booleano true false |
Não |
| bpmpi_order_productcode | Tipoda compra | PHY: compra de mercadorias CHA: Check acceptance ACF: Financiamento de conta QCT: Transação quase-dinheiro PAL: recarga |
Sim |
| bpmpi_order_countlast24hours | Quantidade de pedidos efetuados por este comprador nas últimas 24h | Numérico [até 3 posições] | Não |
| bpmpi_order_countlast6months | Quantidade de pedidos efetuados por este comprador nos últimos 6 meses | Numérico [até 4 posições] | Não |
| bpmpi_order_countlast1year | Quantidade de pedidos efetuados por este comprador no último ano | Numérico [até 3 posições] | Não |
| bpmpi_order_cardattemptslast24hours | Quantidade de transações com o mesmo cartão nas últimas 24h | Numérico [até 3 posições] | Não |
| bpmpi_order_marketingoptin | Indica se o comprador aceitou receber ofertas de marketing | Booleano true – sim false – não |
Não |
| bpmpi_order_marketingsource | Identifica a origem da campanha de marketing | Alfanumérico [até 40 posições] | Não |
| bpmpi_transaction_mode | Identifica o canal que originou a transação | M: MOTO R: Varejo S: E-Commerce P: Mobile T: Tablet |
Não |
| bpmpi_merchant_url | Endereço do site do estabelcimento | Alphanumérico [100] Exemplo: http://www.exemplo.com.br | Sim |
| Dados específicos para cartões Gift Card (pré-pago) | Descrição | Tipo/Tamanho | Obrigatório |
|---|---|---|---|
| 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 |
| bpmpi_giftcard_currency | Código da moeda da transação paga com cartão do tipo pré-pago | Fixo "BRL" | Não |
| Dados de endereço de cobrança | Descrição | Tipo/Tamanho | Obrigatório |
|---|---|---|---|
| bpmpi_billto_customerid | Identifica o CPF/CNPJ do comprador | Numérico [11 a 14 posições] 99999999999999 |
Não |
| bpmpi_billto_contactname | Nome do contato do endereço de cobrança | Alfanumérico [até 120] | Sim |
| bpmpi_billTo_phonenumber | Telefone de contato do endereço de cobrança | Numérico [até 15 posições], no formato: 5511999999999 | Sim |
| bpmpi_billTo_email | E-mail do contato do endereço de cobrança | Alfanumérico [até 255], no formato nome@exemplo.com | Sim |
| bpmpi_billTo_street1 | Logradouro e Número do endereço de cobrança | Alfanumérico [até 60] | Sim |
| bpmpi_billTo_street2 | Complemento e bairro do endereço de cobrança | Alfanumérico [até 60] | Sim |
| bpmpi_billTo_city | Cidade do endereço de cobrança | Alfanumérico [até 50] | Sim |
| bpmpi_billTo_state | Sigla do estado do endereço de cobrança | Texto [2 posições] | Sim |
| bpmpi_billto_zipcode | CEP do endereço de cobrança | Alfanumérico [até 8 posições], no formato: 99999999 | Sim |
| bpmpi_billto_country | País do endereço de cobrança | Texto [2 posições] Ex. BR | Sim |
| Dados de endereço de entrega | Descrição | Tipo/Tamanho | Obrigatório |
|---|---|---|---|
| bpmpi_shipto_sameasbillto | Indica se utiliza o mesmo endereço fornecido para endereço de cobrança | Booleano true false |
Não |
| bpmpi_shipto_addressee | Nome do contato do endereço de entrega | Alfanumérico [até 60] | Não |
| bpmpi_shipTo_phonenumber | Telefone de contato do endereço de entrega | Numérico [até 15 posições], no formato: 5511999999999 | Não |
| bpmpi_shipTo_email | E-mail do contato do endereço de entrega | Alfanumérico [até 255], no formato nome@exemplo.com | Não |
| bpmpi_shipTo_street1 | Logradouro e Número do endereço de entrega | Alfanumérico [até 60] | Não |
| bpmpi_shipTo_street2 | Complemento e bairro do endereço de entrega | Alfanumérico [até 60] | Não |
| bpmpi_shipTo_city | Cidade do endereço de entrega | Alfanumérico [até 50] | Não |
| bpmpi_shipTo_state | Sigla do estado do endereço de entrega | Texto [2 posições] | Não |
| bpmpi_shipto_zipcode | CEP do endereço de entrega | Alfanumérico [até 8 posições], no formato: 99999999 | Não |
| bpmpi_shipto_country | País do endereço de cobrança | Texto [2 posições] Ex. BR | Não |
| 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 |
| 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 |
| Dados do carrinho de compras | Descrição | Tipo/Tamanho | Obrigatório | |
|---|---|---|---|---|
| bpmpi_cart_#_description | Descrição do item | Alfanumérico [até 255 posições] | Não | |
| bpmpi_cart_#_name | Nome do item | Alfanumérico [até 255 posições] | Não | Sim |
| bpmpi_cart_#_sku | SKU do item | Alfanumérico [até 255 posições] | Não | |
| bpmpi_cart_#_quantity | Quantidade do item no carrinho | Numérico [até 10 posições] | Não | |
| bpmpi_cart_#_unitprice | Valor unitário do item do carrinho em centavos | Numérico [até 10 posições] | Não |
| Dados do usuário | Descrição | Tipo/Tamanho | Obrigatório |
|---|---|---|---|
| bpmpi_useraccount_guest | Indica se o comprador é um comprador sem login (guest) | Booleano true – sim false – não |
Não |
| 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 |
| 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 |
| 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 |
| 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 |
| bpmpi_useraccount_authenticationprotocol | Dado que representa o protocolo de login efetuado na loja | Alfanumérico [até 2048 posições] | Não |
| 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 |
| bpmpi_merchant_newcustomer | Identifica se um comprador novo na loja | Booleano true – sim false – não |
Não |
| Dados do dispositivo utilizado para compra | Descrição | Tipo/Tamanho | Obrigatório |
|---|---|---|---|
| bpmpi_device_ipaddress | Endereço IP da máquina do comprador | Alfanumérico [até 45] | Não |
| bpmpi_device_#_fingerprint | Id retornado pelo Device Finger Print | Alfanumérico [sem limitação] | Não |
| bpmpi_device_#_provider | Nome do provedor do Device Finger Print | Alfanumérico [até 32 posições] cardinal inauth threatmetrix |
Não |
| Dados específicos para companhias aéreas | Descrição | Tipo/Tamanho | Obrigatório |
|---|---|---|---|
| bpmpi_airline_travelleg_#_carrier | Código IATA para o trecho | Alfanumérico [2 posições] | Não |
| bpmpi_airline_travelleg_#_departuredate | Data de partida | Texto AAAA-MM-DD |
Não |
| bpmpi_airline_travelleg_#_origin | Código IATA do aeroporto de origem | Alfanumérico [5 posições] | Não |
| bpmpi_airline_travelleg_#_destination | Código IATA do aeroporto de destino | Alfanumérico [5 posições] | Não |
| bpmpi_airline_passenger_#_name | Nome do passageiro | Alfanumérico [até 60 posições] | Não |
| bpmpi_airline_passenger_#_ticketprice | O valor da passagem em centavos Numérico [até 15 posições], exemplo: R$ 125,54 = 12554 |
Não | |
| bpmpi_airline_numberofpassengers | Número de passageiros | Numérico [3 posições] | Não |
| bpmpi_airline_billto_passportcountry | Código do país que emitiu o passaporte (ISO Standard Country Codes) | Texto [2 posições] | Não |
| bpmpi_airline_billto_passportnumber | Número do passaporte | Alfanumérico [40 posições] | Não |
| Dados extras do estabelecimento (caso aplicável) | Descrição | Tipo/Tamanho | Obrigatório |
|---|---|---|---|
| bpmpi_mdd1 | Dado Extra definido pelo lojista | Alfanumérico [até 255 posições] | Não |
| bpmpi_mdd2 | Dado Extra definido pelo lojista | Alfanumérico [até 255 posições] | Não |
| bpmpi_mdd3 | Dado Extra definido pelo lojista | Alfanumérico [até 255 posições] | Não |
| bpmpi_mdd4 | Dado Extra definido pelo lojista | Alfanumérico [até 255 posições] | Não |
| bpmpi_mdd5 | Dado Extra definido pelo lojista | Alfanumérico [até 255 posições] | Não |
Passo 4 - Implementação da 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)
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, conforme tabela abaixo:
| Bandeira | ECI | Significado da Transação |
|---|---|---|
| Visa | 05 | Autenticada pelo Banco Emissor – risco de chargeback passa a ser do banco Emissor |
| Visa | 06 | Autenticada pela Bandeira – risco de chargeback passa a ser do banco Emissor |
| Visa | Diferente de 05 e 06 | Não autenticada – risco de chargeback permanece com o estabelecimento |
| Mastercard | 01 | Autenticada pela Bandeira – risco de chargeback passa a ser do banco Emissor |
| Mastercard | 02 | Autenticada pelo Banco Emissor – risco de chargeback passa a ser do banco Emissor |
| Mastercard | 04 | Não autenticada, transação caracterizada como Data Only – risco de chargeback permanece com o estabelecimento |
| Mastercard | Diferente de 01, 02 e 04 | Não autenticada – risco de chargeback permanece com o estabelecimento |
| Elo | 05 | Autenticada pelo Banco Emissor – risco de chargeback passa a ser do banco Emissor |
| Elo | 06 | Autenticada pela Bandeira – risco de chargeback passa a ser do banco Emissor |
| Elo | 07 | Não autenticada – risco de chargeback permanece com o estabelecimento |
Cartões de Teste
Utilize os cartões de teste abaixo para simular diversos cenários no ambiente de SANDBOX
| Cartão | Resultado | Descrição |
| 4000000000001000 | SUCCESS | Autenticação Silenciosa e portador autenticou com sucesso |
| 4000000000001018 | FAILURE | Autenticação Silenciosa e portador finalizou com falha |
| 4000000000001034 | UNENROLLED | Cartão não elegível para autenticação |
| 4000000000001091 | SUCCESS | Autenticação com desafio e portador autenticou com sucesso |
| 4000000000001117 | UNENROLLED | Autenticação com desafio e Cartão não elegível |
| 4000000000001109 | FAILURE | Autenticação com desafio e portador falhou na autenticação |
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 ). Veja maiores detalhes em: https://developercielo.github.io/manual/autorizacao-com-autenticacao
Últimas atualizações
Para visualizar as últimas atualizações do manual, clique aqui
