Cartão - Integrar meios de pagamento - Mercado Pago Developers

Integre o Checkout API para pagamentos com cartão

A integração por Checkout API do Mercado Pago para pagamentos com cartões permite que você possa oferecer uma opção de pagamento diretamente no seu site. Toda a experiência acontece na sua loja, assim os clientes não precisam sair dela no momento de realizar a compra.

Importante
Sua integração com a API transparente do Mercado Pago pode ser elegível ao . Essa categoria de PCI exige menos requisitos do vendedor, o que acelera o processo de certificação. Para ser elegível a essa categoria é necessário que sua integração seja feita utilizando campos de cartão em formato Iframe.

Fields utiliza HTML iframe e permite que os dados PCI (cardNumber, securityCode, e expirationDate) sejam inacessíveis para terceiros e processados pelos servidores do Mercado Pago, aumentando a segurança do comprador, do vendedor e da adquirente.

Fields

Atualmente existem duas formas de implementar essa solução. A primeira é através da utilização dos métodos core, onde o integrador é responsável por todo o fluxo do pagamento, permitindo maior flexibilidade para experiências totalmente customizadas. A segunda utiliza o cardForm, um componente criado por nós que facilita a integração realizando algumas etapas do processo automaticamente.

Utilize os exemplos para download para conhecer a integração completa ou para adaptá-los de acordo com o que precisa.

Como funciona?

API-integration-flowchart

Caso deseje realizar um fluxo de pagamento personalizado, compartilhamos todos os .

Ao utilizar o Checkout API do Mercado Pago, é importante ter em conta duas instâncias: a de captura de dados e a de envio de confirmação de pagamento.

  1. É preciso um frontend para coletar os dados do cartão e gerar um token de segurança com a informação para poder criar o pagamento.
  2. Tenha um backend que tome o token gerado e os dados do pagamento, como, por exemplo, o valor e o item, além de poder confirmar e efetuar o pagamento.

Tanto para o frontend como para o backend, recomendamos utilizar nossos SDKs para poder coletar os dados sensíveis dos seus usuários de maneira segura.

Nota
Obtenha mais informações nas .

Capture os dados do cartão

Client-Side

Para criar um pagamento é necessário fazer a captura dos dados do cartão através do navegador do comprador. Por questões de segurança, é muito importante que os dados nunca cheguem aos seus servidores.

Para capturar os dados do cartão, siga estas etapas:

  1. Inclua e configure a biblioteca MercadoPago.js
  2. Adicione o formulário de pagamento
  3. Integre o formulário com a biblioteca MercadoPago.js

1. Inclua e configure a biblioteca MercadoPago.js

Utilize a nossa biblioteca oficial para acessar a API de Mercado Pago desde seu frontend para coletar os dados de forma segura e configure sua chave pública da seguinte forma:

html

<body>
  <!-- Add step #2 -->
  <script src="https://sdk.mercadopago.com/js/v2"></script>
  <script>
      const mp = new MercadoPago('YOUR_PUBLIC_KEY');
      // Add step #3
  </script>
</body>

Se ainda não possui conta para ver suas credenciais, registre-se.

A informação do cartão será convertida em um token para que os dados sejam enviados aos seus servidores de forma segura.

2. Adicione o formulário de pagamento

Para capturar os dados do cartão, primeiro você deve oferecer um formulário para carregar toda a informação.

Com a funcionalidade CardForm da biblioteca MercadoPago.js, você pode obter e validar todos os dados necessários, como identificar o tipo e o nome do meio de pagamento, o banco emissor, o número de prestações e mais.

CardForm permite que você tenha uma implementação segura e uma correta tokenização da informação do cartão.

Para os campos PCI (Card Number, Expiration Date e Security Code) deve-se criar divs que servirão de containers para os iFrames.

Utilize o formulário abaixo e adicione os estilos que desejar.

html

<!-- Step #2 -->
<style>
  #form-checkout {
    display: flex;
    flex-direction: column;
    max-width: 600px;
  }

  .container {
    height: 18px;
    display: inline-block;
    border: 1px solid rgb(118, 118, 118);
    border-radius: 2px;
    padding: 1px 2px;
  }
</style>
<form id="form-checkout">
   <div id="form-checkout__cardNumber-container" class="container"></div>
   <div id="form-checkout__expirationDate-container" class="container"></div>
   <input type="text" name="cardholderName" id="form-checkout__cardholderName"/>
   <input type="email" name="cardholderEmail" id="form-checkout__cardholderEmail"/>
   <div id="form-checkout__securityCode-container" class="container"></div>
   <select name="issuer" id="form-checkout__issuer"></select>
   <input type="text" name="identificationNumber" id="form-checkout__identificationNumber"/>
   <select name="installments" id="form-checkout__installments"></select>
   <button type="submit" id="form-checkout__submit">Pagar</button>
   <progress value="0" class="progress-bar">Carregando...</progress>
 </form>
Referência técnica
Veja mais informações sobre os diferentes atributos nas .

3. Integre o formulário com a biblioteca MercadoPago.js

