Integração para Cartão de Débito#

Sobre este guia#

Esta página explica como adicionar Cartões de débito, usando 3DS 2.0, à sua integração com EBANX Direct API. A integração é basicamente a mesma para todos os métodos de pagamento, apenas variando o payment_type_code e alguns campos adicionais obrigatórios.

Se você ainda não está integrado com EBANX Direct API, dê uma olhada neste guia básico. Não tem certeza se EBANX Direct API é a melhor opção para seu e-commerce? Por favor, fale com um de nossos especialistas.

Débito 3DS 2.0 com Autenticação EBANX#

No Brasil, o fluxo de autenticação 3DS é obrigatório nos pagamentos com cartão de débito realizados em ambiente e-commerce. A inclusão deste fluxo é feita através de nossa LIB JS, e os dados resultantes da autenticação devem ser adicionados a requisição da Direct API.

O que você vai precisar#

Antes de iniciar sua integração, certifique-se de ter:

Uma conta em nosso ambiente de testes. Ainda não possui sua conta? Fale com nossa equipe comercial;
debitcard habilitado em sua conta.

Como funciona#

Para completar uma integração com Cartão de débito por meio da Direct API, siga os seguintes passos:

Solicite cartões de débito em sua integração
Entre em contato com o EBANX através de seu representante comercial ou do faleconosco@ebanxpay.com e solicite cartões de débito em sua integração.
Prepare sua página de checkout para coletar os dados de 3DS
Antes de enviar uma requisição de pagamento com cartão débito para nossa Direct API, você precisará coletar os dados de autenticação 3DS deste pagamento. Para isso, nossa LIB JS adicionará este fluxo ao seu checkout de maneira simples.
Adicione os seguintes scripts à sua página de checkout:
<script type="text/javascript" src="https://js.ebanxpay.com/assets/songbird/songbird-dev.js"></script>
<script type="text/javascript" src="https://js.ebanxpay.com/ebanx-libjs-latest.min.js"></script>
E inicialize a LIB JS com a configuração de seu ambiente:
EBANX.config.setMode('test'); // Modo de execução: production ou test
EBANX.config.setPublishableKey('put your key here'); // Sua Chave Pública, de produção ou testes.
EBANX.config.setCountry('br'); // sempre br
Realize o fluxo 3DS
Após o cliente informar os dados de pagamento e antes de seu checkout enviar estes dados ao seu backend, você precisará incluir o fluxo 3DS no pagamento. Este fluxo é realizado através da LIB JS.
Passo 1: Crie um objeto com as informações do pedido:
const orderInformation = {
amountDetails: {
totalAmount: "10.04",
currency: "BRL",
},
billTo: {
address1: "Rua Estanislau Szarek",
administrativeArea: "PR",
country: "BR",
email: "1584023172@exemplo.com.br",
homePhone: "41999999999",
locality: "Curitiba",
postalCode: "81315380",
mobilePhone: "41999999999",
},
};
Passo 2: Crie um objeto com as informações do pagamento:
const paymentInformation = {
card: {
number: cardNumber,
expirationMonth: "12",
expirationYear: "34",
holderName: "JOAO DA SILVA",
},
};
Passo 3: Crie um objeto com as informações do seu cliente:
const personalIdentification = {
id: "97370192024",
type: "CPF",
};
Passo 4: Chame a função EBANX.threeDSecure.checkIfShouldAuthenticate usando os objetos criados nas etapas anteriores. Esta função retorna um Promise object, portanto, certifique-se de tratar a chamada assíncrona utilizando uma função de callback:
const options = {
orderInformation,
paymentInformation,
personalIdentification,
};

const shouldAuthenticatePromise = EBANX.threedsecure.checkIfShouldAuthenticate(options);
shouldAuthenticatePromise.then( response => {
if (response) {
threedsPromise = EBANX.threedsecure.run(options);
threedsPromise.then(successCallback, failureCallback);
}
});
Ainda neste passo, se solicitado pelo banco emissor, um desafio de autenticação será exibido ao cliente.
Se o seu pagamento exigiu autenticação e falhou, você pode enviar uma solicitação de autenticação novamente. Falhas podem acontecer por entrada inválida de clientes, indisponibilidade do emissor ou problemas de comunicação.
Uma resposta de autenticação bem sucedida conterá os seguintes campos. Os valores variam para cada autenticação:
{
threeds_eci: "05",
threeds_cryptogram: "AAIBAkl0NwmHglFBAXQ3AAAAAAA",
threeds_version: "2",
threeds_xid: "AAIBAkl0NwmHglFBAXQ3AAAAAAA",
threeds_trxid: "AAIBAkl0NwmHglFBAXQ3AAAAAAA"
}
Os campos threeds_xid, threeds_version e threeds_trxid são opcionais. Se eles não retornarem na resposta da chamada EBANX.threedsecure.run, não é necessário incluí-los nos passos subsequentes.
Envie os valores retornados pelo fluxo 3DS ao seu backend. Eles deverão ser enviados para o EBANX na requisição da Direct API.
Envie a requisição de pagamento para a Direct API com os parâmetros de 3DS
Se seu pagamento exigiu autenticação, inclua os valores recebidos na etapa anterior no objeto payment.card da requisição para a Direct API. Caso não tenha recebido valores, prossiga com os parâmetros regulares do objeto card.
- Card object com 3DS
- Card object sem 3DS
"card": {
"card_number": 4000000000001091,
"card_name": "JOAO DA SILVA",
"card_due_date": "01/2023",
"card_cvv": 123,
"threeds_eci": "05",
"threeds_cryptogram": "AAIBAkl0NwmHglFBAXQ3AAAAAAA=",
"threeds_xid": "AAIBAkl0NwmHglFBAXQ3AAAAAAA=",
"threeds_version": "2"
"threeds_trxid": "AAIBAkl0NwmHglFBAXQ3AAAAAAA"
}
Importante
O payment_type_code desta requisição deverá serdebitcard.

