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?
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.
- 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.
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>
3. Configure sua chave pública
Configure sua chave pública da seguinte forma:
javascript
window.Mercadopago.setPublishableKey("YOUR_PUBLIC_KEY");
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();
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.
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
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": [],
...
}
Mensagens de respostas
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 as mensagens de respostas e utilizar a comunicação sugerida em cada um dos casos.
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.