Inserindo o Checkout

❗️

Você está na versão correta da documentação?

Verifique na sua Dashboard a versão da API que você está usando. Você deve usar a documentação correspondente. Para saber mais, veja: Versionamento.

Existem duas formas de utilizar o Checkout Pagar.me em seu site: por formulário HTML ou pela API.

A configuração base do checkout é baseada em dois parâmetros que são o createToken (data-create-token) e o customerData (data-customer-data).

O createToken (data-create-token) irá definir se o checkout deve criar uma transação ou apenas servir como formulário de dados. Quando o createToken é “true” o checkout irá autorizar uma transação lhe retornando um token de captura, status da transação e número de parcelas. Caso esse parâmetro esteja setado como “false”, o checkout servirá como um formulário apenas encriptando os dados do cartão do cliente na forma de um card_hash, retornando assim os dados preenchidos junto do card_hash.

A configuração “customerData” (data-customer-data) por sua vez define se o checkout deve pedir dados de endereço, email e nome do comprador. Caso essa configuração esteja desabilitada e deseje que o checkout crie uma transação é necessário enviar os dados do comprador no momento de abertura do checkout, utilizando os parâmetros de customer.

Inserindo a versão formulário

A versão de formulário do checkout mescla elementos de Javascript e HTML em sua composição. Para inserir o checkout na sua página é necessário importar o seus recursos da url "https://assets.pagar.me/checkout/checkout.js" e adicionar os mesmos através do parâmetro src em um botão.

O primeiro passo para configurar o checkout é definir seus parâmetros e regras. Na seção Configurações do checkout é possível verificar com mais detalhes cada campo que pode ser customizado, para esse exemplo foi utilizada a configuração mais simples possível, onde é informado apenas o valor da compra e o checkout é configurado para receber os dados do comprador (data-customer-data:true) e gerar o token de captura (data-create-token:true):

<form method="POST" action="/comprar">
    <script type="text/javascript"
        src="https://assets.pagar.me/checkout/checkout.js"
        data-encryption-key="SUA ENCRYPTION KEY"
        data-amount="1000"
        data-create-token="true"
        data-customer-data="true">
    </script>
</form>

Uma vez importado o script e configurados os campos desejados, será adicionado um botão responsável por abrir o checkout. Ao finalizar o processo de preenchimento e autorização, caso tudo tenha corrido bem, o checkout irá redirecionar o comprador para a página contida no parâmetro “action” do formulário.

A página HTML completa ficaria da seguinte maneira:

<html>
  <head>
      <meta charset="utf-8">
       <meta name="viewport" content="width=device-width, initial-scale=1.0">
  </head>
  <body>
    <center>
      <p>Checkout</p>
      <form method="POST" action="/comprar">
        <script type="text/javascript"
            src="https://assets.pagar.me/checkout/checkout.js"
            data-encryption-key="SUA ENCRYPTION KEY"
            data-amount="1000"
            data-create-token="true"
            data-customer-data="true">
        </script>
      </form>

    </center>
  </body>
</html>

Por conta do parâmetro "create-token:true" o checkout irá autorizar uma transação. Uma transação criada e autorizada pelo checkout Pagar.me permanece assim por até 5 horas, sendo necessário realizar a captura da mesma através do seu servidor. Caso a captura não seja realizada a transação será ESTORNADA.

Para realizar a captura de uma transação gerada pelo checkout será necessário que a página de redirecionamento seja capaz de tratar e enviar as informações da transação para o seu servidor, para que ele realize essa operação. No momento da captura é necessário o token retornado pelo checkout, o valor da transação e a chave de API. É extremamente importante que a captura seja realizada à partir do seu servidor (backend), isso porque essa operação é feita através da chave de API, dado sensível que permite a realização de TODAS as operações junto da API. NÃO faça a captura em ambientes do lado de seu cliente, como por exemplo, mas não limitado a: aplicativos mobile, páginas web via chamadas ajax e aplicativos desktop.

Inserindo a versão via API

Para inserir o checkout utilizando a versão API é necessário importar o seu script através da tag <script src="https://assets.pagar.me/checkout/checkout.js">.

O primeiro passo para configurar o checkout é definir seus parâmetros e regras. Na seção Configurações do checkout é possível verificar com mais detalhes cada campo que pode ser customizado, para esse exemplo utilizei a configuração mais simples possível, onde informo apenas o valor da compra e configuro as regras para o checkout receber os dados do comprador (customerData:true) e autorizar a transação (createToken:true):

<script>
checkout.open({
  amount: 1500,
  customerData: 'true',
  createToken: 'true'
})
</script>

Uma vez importado o script e configurados os campos desejados, é necessário que exista uma função para acessar os dados do checkout. O checkout possui 3 eventos distintos que podem ser tratados na sua aplicação: sucesso (sucess), erro (error) e fechamento (close).

<script>
  var button = document.querySelector('button');
 
  // Abrir o checkout ao clicar no botão
  button.addEventListener('click', function() {     

    // inicia a instância do checkout
    var checkout = new PagarMeCheckout.Checkout({
      encryption_key: 'SUA ENCRYPTION KEY',
      success: function(data) {
        console.log(data);
      },
      error: function(err) {
        console.log(err);
      },
      close: function() {
        console.log('The modal has been closed.');
      }
    });             
  });
</script>

A página HTML completa ficaria da seguinte maneira:

<html>
  <head>
    <!-- SCRIPT PAGAR.ME -->
    <script src="https://assets.pagar.me/checkout/checkout.js"></script>
  </head>
  <body>
    <button id="pay-button">Abrir modal de pagamento</button>

    <script>
      var button = document.querySelector('button');
      
      // Abrir o modal ao clicar no botão
      button.addEventListener('click', function() {     
            
        // inicia a instância do checkout
        var checkout = new PagarMeCheckout.Checkout({
          encryption_key: 'SUA ENCRYPTION KEY',
          success: function(data) {
            console.log(data);
          },
          error: function(err) {
            console.log(err);
          },
          close: function() {
            console.log('The modal has been closed.');
          }
        });             

        checkout.open({
          amount: 10000,
          customerData: 'true',
          createToken: 'true'
                })
      });
    </script>
  </body>
</html>

Assim como na versão de formulário, por conta do parâmetro "createToken:true" o checkout irá autorizar uma transação. Uma transação criada e autorizada pelo checkout Pagar.me permanece assim por até 5 horas, sendo necessário realizar a captura da mesma através do seu servidor. Caso a captura não seja realizada a transação será ESTORNADA.

Para realizar a captura de uma transação gerada pelo checkout será necessário enviar as informações da mesma para o seu servidor, para que ele realize essa operação. Para realização da captura, é necessário o token retornado pelo checkout, o valor da transação e a chave de API. É extremamente importante que a captura seja realizada à partir do seu servidor, isso porque essa operação é feita através da chave de API, dado sensível que permite a realização de TODAS as operações junto da API.

Capturando uma transação criada com Checkout

A rota utilizada para a operação de captura é a rota /transactions. É possível verificar os detalhes dessa rota através da referência da documentação: /capture. Lembrando que é através da mesma que serão enviados os dados de metadata e split_rules caso sejam necessários.

No nosso github é possível encontrar exemplos de aplicações que enviam os dados retornados pelo checkout para o backend e realizam a captura dos mesmos.

O checkout Pagar.me não cria recorrencias, porém o mesmo pode ser utilizado como formulário de dados e assim criar a recorrência à partir do endpoint /subscriptions. Para mais detalhes verifique a página de configurações do checkout.


Próximo