Testando sua integração#

Cenários de Testes#

Abaixo você pode encontrar uma lista de cartões de teste e outras informações para garantir que sua integração esteja funcionando conforme planejado. Você pode usar qualquer um dos seguintes cartões de teste, uma data de expiração válida no futuro e um número CVV para criar um pagamento.

CVV: Deverá ser 123 sempre;
Data de expiração (data de vencimento): Use 01/aaaa, onde aaaa = ano atual + 3.
- Por exemplo: se o ano atual é 2020, a data de vencimento deve ser 01/2023.

Cartões de Teste

Bandeira	Número do Cartão	Descrição do Cenário
visa	4000000000001000	Autenticação Aprovado (Sem desafio)
mastercard	5200000000001005	Autenticação Aprovado (Sem desafio)
elo	6505050000001000	Autenticação Aprovado (Sem desafio)
visa	4000000000001018	Falha na autenticação (sem desafio)
mastercard	5200000000001015	Falha na autenticação (sem desafio)
elo	6505050000001018	Falha na autenticação (sem desafio)
visa	4000000000001026	Falha na tentativa da Autenticação (sem desafio)
mastercard	5200000000001021	Falha na tentativa da Autenticação (sem desafio)
elo	6505050000001026	Falha na tentativa da Autenticação (sem desafio)
visa	4000000000001034	Autenticação indisponível no emissor
mastercard	5200000000003035	Autenticação indisponível no emissor
elo	6505050000001034	Autenticação indisponível no emissor
visa	4000000000001042	Autenticação indisponível no emissor (sem desafio)
mastercard	5200000000003043	Autenticação indisponível no emissor (sem desafio)
elo	3400000000001049	Autenticação indisponível no emissor (sem desafio)
visa	4000000000001059	Autenticação indisponível na pesquisa
mastercard	5200000000003054	Autenticação indisponível na pesquisa
elo	6505050000001059	Autenticação indisponível na pesquisa
visa	4000000000001067	Erro na tentativa de autenticação
mastercard	5200000000001062	Erro na tentativa de autenticação
elo	6505050000001067	Erro na tentativa de autenticação
visa	4000000000001075	Tempo limite exedido na tentativa de autenticação
mastercard	5200000000001070	Tempo limite exedido na tentativa de autenticação
elo	6505050000001075	Tempo limite exedido na tentativa de autenticação
visa	4000000000001083	Autenticação ignorada
mastercard	5200000000001088	Autenticação ignorada
elo	6505050000001083	Autenticação ignorada
visa	4000000000001091	Autenticação aprovada (com desafio)
mastercard	5200000000001096	Autenticação aprovada (com desafio)
elo	6505050000001091	Autenticação aprovada (com desafio)
visa	4000000000001109	Falha na autenticação (com desafio)
mastercard	5200000000001104	Falha na autenticação (com desafio)
elo	6505050000001109	Falha na autenticação (com desafio)
visa	4000000000001117	Desafio não disponível
mastercard	5200000000001112	Desafio não disponível
elo	6505050000001117	Desafio não disponível
visa	4000000000001125	Autenticação com erro
mastercard	5200000000001120	Autenticação com erro
mastercard	5200000000002011	Autenticação com erro
elo	6505050000001125	Autenticação com erro

Script de Testes#

Abaixo um script de teste HTML simples que você pode usar entender melhor os conceitos explorados neste guia:

