Integrar pagamentos com cartão - Checkout API - Mercado Pago Developers
Developers
Referência API
Suporte
Entrar

    Inicio

    Começando

    Pagamentos online

    Checkout Pro

    Checkout API

    Link de pagamento

    Assinaturas

    Marketplace

    Mobile Checkout

    Web Tokenize Checkout

    Pagamentos presenciais

    Código QR

    Mercado Pago Point

    Plugins e plataformas

    WooCommerce

    Prestashop

    Magento 2

    Shopify

    Tiendanube

    VTEX

    SDKs

    Notificações

    Webhooks

    IPN

    Gerenciamento de conta

    Requisitos para ir à produção

    Obter pagamentos

    Relatórios

    Devoluções e cancelamentos

    Gestão de estornos

    Melhora a aprovação

    Recursos

    Localização

    Changelog

    Status

NESTA PÁGINA

Sugerir alterações
Ajude-nos a melhorar a documentação
Você viu informações equivocadas, gostaria que explicássemos algo a mais ou que melhorássemos nossos manuais? Deixe suas sugestões no GitHub.

Integre 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 totalmente no seu site. Toda a experiência acontece na sua loja para que os clientes não tenham que sair no momento de realizar a compra.

Use 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


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

  1. Primeiro, é 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. Segundo, um backend que tome o token gerado e os dados do pagamento, como por exemplo o valor e o ítem, e possa 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.

Obtenha mais informações nas Referências de API.

Capture os dados de 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.

      1. Inclua a biblioteca MercadoPago.js

Use nossa biblioteca oficial para acessar a API de Mercado Pago no seu frontend e coletar os dados de forma segura.

html

<script src="https://secure.mlstatic.com/sdk/javascript/v1/mercadopago.js"></script>

A informação do cartão será convertida em um token para que envie os dados aos seus servidores de modo seguro.

      2. Adicione o formulário de pagamento

Para realizar a captura dos dados sensíveis dos cartões dos seus clientes, é muito importante que utilize nosso formulário com os atributos correspondentes para garantir a segurança da informação e a geração correta do token. Por exemplo, é preciso respeitar os atributos data-checkout e não colocar o atributo name nos campos que tenham dados sensíveis, dessa forma nunca chegarão aos seus servidores.

Você pode adicionar tudo o que necessite, modificar o atributo label sugerido e adicionar o estilo que queira sem problemas.

No seguinte exemplo se assume que os dados transactionAmount e description formam obtidos em um passo anterior onde o cliente selecionou o produto ou serviço que deseja pagar.

html

<form action="/process_payment" method="post" id="paymentForm">
   <h3>Detalhe do comprador</h3>
     <div>
       <div>
         <label for="email">E-mail</label>
         <input id="email" name="email" type="text" value="test@test.com"/>
       </div>
       <div>
         <label for="docType">Tipo de documento</label>
         <select id="docType" name="docType" data-checkout="docType" type="text"></select>
       </div>
       <div>
         <label for="docNumber">Número do documento</label>
         <input id="docNumber" name="docNumber" data-checkout="docNumber" type="text"/>
       </div>
     </div>
   <h3>Detalhes do cartão</h3>
     <div>
       <div>
         <label for="cardholderName">Titular do cartão</label>
         <input id="cardholderName" data-checkout="cardholderName" type="text">
       </div>
       <div>
         <label for="">Data de vencimento</label>
         <div>
           <input type="text" placeholder="MM" id="cardExpirationMonth" data-checkout="cardExpirationMonth"
             onselectstart="return false" onpaste="return false"
             oncopy="return false" oncut="return false"
             ondrag="return false" ondrop="return false" autocomplete=off>
           <span class="date-separator">/</span>
           <input type="text" placeholder="YY" id="cardExpirationYear" data-checkout="cardExpirationYear"
             onselectstart="return false" onpaste="return false"
             oncopy="return false" oncut="return false"
             ondrag="return false" ondrop="return false" autocomplete=off>
         </div>
       </div>
       <div>
         <label for="cardNumber">Número do cartão</label>
         <input type="text" id="cardNumber" data-checkout="cardNumber"
           onselectstart="return false" onpaste="return false"
           oncopy="return false" oncut="return false"
           ondrag="return false" ondrop="return false" autocomplete=off>
       </div>
       <div>
         <label for="securityCode">Código de segurança</label>
         <input id="securityCode" data-checkout="securityCode" type="text"
           onselectstart="return false" onpaste="return false"
           oncopy="return false" oncut="return false"
           ondrag="return false" ondrop="return false" autocomplete=off>
       </div>
       <div id="issuerInput">
         <label for="issuer">Banco emissor</label>
         <select id="issuer" name="issuer" data-checkout="issuer"></select>
       </div>
       <div>
         <label for="installments">Parcelas</label>
         <select type="text" id="installments" name="installments"></select>
       </div>
       <div>
         <input type="hidden" name="transactionAmount" id="transactionAmount" value="100" />
         <input type="hidden" name="paymentMethodId" id="paymentMethodId" />
         <input type="hidden" name="description" id="description" />
         <br>
         <button type="submit">Pagar</button>
         <br>
       </div>
   </div>
 </form>
