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?
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.
- 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.
- 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
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.
Tenha em conta que o token tem uma validade de 7 dias e só pode ser usado uma única vez.
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
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.
<?php
require_once 'vendor/autoload.php';
MercadoPago\SDK::setAccessToken("ENV_ACCESS_TOKEN");
$payment = new MercadoPago\Payment();
$payment->transaction_amount = 105;
$payment->token = "ff8080814c11e237014c1ff593b57b4d";
$payment->description = "Durable Marble Bag";
$payment->installments = 1;
$payment->payment_method_id = "visa";
$payment->payer = array(
"email" => "jewel@yahoo.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: 105,
token: 'ff8080814c11e237014c1ff593b57b4d'
description: 'Durable Marble Bag',
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(105f)
.setToken("ff8080814c11e237014c1ff593b57b4d")
.setDescription("Durable Marble Bag")
.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 = 105
payment.token = 'ff8080814c11e237014c1ff593b57b4d'
payment.description = 'Durable Marble Bag'
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("105"),
Token = "ff8080814c11e237014c1ff593b57b4d",
Description = "Durable Marble Bag",
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": 105,
"token": "ff8080814c11e237014c1ff593b57b4d",
"description": "Durable Marble Bag",
"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:
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.
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.
Encontre o estado do pagamento no campo status.