Para inicializar o CardForm, deve-se relacionar o ID de cada campo do formulário com os atributos correspondentes. A biblioteca será responsável pelo preenchimento, obtenção e validação de todos os dados necessários na hora de confirmar o pagamento.

Para que o IFrame seja renderizado, é necessário passar a opção iframe com valor true no objeto de parâmetro recebido pelo cardForm. Além disso, também é possível passar o style para os elementos.

javascript

// Step #3
const cardForm = mp.cardForm({
   amount: '100.5',
   iframe: true,
   form: {
     id: 'form-checkout',
     cardholderName: {
       id: 'form-checkout__cardholderName',
       placeholder: "Titular do cartão",
     },
     cardholderEmail: {
       id: 'form-checkout__cardholderEmail',
       placeholder: 'E-mail'
     },
     cardNumber: {
       id: 'form-checkout__cardNumber-container',
       placeholder: 'Número do cartão',
     },
     securityCode: {
       id: 'form-checkout__securityCode-container',
       placeholder: 'Código de segurança'
     },
     installments: {
       id: 'form-checkout__installments',
       placeholder: 'Parcelas'
     },
     expirationDate: {
       id: 'form-checkout__expirationDate-container',
       placeholder: 'Data de vencimento (MM/YYYY)',
     },
     identificationNumber: {
       id: 'form-checkout__identificationNumber',
       placeholder: 'Número do documento'
     },
     issuer: {
       id: 'form-checkout__issuer',
       placeholder: 'Banco emissor'
     }
   },
   callbacks: {
     onFormMounted: function (error) {
       if (error) return console.log('Callback para tratar o erro: montando o cardForm ', error)
     },
     onSubmit: function (event) {
       event.preventDefault();
 
       const {
         paymentMethodId: payment_method_id,
         issuerId: issuer_id,
         cardholderEmail: email,
         amount,
         token,
         installments,
         identificationNumber
       } = cardForm.getCardFormData();
 
        fetch('/process_payment', {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({
            token,
            issuer_id,
            payment_method_id,
            transaction_amount: Number(amount),
            installments: Number(installments),
            description: 'product description',
            payer: {
              email,
              identification: {
                number: identificationNumber
             }
           }
         })
       })
     },
     onFetching: function (resource) {
       console.log('fetching... ', resource)
       const progressBar = document.querySelector('.progress-bar')
       progressBar.removeAttribute('value')
 
       return () => {
         progressBar.setAttribute('value', '0')
       }
     }
   }
 });

A opção de callbacks aceita diferentes funções que são ativadas em diversos momentos do fluxo.

Referência técnica
Obtenha mais informações sobre os callbacks nas .

Ao enviar o formulário, geramos um token como uma representação segura dos dados do cartão. Você pode acessar este token usando a função getCardFormData, como mostramos anteriormente no callback onSubmit. Também armazenaremos o token em um input oculto dentro do seu formulário e o chamaremos de MPHiddenInputToken.

Importante
Tenha em conta que o token tem validade de 7 dias e só pode ser utilizado uma única vez.

Envie o pagamento ao Mercado Pago

Server-Side

Para continuar o processo de pagamento ao Mercado Pago, é necessário que seu backend possa receber a informação do formulário com o token gerado e os dados completos.

Segundo o exemplo, seu backend deveria disponibilizar um endpoint /process_payment para receber todos os dados depois de realizar a ação submit.

Estando no seu backend com toda a informação coletada, é o momento de enviar a solicitação ao Mercado Pago através das nossas APIs. Os campos mínimos requeridos para enviar são: token, transaction_amount, installments, payment_method_id e o payer.email.

Tenha em conta que para que esse passo funcione é necessário que configure sua chave privada e que, para interagir com nossas APIs, recomendamos utilizar o SDK oficial do Mercado Pago.

Encontre o estado do pagamento no campo status.

          
<?php
   require_once 'vendor/autoload.php';
 
   MercadoPago\SDK::setAccessToken("YOUR_ACCESS_TOKEN");
 
   $payment = new MercadoPago\Payment();
   $payment->transaction_amount = (float)$_POST['transactionAmount'];
   $payment->token = $_POST['token'];
   $payment->description = $_POST['description'];
   $payment->installments = (int)$_POST['installments'];
   $payment->payment_method_id = $_POST['paymentMethodId'];
   $payment->issuer_id = (int)$_POST['issuer'];
 
   $payer = new MercadoPago\Payer();
   $payer->email = $_POST['email'];
   $payer->identification = array(
       "number" => $_POST['identificationNumber']
   );
   $payment->payer = $payer;
 
   $payment->save();
 
   $response = array(
       'status' => $payment->status,
       'status_detail' => $payment->status_detail,
       'id' => $payment->id
   );
   echo json_encode($response);
 
?>

        

Encontre o estado do pagamento no campo status.

          
 
var mercadopago = require('mercadopago');
mercadopago.configurations.setAccessToken("YOUR_ACCESS_TOKEN");
 
