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 a API para pagamentos com cartão

A integração por 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 nossa API de pagamentos 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 transaction_amount e description formam obtidos em um passo anterior onde o cliente selecionou o produto ou serviço que deseja pagar.

Html

<form action="/processar_pagamento" method="post" id="pay" name="pay" >
    <fieldset>
        <p>
            <label for="description">Descrição</label>                        
            <input type="text" name="description" id="description" value="Ítem selecionado"/>
        </p>                    
        <p>
            <label for="transaction_amount">Valor a pagar</label>                        
            <input name="transaction_amount" id="transaction_amount" value="100"/>
        </p>        
        <p>
            <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 />
        </p>
        <p>
            <label for="cardholderName">Nome e sobrenome</label>
            <input type="text" id="cardholderName" data-checkout="cardholderName" />
        </p>
        <p>
            <label for="cardExpirationMonth">Mês de vencimento</label>
            <input type="text" 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 />
        </p>
        <p>
            <label for="cardExpirationYear">Ano de vencimento</label>
            <input type="text" 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 />
        </p>
        <p>
            <label for="securityCode">Código de segurança</label>
            <input type="text" id="securityCode" data-checkout="securityCode" onselectstart="return false" onpaste="return false" onCopy="return false" onCut="return false" onDrag="return false" onDrop="return false" autocomplete=off />
        </p>
        <p>
            <label for="installments">Parcelas</label>
            <select id="installments" class="form-control" name="installments"></select>
        </p>
        <p>
            <label for="docType">Tipo de documento</label>
            <select id="docType" data-checkout="docType"></select>
        </p>
        <p>
            <label for="docNumber">Número do documento</label>
            <input type="text" id="docNumber" data-checkout="docNumber"/>
        </p>
        <p>
            <label for="email">E-mail</label>
            <input type="email" id="email" name="email" value="test@test.com"/>
        </p>
        <input type="hidden" name="payment_method_id" id="payment_method_id"/>
        <input type="submit" value="Pagar"/>
    </fieldset>
</form>

      3. Configure sua chave pública

Configure sua chave pública da seguinte forma:

Javascript

window.Mercadopago.setPublishableKey("ENV_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('keyup', guessPaymentMethod);
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 paymentMethodId = response[0].id;
        let element = document.getElementById('payment_method_id');
        element.value = paymentMethodId;
        getInstallments();
    } else {
        alert(`payment 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(){
    window.Mercadopago.getInstallments({
        "payment_method_id": document.getElementById('payment_method_id').value,
        "amount": parseFloat(document.getElementById('transaction_amount').value)

    }, function (status, response) {
        if (status == 200) {
            document.getElementById('installments').options.length = 0;
            response[0].payer_costs.forEach( installment => {
                let opt = document.createElement('option');
                opt.text = installment.recommended_message;
                opt.value = installment.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.querySelector('#pay').addEventListener('submit', doPay);

function doPay(event){
    event.preventDefault();
    if(!doSubmit){
        var $form = document.querySelector('#pay');

        window.Mercadopago.createToken($form, sdkResponseHandler);

        return false;
    }
};

function sdkResponseHandler(status, response) {
    if (status != 200 && status != 201) {
        alert("verify filled data");
    }else{
        var form = document.querySelector('#pay');
        var card = document.createElement('input');
        card.setAttribute('name', 'token');
        card.setAttribute('type', 'hidden');
        card.setAttribute('value', response.id);
        form.appendChild(card);
        doSubmit=true;
        form.submit();
    }
};

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 sdkResponseHandler). Então tomaremos o ID da resposta e 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.


Baixe um exemplo do formulário

Se nunca desenvolveu um formulário e têm dúvidas, te deixamos um exemplo completo do formulário de pagamento no GitHub para que possa baixar.


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 /processar_pagamento, que foi definido no atributo action do formulário, para receber aí 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 a 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("ENV_ACCESS_TOKEN");

    $payment = new MercadoPago\Payment();
    $payment->transaction_amount = 177;
    $payment->token = "ff8080814c11e237014c1ff593b57b4d";
    $payment->description = "Aerodynamic Paper Keyboard";
    $payment->installments = 1;
    $payment->payment_method_id = "visa";
    $payment->payer = array(
    "email" => "valentina_connelly@hotmail.com"
    );

$payment->save();


echo $payment->status;

?>

Encontre o estado do pagamento no campo status.

var mercadopago = require('mercadopago');
mercadopago.configurations.setAccessToken("ENV_ACCESS_TOKEN");

var payment_data = {
  transaction_amount: 177,
  token: 'ff8080814c11e237014c1ff593b57b4d'
  description: 'Aerodynamic Paper Keyboard',
  installments: 1,
  payment_method_id: 'visa',
  payer: {
    email: 'test@test.com'
  }
};

mercadopago.payment.save(payment_data).then(function (data) {
      console.log(data);
      res.send(data);
    }).catch(function (error) {
      console.log(error);
    });

Encontre o estado do pagamento no campo status.

MercadoPago.SDK.setAccessToken("ENV_ACCESS_TOKEN");

Payment payment = new Payment();
payment.setTransactionAmount(177f)
       .setToken("ff8080814c11e237014c1ff593b57b4d")
       .setDescription("Aerodynamic Paper Keyboard")
       .setInstallments(1)
       .setPaymentMethodId("visa")
       .setPayer(new Payer()
         .setEmail("test@test.com"));

payment.save();


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

Encontre o estado do pagamento no campo status.

require 'mercadopago'
MercadoPago::SDK.access_token = "ENV_ACCESS_TOKEN";

payment = MercadoPago::Payment.new()
payment.transaction_amount = 177
payment.token = 'ff8080814c11e237014c1ff593b57b4d'
payment.description = 'Aerodynamic Paper Keyboard'
payment.installments = 1
payment.payment_method_id = "visa"
payment.payer = {
  email: "test@test.com"
}

payment.save()

Encontre o estado do pagamento no campo status.

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

MercadoPago.SDK.SetAccessToken("ENV_ACCESS_TOKEN");

Payment payment = new Payment()
{
    TransactionAmount = float.Parse("177"),
    Token = "ff8080814c11e237014c1ff593b57b4d",
    Description = "Aerodynamic Paper Keyboard",
    Installments = 1,
    PaymentMethodId = "visa",
    Payer = new Payer(){
        Email = "test@test.com"
    }
};

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=ENV_ACCESS_TOKEN' \
    -d '{
          "transaction_amount": 177,
          "token": "ff8080814c11e237014c1ff593b57b4d",
          "description": "Aerodynamic Paper Keyboard",
          "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.

Próximos passos

Sua pesquisa não retorna resultados.

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