TECNOLANDIA TECH
Publicidade

Conecte-se com o Tecnolândia Tech

BLOG + INSTAGRAM + FACEBOOK

Tecnologia na prática, em todos os formatos.

Aqui no Tecnolândia Tech, você encontra artigos e guias completos. No Instagram @djwinformatica e no Facebook TecnoInfo, acompanhe vídeos, dicas e novidades de IA, automação e tecnologia. São nossos canais oficiais.

Pagamentos com a API do Mercado Pago em PHP

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_TOKEN com 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 é:

  1. Usuário volta para a página de sucesso (mostra "processando")
  2. Front-end chama seu endpoint /webhook/mercado-pago ou o servidor consulta a API
  3. 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_reference preenchido 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.

Publicidade