mercadopago.payment.save(req.body)
  .then(function(response) {
    const { status, status_detail, id } = response.body;
    res.status(response.status).json({ status, status_detail, id });
  })
  .catch(function(error) {
    console.error(error);
  });

        

Encontre o estado do pagamento no campo status.

          

PaymentClient client = new PaymentClient();

PaymentCreateRequest paymentCreateRequest =
   PaymentCreateRequest.builder()
       .transactionAmount(request.getTransactionAmount())
       .token(request.getToken())
       .description(request.getDescription())
       .installments(request.getInstallments())
       .paymentMethodId(request.getPaymentMethodId())
       .payer(
           PaymentPayerRequest.builder()
               .email(request.getPayer().getEmail())
               .firstName(request.getPayer().getFirstName())
               .identification(
                   IdentificationRequest.builder()
                       .type(request.getPayer().getIdentification().getType())
                       .number(request.getPayer().getIdentification().getNumber())
                       .build())
               .build())
       .build();

client.create(paymentCreateRequest);


        

Encontre o estado do pagamento no campo status.

          
require 'mercadopago'
sdk = Mercadopago::SDK.new('YOUR_ACCESS_TOKEN')
 
payment_data = {
 transaction_amount: params[:transactionAmount].to_f,
 token: params[:token],
 description: params[:description],
 installments: params[:installments].to_i,
 payment_method_id: params[:paymentMethodId],
 payer: {
   email: params[:email],
   identification: {
     number: params[:identificationNumber]
   }
 }
}
 
payment_response = sdk.payment.create(payment_data)
payment = payment_response[:response]
 
puts payment
 

        

Encontre o estado do pagamento no campo status.

          
using System;
using MercadoPago.Client.Common;
using MercadoPago.Client.Payment;
using MercadoPago.Config;
using MercadoPago.Resource.Payment;
 
MercadoPagoConfig.AccessToken = "YOUR_ACCESS_TOKEN";
 
var paymentRequest = new PaymentCreateRequest
{
   TransactionAmount = decimal.Parse(Request["transactionAmount"]),
   Token = Request["token"],
   Description = Request["description"],
   Installments = int.Parse(Request["installments"]),
   PaymentMethodId = Request["paymentMethodId"],
   Payer = new PaymentPayerRequest
   {
       Email = Request["email"],
       Identification = new IdentificationRequest
       {
           Number = Request["identificationNumber"],
       },
   },
};
 
var client = new PaymentClient();
Payment payment = await client.CreateAsync(paymentRequest);
 
Console.WriteLine(payment.Status);
 

        

Encontre o estado do pagamento no campo status.

          
import mercadopago
sdk = mercadopago.SDK("ACCESS_TOKEN")
 
payment_data = {
   "transaction_amount": float(request.POST.get("transaction_amount")),
   "token": request.POST.get("token"),
   "description": request.POST.get("description"),
   "installments": int(request.POST.get("installments")),
   "payment_method_id": request.POST.get("payment_method_id"),
   "payer": {
       "email": request.POST.get("email"),
       "identification": {
           "number": request.POST.get("number")
       }
   }
}
 
payment_response = sdk.payment().create(payment_data)
payment = payment_response["response"]
 
print(payment)

        

Encontre o estado do pagamento no campo status.

          
 
curl -X POST \
   -H 'accept: application/json' \
   -H 'content-type: application/json' \
   -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
   'https://api.mercadopago.com/v1/payments' \
   -d '{
         "transaction_amount": 100,
         "token": "ff8080814c11e237014c1ff593b57b4d",
         "description": "Blue shirt",
         "installments": 1,
         "payment_method_id": "visa",
         "issuer_id": 310,
         "payer": {
           "email": "test@test.com"
         }
   }'
 

        

Resposta

json

{
   "status": "approved",
   "status_detail": "accredited",
   "id": 3055677,
   "date_approved": "2019-02-23T00:01:10.000-04:00",
   "payer": {
       ...
   },
   "payment_method_id": "visa",
   "payment_type_id": "credit_card",
   "refunds": [],
   ...
}
Conheça todos os campos disponíveis para realizar um pagamento completo nas .

Mensagens de respostas

Os possíveis estados de um pagamento são:

payment-status

Para ajudar a melhorar a aprovação dos seus pagamentos, é fundamental que você possa comunicar corretamente aos seus clientes os dados resultantes da criação de um pagamento.

Isso ajudará a evitar casos de rejeição e estornos nos casos de transações inicialmente aprovadas. Por exemplo, permite que se possa corrigir os erros de carga de dados ou ajudar a alterar o meio de pagamento.

Recomendamos que você use as mensagens de respostas e utilize a comunicação sugerida em cada um dos casos.

Nota
Evite pagamentos rejeitados com nossas .

Receba notificações de pagamento

Por último, é importante que você esteja sempre informado sobre a criação de novos pagamentos e as atualizações dos seus estados. Por exemplo, se foram aprovados, rejeitados ou se ainda estão pendentes.

Configure notificações webhooks ou notificações IPN.

Exemplos para download

Checkout API
Disponibilizamos para que você possa fazer o download.