Nota
Lembre-se que é necessário que o formulário seja encontrado antes de todos os passos seguintes para seu correto funcionamento.

      3. Configure sua chave pública

Configure sua chave pública da seguinte forma:

javascript

window.Mercadopago.setPublishableKey("YOUR_PUBLIC_KEY");
Se ainda não possui conta para ver suas credenciais, regístre-se.

      4. Obtenha os dados para seu formulário

        Obtenha os tipos de documento

Um dos campos obrigatórios é o tipo de documento. Utilize a lista de documentos no momento de completar os dados.

Incluindo o elemento de tipo select com id = docType que se encontra no formulário, MercadoPago.js completará automaticamente as opções disponíveis quando a seguinte função for chamada:

javascript

window.Mercadopago.getIdentificationTypes();
Encontre mais detalhes na seção de Tipos de documentos.

        Obtenha o método de pagamento do cartão

Valide os dados dos seus clientes enquanto são preenchidos para evitar erros e oferecer corretamente as parcelas disponíveis. Use o seguinte código de exemplo para identificar o meio de pagamento com os primeiros 6 dígitos do cartão.

javascript

document.getElementById('cardNumber').addEventListener('change', guessPaymentMethod);

function guessPaymentMethod(event) {
   let cardnumber = document.getElementById("cardNumber").value;
   if (cardnumber.length >= 6) {
       let bin = cardnumber.substring(0,6);
       window.Mercadopago.getPaymentMethod({
           "bin": bin
       }, setPaymentMethod);
   }
};

function setPaymentMethod(status, response) {
   if (status == 200) {
       let paymentMethod = response[0];
       document.getElementById('paymentMethodId').value = paymentMethod.id;

       getIssuers(paymentMethod.id);
   } else {
       alert(`payment method info error: ${response}`);
   }
}

        Obtenha a banco emissor

No momento do preenchimento o formulário, é importante identificar o banco emissor do cartão para evitar conflitos entre os diferentes emissores e poder oferecer as opções corretas de parcelamento.

Adicione o seguinte código para obter o issuer_id:

javascript

function getIssuers(paymentMethodId) {
   window.Mercadopago.getIssuers(
       paymentMethodId,
       setIssuers
   );
}

function setIssuers(status, response) {
   if (status == 200) {
       let issuerSelect = document.getElementById('issuer');
       response.forEach( issuer => {
           let opt = document.createElement('option');
           opt.text = issuer.name;
           opt.value = issuer.id;
           issuerSelect.appendChild(opt);
       });

       getInstallments(
           document.getElementById('paymentMethodId').value,
           document.getElementById('transactionAmount').value,
           issuerSelect.value
       );
   } else {
       alert(`issuers method info error: ${response}`);
   }
}

        Obtenha a quantidade de parcelas

Outro campo obrigatório para pagamento com cartão é a quantidade de parcelas. Para obter as parcelas diponíveis, utilize a seguinte função de exemplo para completar o campo sugerido de tipo select denominado installments.

javascript

function getInstallments(paymentMethodId, transactionAmount, issuerId){
   window.Mercadopago.getInstallments({
       "payment_method_id": paymentMethodId,
       "amount": parseFloat(transactionAmount),
       "issuer_id": parseInt(issuerId)
   }, setInstallments);
}

function setInstallments(status, response){
   if (status == 200) {
       document.getElementById('installments').options.length = 0;
       response[0].payer_costs.forEach( payerCost => {
           let opt = document.createElement('option');
           opt.text = payerCost.recommended_message;
           opt.value = payerCost.installments;
           document.getElementById('installments').appendChild(opt);
       });
   } else {
       alert(`installments method info error: ${response}`);
   }
}

      5. Crie o token do cartão

Antes de enviar o pagamento, crie o token que conterá de maneira segura toda a informação do cartão. Você deve gerá-lo da seguinte forma:

javascript

doSubmit = false;
document.getElementById('paymentForm').addEventListener('submit', getCardToken);
function getCardToken(event){
   event.preventDefault();
   if(!doSubmit){
       let $form = document.getElementById('paymentForm');
       window.Mercadopago.createToken($form, setCardTokenAndPay);
       return false;
   }
};

function setCardTokenAndPay(status, response) {
   if (status == 200 || status == 201) {
       let form = document.getElementById('paymentForm');
       let card = document.createElement('input');
       card.setAttribute('name', 'token');
       card.setAttribute('type', 'hidden');
       card.setAttribute('value', response.id);
       form.appendChild(card);
       doSubmit=true;
       form.submit();
   } else {
       alert("Verify filled data!\n"+JSON.stringify(response, null, 4));
   }
};

O método createToken devolverá um card_token com a representação segura do cartão. O segundo campo do método createToken é a função de callback que processará a resposta (nesse caso usamos a função setCardTokenAndPay). Então tomaremos o ID da resposta e o guardaremos em um atributo oculto que chamaremos token, para em seguida enviar o formulário aos seus servidores.

