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.

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"></select>
       </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>

      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

Caso seu país possua mais de um tipo de documento, este campo será obrigatório. 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 e verifique se é necessário identificar também o banco emissor.

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;

       if(paymentMethod.additional_info_needed.includes("issuer_id")){
           getIssuers(paymentMethod.id);
       } else {
           getInstallments(
               paymentMethod.id,
               document.getElementById('transactionAmount').value
           );
       }
   } else {
       alert(`payment method info error: ${response}`);
   }
}

        Obtenha a banco emissor

É importante identificar o banco emissor do cartão no momento do preenchimento o formulário para evitar conflitos entre os diferentes emissores e poder disponibilizar a informação para os meios de pagamento que o solicitem.

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

Se não deseja oferecer parcelamento, ignore esse passo.

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": issuerId ? parseInt(issuerId) : undefined
   }, 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.

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' \
    'https://api.mercadopago.com/v1/payments?access_token=YOUR_ACCESS_TOKEN' \
    -d '{
          "transaction_amount": 115,
          "token": "ff8080814c11e237014c1ff593b57b4d",
          "description": "Ergonomic Linen Gloves",
          "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.

Manipulação de respostas de erro

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 a manipulação de respostas de erro 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

Sua pesquisa não retorna resultados.

Check the spelling of search terms or test with other keywords.