NAV
javascript

Introdução

Bem-vindo à biblioteca de Checkout de Pagamento Seguro da AixMobil!

Ela fornece uma camada extra de segurança para o portador do cartão, garantindo que os dados informados na hora do pagamento trafeguem de forma encriptada até chegarem aos nossos servidores para que a transação seja processada.

Encriptar os dados significa que os dados originais do cartão não ficam visíveis para que pessoas mal-intencionadas possam copiá-los e utilizá-los para realizar outras transações ou que tais dados não sejam expostos em caso de uma brecha de segurança durante o fluxo dos dados.

A biblioteca implementa a técnica Client-side encription (CSE) e é aderente às exigências definidas pelo PCI-DSS.

Os passos abaixo explicam como integrar client-side encription a sua página de pagamento utilizando Javascript.

Pré-requisitos

A técnica de CSE utiliza-se do sistema de criptografia RSA, baseado em um par de chaves para encriptar e decriptar os dados sensíveis do pagamento.

Para cada site de pagamento deve existir apenas um par de chaves.

A chave pública, representada por uma string, deve ser informada para a biblioteca durante a inicialização da página, por exemplo.

O hostname, representado por uma string, é o endereço do serviço que será chamado para a obtenção do token de criptografia.

A chave privada é armazenada dentro de um ambiente de seguro na infra-estrutura da AixMobil e nunca é transmitida ou acessível a qualquer pessoa. Ela é utilizada apenas pela plataforma para decriptar os dados recebidos.

Para solicitar um novo par de chaves para um determinado site, enviar um e-mail para suporte@aixmobil.com informando os seguintes dados:

Instalação

<body>
  ...
  <!-- Ambiente de testes e produção -->
  <script src="https://docs.aixmobil.com.br/libs/aixmobil-cse-1.1.0.min.js"></script>
</body>

Referenciar o script da biblioteca no HTML do site.

É importante referenciar o script externo ao invés de criar uma cópia do script para dentro do site, uma vez que a biblioteca poderá ser alterada a qualquer momento, podendo gerar problemas para aprovar a transação.

Configuração

O site pode ter sido desenvolvido para enviar os dados do formulário de duas formas diferentes: usando alguma biblioteca ou framework que intercepta o evento de submit do form e realiza uma chamada AJAX internamente ou utilizando o recurso nativo do elemento FORM, através dos atributos method e action.

Submit com requisição AJAX

<script>
  window.onload = function () {
      var publicKey = '[CHAVE_PUBLICA_AQUI]';
      var hostName = '[HOST_NAME_DO_SERVICO_AQUI]';

      aix.setPublicKey(publicKey);
      aix.setHostName(hostName);

      aix.getTransactionToken().then(function (token) {
          if (token) {
              // Neste modo, o token deve ser enviado 
              // junto com o POST do pagamento em um 
              // atributo chamado checkoutSessionToken
          }
      }, function (error) {
          console.log(error);
      });
  }
</script>

// exemplo de submit do submit do formulário, 
// utilizando requisição AJAX para envio dos dados.
function onSubmit() {
    var data = {
        dadosAdicionais: 'Descricao do pagamento',
        valor: 150.30,
        parcelas: 1,
        bandeira: 1,
        cartao: aix.encryptValue('1234567890123456'),
        validade: aix.encryptValue('10/2023'),
        cvv: aix.encryptValue('1234'),
        portador: 'Jorge da Silva',
        cpfCnpjPortador: '11111111111',
        checkoutSessionToken: token // token obtido da promise aix.createEncryptedForm()
    };

    var xhr = new XMLHttpRequest();
    xhr.open('POST', 'my-custom-endpoint-url', true);
    xhr.setRequestHeader('Content-type', 'application/json');
    xhr.send(JSON.stringify(data));
}

Este método é adequado para sites desenvolvidos utilizando bibliotecas ou frameworks que interceptam o evento de submit do formulário e realizam o submit de forma própria e também se utilizam de bindings ou funções para obter dados digitados no formulário.

Inicialização

A biblioteca deve ser inicializada no evento de load da página pois executa uma chamada assíncrona para os servidores da AixMobil a fim de validar a autenticidade do formulário de pagamento.

A chave pública e o hostname do backend devem ser informados antes da chamada para a validação do formulário.