Importante
Tenha em conta que o token tem uma validade de 7 dias e só pode ser usado 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 dado, seu backend devería diponibilizar um endpoint /process_payment, que foi definido no atributo action do formulário, para receber nele, todos os dados assim que realizar a ação submit.

Já 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.

  • php
  • node
  • java
  • ruby
  • csharp
  • curl

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(
        "type" => $_POST['docType'],
        "number" => $_POST['docNumber']
    );
    $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");

var payment_data = {
  transaction_amount: Number(req.body.transactionAmount),
  token: req.body.token,
  description: req.body.description,
  installments: Number(req.body.installments),
  payment_method_id: req.body.paymentMethodId,
  issuer_id: req.body.issuer,
  payer: {
    email: req.body.email,
    identification: {
      type: req.body.docType,
      number: req.body.docNumber
    }
  }
};

mercadopago.payment.save(payment_data)
  .then(function(response) {
    res.status(response.status).json({
      status: response.body.status,
      status_detail: response.body.status_detail,
      id: response.body.id
    });
  })
  .catch(function(error) {
    res.status(response.status).send(error);
  });

        

Encontre o estado do pagamento no campo status.

          

MercadoPago.SDK.setAccessToken("YOUR_ACCESS_TOKEN");

Payment payment = new Payment();
payment.setTransactionAmount(Float.valueOf(request.getParameter("transactionAmount")))
       .setToken(request.getParameter("token"))
       .setDescription(request.getParameter("description"))
       .setInstallments(Integer.valueOf(request.getParameter("installments")))
       .setPaymentMethodId(request.getParameter("paymentMethodId"));

Identification identification = new Identification();
identification.setType(request.getParameter("docType"))
              .setNumber(request.getParameter("docNumber")); 

Payer payer = new Payer();
payer.setEmail(request.getParameter("email"))
     .setIdentification(identification);
     
payment.setPayer(payer);

payment.save();

System.out.println(payment.getStatus());


        

Encontre o estado do pagamento no campo status.

          
require 'mercadopago'
$mp = MercadoPago.new('YOUR_ACCESS_TOKEN')

payment_data = {
  "transaction_amount": request.body.transactionAmount.to_f,
  "token": request.body.token,
  "description": request.body.description,
  "installments": request.body.installments.to_i,
  "payment_method_id": request.body.paymentMethodId,
  "payer": {
    "email": request.body.email,
    "identification": {
      "type": request.body.docType,
      "number": request.body.docNumber
    }
  }
}

payment = $mp.post('/v1/payments', payment_data)

puts payment


        

Encontre o estado do pagamento no campo status.

          

using MercadoPago;
using MercadoPago.DataStructures.Payment;
using MercadoPago.Resources;

MercadoPago.SDK.SetAccessToken("YOUR_ACCESS_TOKEN");

Payment payment = new Payment()
{
    TransactionAmount = float.Parse(Request["transactionAmount"]),
    Token = Request["token"],
    Description = Request["description"],
    Installments = int.Parse(Request["installments"]),
    PaymentMethodId = Request["paymentMethodId"],
    Payer = new Payer(){
        Email = Request["email"],
        Identification = new Identification(){
          Type = Request["docType"],
          Number = Request["docNumber"]
        }
    }
};

payment.Save();

console.log(payment.Status);


        

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 Referências de API.

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 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.

Te recomendamos usar as mensagens de respostas e utilizar a comunicação sugerida em cada um dos casos.

Nota
Evite pagamentos rejeitados com nossas recomendações para melhorar a aprovação dos seus pagamentos.

Receba notificações de pagamento

Por último, é importante que esteja sempre informado sobre a criação nos novos pagamentos e as atualizações dos seus estados. Por exemplo se foram aprovados, rejeitados ou caso encontram-se pendentes.

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

Exemplos para download

Checkout API
Disponibilizamos exemplos completos de integração no GitHub para PHP ou NodeJS para que você possa fazer o download imediatamente.

Formulário de pagamento
Se você deseja implementar seu servidor com alguma outra tecnologia, te deixamos um exemplo completo do formulário de pagamento no GitHub para que possa baixar.

Próximos passos

OBRIGATÓRIO

Teste sua integração

Revise que esteja tudo bem com sua integração com os usuários de teste.

RECOMENDADO

Integrar outros meios de pagamento

Conheça todas as opções de pagamentos disponíveis e como oferê-las.

Essas informações foram úteis?

Mercado Pago ofrece servicios de pago y no está autorizado por el Banco Central a operar como entidad financiera. Los fondos acreditados en cuentas de pago no constituyen depósitos en una entidad financiera ni están garantizados conforme legislación aplicable a depósitos en entidades financieras. Copyright © 2021 MercadoLibre S.R.L.

Termos e condiçõesComo cuidamos da sua privacidade
Partners Mercado Pago

Al navegar en este sitio aceptás las cookies que utilizamos para mejorar tu experiencia. Más información.