Tokenizar meio de pagamento

Na integração via Card Payment Brick para websites, a biblioteca MercadoPago.js, incluída no seu projeto durante a configuração do ambiente de desenvolvimento, é responsável por obter as informações necessárias para a geração de um pagamento. Ou seja, ela realiza uma busca pelos tipos de documentos disponíveis para o país correspondente e, conforme os dados do cartão são inseridos, também busca as informações relativas ao emissor e às parcelas disponíveis.

Toda a informação envolvida no processamento da transação é armazenada no backend, em conformidade com os padrões de segurança PCI.

Além disso, o componente oferece a possibilidade de orientar o usuário com alertas sobre campos incompletos ou possíveis erros ao preencher os dados, otimizando o processo de compra.

Com isso, a implementação do fluxo é transparente para quem realiza a integração, conforme mostra o diagrama abaixo.

  sequenceDiagram
    participant Navegador as Navegador do comprador
    participant Frontend as Front-end do integrador
    participant MPjs as MercadoPago.js
    participant Backend as Back-end do integrador
    participant API as API Mercado Pago

    Navegador->>Frontend: 1. O comprador acessa a tela de pagamento.
    Frontend->>MPjs: 2. O front-end do integrador baixa e inicializa o SDK JS do Mercado Pago.
    Frontend->>Navegador: 3. O front-end do integrador exibe o formulário de pagamento.
    Navegador->>Frontend: 4. O comprador preenche o formulário e finaliza o pagamento.
    Frontend->>MPjs: 5. O front-end do integrador usa o SDK JS para criar o _token_ que conterá os dados do cartão de forma segura.
    Frontend->>Backend: 6.O front-end do integrador envia o _token_ do cartão e os dados de pagamento para seu back-end.
    Backend->>API: 7. Do back-end, são chamados os serviços do Mercado Pago para criar o pagamento.
    API->>Navegador: 8. O front-end do integrador exibe ao comprador o resultado da operação.
    API->>Backend: 9. O Mercado Pago pode enviar notificações via Webhook com atualizações do status do pagamento.
    Backend->>Navegador: 10. Se aplicável, o comprador é notificado sobre a atualização do pagamento.

Para avançar com a configuração, siga os passos abaixo.

Adicionar formulário de pagamento

Para receber pagamentos, adicione no frontend um formulário que permita capturar os dados do pagador de maneira segura e possibilite a criptografia do cartão. Essa inclusão deve ser feita por meio do Card Payment Brick, que oferece um formulário otimizado com temas variados e inclui os campos necessários para pagamentos com cartões.

Para adicionar o Card Payment Brick, primeiro realize sua configuração e inicialização a partir do frontend, como mostram os exemplos a seguir.

const renderCardPaymentBrick = async (bricksBuilder) => {
  const settings = {
    initialization: {
      amount: 100.99, // valor total a ser pago
    },
    callbacks: {
      onReady: () => {
        /*
         Callback chamado quando o Brick estiver pronto.
         Aqui podem ser ocultos loadings do site, por exemplo.
       */
      },
      onSubmit: (formData, additionalData) => {
        // callback chamado ao clicar no botão de envio de dados
        return new Promise((resolve, reject) => {
          const submitData = {
            type: "online",
            total_amount: String(formData.transaction_amount), // deve ser uma string com formato 00.00
            external_reference: "ext_ref_1234", // identificador da origem da transação.
            processing_mode: "automatic",
            transactions: {
              payments: [
                {
                  amount: String(formData.transaction_amount), // deve ser uma string com formato 00.00 
                  payment_method: {
                    id: formData.payment_method_id,
                    type: additionalData.paymentTypeId,
                    token: formData.token,
                    installments: formData.installments,
                  },
                },
              ],
            },
            payer: {
              email: formData.payer.email,
              identification: formData.payer.identification,
            },
          };

          fetch("/process_order", {
            method: "POST",
            headers: {
              "Content-Type": "application/json",
            },
            body: JSON.stringify(submitData),
          })
            .then((response) => response.json())
            .then((response) => {
              // receber o resultado do pagamento
              resolve();
            })
            .catch((error) => {
              // lidar com a resposta de erro ao tentar criar o pagamento 
              reject();
            });
        });
      },
      onError: (error) => {
        // callback chamado para todos os casos de erro do Brick 
        console.error(error);
      },
    },
  };
  window.cardPaymentBrickController = await bricksBuilder.create(
    "cardPayment",
    "cardPaymentBrick_container",
    settings
  );
};
renderCardPaymentBrick(bricksBuilder);

O callback onSubmit do Brick obterá os dados mínimos necessários para a criação de um pagamento. Uma das informações retornadas é o CardToken, que representa de forma segura os dados do cartão. Esse token pode ser usado somente uma vez e expira dentro de 7 dias.

Além das informações mínimas, recomendamos incluir detalhes adicionais ou que possam facilitar o reconhecimento da compra por parte do comprador, aumentando assim a taxa de aprovação dos pagamentos. Consulte nossa Referência de API para conhecer em detalhe todos os parâmetros a serem enviados ao criar um pagamento, incluindo aqueles que podem melhorar sua taxa de aprovação, e verifique quais você deseja incluir nesta etapa.

Em seguida, adicione os campos relevantes ao objeto enviado, que são retornados na resposta do callback.

Por fim, realize a renderização do Brick utilizando um dos exemplos abaixo.

<div id="cardPaymentBrick_container"></div> // O id deve corresponder ao valor enviado no método create() na etapa anterior

Como resultado, a renderização do Brick ficará semelhante à imagem abaixo.

Por último, será necessário que seu backend possa receber as informações do formulário criado, junto com o token resultante da criptografia do cartão. Para isso, recomendamos disponibilizar um endpoint /Process_order que receba os dados coletados pelo Brick após a ação de submit.