<script type="text/javascript" src="https://js.ebanxpay.com/assets/songbird/songbird-dev.js"></script>
<script type="text/javascript" src="https://js.ebanxpay.com/ebanx-libjs-latest.min.js"></script>
<script type="text/javascript">
  window.onload = function() {
    const cardNumber = window.prompt("Test Card:");

    const orderInformation = {
      "amountDetails": {
          "totalAmount": "10.00",
          "currency": "BRL"
      },
      "billTo": {
          "address1": "Rua Teste",
          "administrativeArea": "PR",
          "country": "BR",
          "email": "test@test.com",
          "homePhone": "41999999999",
          "locality": "Curitiba",
          "postalCode": "81315380",
          "mobilePhone": "41999999999"
      }
    };
    EBANX.config.setMode('test');
    EBANX.config.setPublishableKey('your_test_public_integration_key');
    EBANX.config.setCountry('br');

    const paymentInformation = {
      "card": {
        "number": cardNumber,
        "expirationMonth": "12",
        "expirationYear": "34",
        "holderName": "JOAO DA SILVA"
      }
    };

    const personalIdentification = {
      "id": "85351346893",
      "type": "CPF"
    };

    function successCall(result, shouldAuthenticate) {
      console.log("Sucess: " + JSON.stringify(result));
      if(shouldAuthenticate){
        //If true, adds the 3DS objects to the request
        const request_draft = {
          "integration_key": "your_test_integration_key",
          "operation": "request",
          "mode": "full",
          "payment": {
            "merchant_payment_code": "0x0W05D2-T01",
            "amount_total": 10.00,
            "currency_code": "BRL",
            "name": "James Bond",
            "email": "test@test.com",
            "document": "85351346893",
            "address": "Rua Teste",
            "street_number": 123,
            "city": "Curitiba",
            "state": "PR",
            "zipcode": "81315380",
            "country": "BR",
            "phone_number": 41999999999,
            "payment_type_code": "debitcard",
            "card": {
              "card_number": cardNumber,
              "card_name": "JOAO DA SILVA",
              "card_due_date": "12/2034",
              "card_cvv": 123,
              "threeds_eci": result.threeds_eci,
              "threeds_cryptogram": result.threeds_cryptogram,
              "threeds_xid": result.threeds_xid,
              "threeds_version": result.threeds_version,
              "threeds_trxid": result.threeds_trxid
            }
          }
        };
      }
      else{
        //If false, runs the request without the 3DS objects
        const request_draft = {
          "integration_key": "your_test_integration_key",
          "operation": "request",
          "mode": "full",
          "payment": {
            "merchant_payment_code": "0x0W05D2-T01",
            "amount_total": 10.00,
            "currency_code": "BRL",
            "name": "James Bond",
            "email": "test@test.com",
            "document": "85351346893",
            "address": "Rua Teste",
            "street_number": 123,
            "city": "Curitiba",
            "state": "PR",
            "zipcode": "81315380",
            "country": "BR",
            "phone_number": 41999999999,
            "payment_type_code": "debitcard",
            "card": {
              "card_number": cardNumber,
              "card_name": "JOAO DA SILVA",
              "card_due_date": "12/2034",
              "card_cvv": 123,
            }
          }
        };
      }
      document.getElementById('request_output').innerHTML = JSON.stringify(request_draft, null, 2);
    }

    function failureCall(error) {
        console.error(error);
    }

    const options = {
      orderInformation,
      paymentInformation,
      personalIdentification,
    };

    function run3DS(shouldAuthenticate,options){
      const result = null;
      if(shouldAuthenticate){
        //If shouldAuthenticate is true, runs 3DS
        result = EBANX.threedsecure.run(options);
        result
          .then(successCall)
          .catch(failureCall);
      }
      else{
        //If false, go straight to successCall, where the contents of result won't be needed in this case
        successCall;
      }
    };

    //Determines if 3DS Authentication is needed.
    const shouldAuthenticate = EBANX.threedsecure.checkIfShouldAuthenticate(options);
    shouldAuthenticate
        .then(run3DS)
        .catch(failureCall);
  }
</script>
<body>
  <textarea type="text" id="request_output" rows="29" cols="50">
</body>

Obtendo Ajuda#

Nós esperamos que este artigo tenha sido esclarecedor, mas caso não tenhamos tirado suas dúvidas você tem as seguintes opções para continuar buscando respostas:

Se você ainda não é nosso parceiro e deseja saber mais sobre nossos preços e condições, entre em contato com nossa equipe comercial.
Caso você já seja nosso parceiro, entre em contato com nossa equipe de suporte em faleconosco@ebanxpay.com.

Integração para Cartão de Débito#

Sobre este guia#

Débito 3DS 2.0 com Autenticação EBANX#

O que você vai precisar#

Como funciona#

Solicite cartões de débito em sua integração

Prepare sua página de checkout para coletar os dados de 3DS

Realize o fluxo 3DS

Envie a requisição de pagamento para a Direct API com os parâmetros de 3DS

Importante

Testando sua integração#

Cenários de Testes#

Cartões de Teste

Script de Testes#

Obtendo Ajuda#