Neste modo, é necessário chamar a função aix.getTransactionToken() para que um novo token seja gerado e enviado posteriormente junto com os dados do pagamento.

Envio dos dados

Antes de submeter os dados, deve-se utilizar a função aix.encryptValue() para encriptar cada um dos campos abaixo:

É neste momento que o token gerado no início da página é enviado junto com os dados da requisição utilizando a propridade checkoutSessionToken.

Submit com atributo action e method

<script>
  window.onload = function () {
      var publicKey = '[CHAVE_PUBLICA_AQUI]';
      var hostName = '[HOST_NAME_DO_SERVICO_AQUI]';

      aix.setPublicKey(publicKey);
      aix.setHostName(hostName);

      aix.createEncryptedForm().then(function (token) {
          if (token) {
              // um atributo contendo o valor do token deve ser enviado no body da requisição HTTP caso o submit esteja sendo feito de forma manual.
              // para submit feito utilizando o atributo action do form, esse valor é enviado automaticamente.

              // A partir deste ponto, o formulário pode ser submetido pois já possui o token necessário para validação da transação.
          }
      }, function (error) {
          console.log(error);
      });
  }
</script>

Este método é adequado para sites que fazem a submissão dos dados de um formulário utilizando o atributo action e method do elemento form.

Inicialização

A biblioteca deve ser inicializada no evento de load da página pois executa uma chamada assíncrona para os servidores da AixMobil a fim de validar o formulário de pagamento.

A chave pública e o hostname do backend devem ser informados antes da chamada para a validação do formulário.

Neste modo, é necessário chamar a função aix.createEncryptedForm() para preparar o formulário para encriptação. Essa função também se encarrega de gerar um novo token de transação, que será enviado automaticamente ao submeter os dados, sem necessidade de código adicional.

Envio dos dados

<!-- Form notation -->
<form method="POST" data-encrypted-form="payment-form">

<!-- Encrypted input notation -->
<input type="tel" data-encrypted-field="numero" />

<!-- Regular input notation -->
<input type="tel" name="valor" />



<!-- Form overview -->
<form method="POST" data-encrypted-form="payment-form">
  <div class="field">
      <label>Número do cartão</label>
      <input type="tel" data-encrypted-field="numero" />
  </div>
  <div class="field">
      <label>Data de validade do cartão</label>
      <input type="tel" data-encrypted-field="dataExpiracao" />
  </div>
  <div class="field">
      <label>CVV</label>
      <input type="tel" data-encrypted-field="codigoSeguranca" />
  </div>
  <div class="field">
      <label>Portador</label>
      <input type="text" name="portador" />
  </div>
  <div class="field">
      <label>Valor</label>
      <input type="tel" name="valor" />
  </div>
  <button>Encriptar e enviar</button>
</form>

O html do formulário e dos campos a serem encriptados devem seguir algumas regras. Dessa forma, não será necessário nenhum código para controlar a submissão dos dados.

Validação da transação

var xhr = new XMLHttpRequest();
    xhr.open('POST', 'my-custom-endpoint-url', true);
    xhr.setRequestHeader('Content-type', 'application/json');
    xhr.onreadystatechange = function () {
      if (xhr.readyState === XMLHttpRequest.DONE && xhr.status === 200) {
        var response = xhr.response;

        // chama manualmente a geração de novo token
        aix.getTransactionToken().then(function (token) {
          // armazena token para ser enviado no próximo submit
        });
      }
    };
    xhr.send(JSON.stringify(data));

A autenticação da transação se dá quando o backend confirma que o token recebido junto com os dados de pagamento equivale ao token gerado no carregamento da página.

A geração do token é feita de forma automática quando a função aix.createEncryptedForm() é chamada ou quando a função aix.getTransactionToken() é chamada explicitamente.

No entanto, dependendo da navegação do site, se o site foi desenhado para não redirecionar o usuário após um pagamento e ainda permitir que outra transação seja realizada sem que o usuário precise sair da tela e voltar ou realizar um refresh, é necessário chamar manualmente uma função para gerar um novo token, uma vez que o token anterior já foi consumido e não pode ser reutilizado.

Neste caso, pode-se executar a função aix.getTransactionToken() para gerar novo token logo após o submit do formulário ter sido realizado com sucesso.