Pagamentos com a API do Mercado Pago em PHP
Fonte: Unsplash
Receber pagamento por cartão e Pix no Brasil quase sempre significa Mercado Pago. A boa notícia: a integração básica é uma chamada HTTP com token e a devolução de um link de checkout — dá para colocar no ar em uma tarde. A má notícia: a maioria dos bugs de pagamento vem de tratar o retorno do usuário como prova de pagamento. Este guia cobre o fluxo completo na ordem correta: preferência, redirecionamento, notificação e confirmação no servidor.
1. Antes do código: credencial, ambiente e o que é cada token
No painel do Mercado Pago existem dois ambientes: test (sandbox, com cartões de teste e saldo fictício) e production. Cada um tem seu access token próprio — nunca misture os dois. Na prática de dev, o esquema é:
- Variável de ambiente
MP_ACCESS_TOKENcom o token do ambiente atual - Sandbox para desenvolvimento, production só depois de validar o fluxo ponta a ponta
- Credencial nunca commitada: quem tem o token consegue mover dinheiro da conta
2. Criando a preferência de pagamento
A "preferência" é o carrinho traduzido para a API. Crie via cURL puro — sem depender de SDK, você vê exatamente o que sai:
$token = getenv('MP_ACCESS_TOKEN');
$payload = [
'items' => [[
'title' => 'Curso de PHP',
'quantity' => 1,
'unit_price' => 197.00,
'currency_id' => 'BRL',
]],
'external_reference' => 'PEDIDO-1042',
'back_urls' => [
'success' => 'https://minhaloja.com/obrigado',
'failure' => 'https://minhaloja.com/erro',
'pending' => 'https://minhaloja.com/pendente',
],
'auto_return' => 'approved',
];
$ch = curl_init('https://api.mercadopago.com/checkout/preferences');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $token,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($payload),
]);
$resp = json_decode(curl_exec($ch), true);
curl_close($ch);
$checkoutUrl = $resp['init_point']; // produção
$sandboxUrl = $resp['sandbox_init_point']; // teste
Três campos merecem atenção: external_reference é o identificador do seu pedido no seu sistema (é por ele que você reconcilia depois), back_urls são para o navegador do comprador e auto_return faz o redirect automático no sucesso (exige back_urls.success com domínio configurado).
3. Redirecionar não é confirmar: a regra de ouro
O comprador volta para obrigado com query string contendo payment_id e status. Mas essa URL vem do navegador — pode ser alterada, recarregada ou chegar atrasada. Nunca libere produto com base nela. O fluxo seguro é:
- Usuário volta para a página de sucesso (mostra "processando")
- Front-end chama seu endpoint
/webhook/mercado-pagoou o servidor consulta a API - Você confere o status real na API antes de entregar
$pagamento = json_decode(file_get_contents(
"https://api.mercadopago.com/v1/payments/{$paymentId}",
false,
stream_context_create([
'http' => ['header' => "Authorization: Bearer {$token}\r\n"]
])
), true);
if ($pagamento['status'] === 'approved' &&
$pagamento['external_reference'] === 'PEDIDO-1042') {
liberarPedido($pagamento['external_reference']);
}
Status que você vai ver no dia a dia: approved, pending (Pix em processamento), in_process (análise de risco), rejected, cancelled, refunded. Em Pix, o comprador pode voltar para a página antes do pagamento cair — por isso o pending é comum e a confirmação final vem depois.
4. Webhook: recebendo a notificação da API
Configure no painel (Integrações → Webhooks) a URL do seu endpoint para eventos de pagamento. O Mercado Pago envia uma chamada POST com o id do recurso; você consulta a API como acima. Ponto de atenção de produção: o webhook chega do servidor da plataforma, então seu endpoint precisa ser público, rápido e idempotente — a mesma notificação pode chegar mais de uma vez. Trate "processar pagamento" como operação repetível: consulte o status, verifique se o pedido já foi liberado e só então aja.
Para validar que a notificação veio mesmo da plataforma, o Mercado Pago envia um header de assinatura (x-signature) calculado com HMAC-SHA256 sobre um manifesto que inclui id do recurso, request-id e timestamp, usando o secret do webhook configurado no painel. Vale implementar essa verificação antes de confiar no payload.
5. Estornos, reembolsos e consultas frequentes
# reembolso total
POST /v1/payments/{id}/refund
# detalhe do pagamento
GET /v1/payments/{id}
# busca por referência do seu pedido
GET /v1/payments/search?external_reference=PEDIDO-1042
No PHP, os mesmos endpoints via curl ou file_get_contents. Guarda sempre o payment_id retornado junto ao pedido no seu banco: sem ele, o suporte vira caça ao tesouro no painel. E lembre do custo: reembolso não devolve a taxa da transação — essa conta faz diferença quando o produto tem margem apertada.
6. Checklist antes de ir para produção
- Token de produção no ambiente, fora do código
- Webhook testado com o fluxo sandbox ponta a ponta
- Confirmação por servidor (nunca só pelo retorno do navegador)
external_referencepreenchido com o id do pedido- Página de sucesso idempotente: recarregar não duplica entrega
- Log de id de pagamento e status para conciliação
Na prática, comece com o checkout transparente ou o init_point (link gerado), valide tudo em sandbox — inclusive o caso do Pix pendente — e só depois troque o token. Quem pula essa etapa descobre o problema no primeiro cliente real, com dinheiro em análise e sem log para investigar.