Como receber via Pix num app feito no Lovable/Bolt: Mercado Pago, webhooks e os erros mais comuns
O Lovable documenta pagamentos nativos com Stripe ou Paddle, e também a conexão com a sua própria conta Stripe (documentação do Lovable). Se o comprador está no Brasil e vai pagar com Pix, o Mercado Pago documenta um fluxo diferente: o pagamento é criado no servidor, o app só exibe o QR Code e o Pix Copia e Cola, e o acesso só é liberado quando uma notificação — com a assinatura validada — confirma o status approved.
Abaixo está esse fluxo numa Edge Function do Supabase, com a verificação do cabeçalho x-signature. Os trechos repetem o que está nas documentações oficiais, com o link ao lado. Não substitui a leitura dessas páginas nem um teste com credenciais de teste.
O que você precisa antes
- Uma conta de vendedor no Mercado Pago com chaves Pix cadastradas. Sem isso, a opção não aparece (pré-requisitos do Checkout Transparente).
- Uma aplicação em Suas integrações, com a public key e o access token de teste.
- Um backend. No caso de um app feito no Lovable ou no Bolt, o caminho usual é o Supabase: é lá que ficam a Edge Function e os segredos.
1. O access token fica no servidor
O access token cria cobranças e lê pagamentos da sua conta. Salve-o como segredo do Supabase (por exemplo MP_ACCESS_TOKEN) e use-o só dentro de Edge Functions. No navegador vai, no máximo, a public key. Se o token já apareceu no código, no repositório ou no histórico do Git, gere outro no painel do Mercado Pago antes de seguir.
O preço também é definido no servidor, não no corpo que o navegador envia. Se o valor vier do frontend, qualquer pessoa pode alterá-lo.
2. Crie o pagamento Pix numa Edge Function
A documentação do Mercado Pago descreve o Pix como um POST em /v1/payments com payment_method_id: "pix", o e-mail do comprador e o cabeçalho obrigatório X-Idempotency-Key, que evita cobrança duplicada se a requisição for repetida (documentação Pix).
// supabase/functions/criar-pix/index.ts
Deno.serve(async (req) => {
const { email, pedidoId } = await req.json();
const PRECO = 49.90; // definido aqui, nunca no navegador
const r = await fetch("https://api.mercadopago.com/v1/payments", {
method: "POST",
headers: {
"Authorization": `Bearer ${Deno.env.get("MP_ACCESS_TOKEN")}`,
"Content-Type": "application/json",
"X-Idempotency-Key": crypto.randomUUID(),
},
body: JSON.stringify({
transaction_amount: PRECO,
description: "Plano Pro",
payment_method_id: "pix",
external_reference: pedidoId,
payer: { email },
}),
});
const p = await r.json();
const t = p.point_of_interaction?.transaction_data;
return Response.json({
id: p.id,
status: p.status,
qr_code: t?.qr_code,
qr_code_base64: t?.qr_code_base64,
ticket_url: t?.ticket_url,
});
});
Por padrão, o código Pix vence em 24 horas. Dá para mudar isso com date_of_expiration, entre 30 minutos e 30 dias a partir da emissão (mesma documentação).
O Mercado Pago também documenta o Pix na Orders API, com payment_method.type = "bank_transfer" (documentação da Orders API). A lógica é a mesma: criar no servidor, exibir o QR e confirmar pelo webhook.
3. Mostre o QR Code e o Copia e Cola — e não libere o acesso nessa tela
A resposta chega com status pending e status_detail pending_waiting_transfer, e traz em point_of_interaction.transaction_data três campos úteis: qr_code_base64 (a imagem), qr_code (o texto do Pix Copia e Cola) e ticket_url (uma página do Mercado Pago com os dois).
O Pix é pago fora do seu app, no banco do comprador. A tela de “aguardando pagamento” ou de “obrigado” não prova que a transferência aconteceu: qualquer pessoa pode abrir essa URL. A confirmação tem que vir do servidor.
4. Valide o cabeçalho x-signature antes de confiar no aviso
Em Suas integrações → Webhooks, configure uma URL que aponte para outra Edge Function (por exemplo https://SEU-PROJETO.supabase.co/functions/v1/webhook-mp) e copie a chave secreta para um segredo MP_WEBHOOK_SECRET. As URLs que você configurar na criação do pagamento têm prioridade sobre as de Suas integrações (documentação de webhooks). As notificações de Código QR não levam essa assinatura e não devem usar este procedimento.
Por padrão, as Edge Functions do Supabase exigem um JWT válido no cabeçalho de autorização. O Mercado Pago não envia um JWT do Supabase, então esta função precisa de verify_jwt = false no supabase/config.toml. É o padrão que o Supabase documenta para webhooks de provedores de pagamento (configuração de funções). A autenticidade passa a ser conferida pela assinatura do Mercado Pago, não pelo JWT.
[functions.webhook-mp]
verify_jwt = false
Cada notificação chega com um cabeçalho x-signature neste formato:
ts=1704908010,v1=618c85345248dd820d5fd456117c2ab2ef8eda45a0282ff693eac24131a5e839
Também são necessários o cabeçalho x-request-id e o parâmetro data.id da query da URL. Com esses valores você monta o manifesto e calcula um HMAC-SHA256 em hexadecimal, usando o seu segredo como chave:
id:<data.id>;request-id:<x-request-id>;ts:<ts>;
Se data.id vier com letras maiúsculas (acontece com alguns ids de ordens), a documentação pede para passar para minúsculas antes de usar. Se faltar data.id ou x-request-id, esses trechos saem do manifesto. O resultado tem que coincidir exatamente com v1. Se não coincidir, responda 401 e não ative nada (documentação de webhooks).
Numa Edge Function (Deno), isso pode ser feito com a Web Crypto API:
// supabase/functions/webhook-mp/index.ts
async function hmacHex(secret: string, message: string) {
const key = await crypto.subtle.importKey(
"raw",
new TextEncoder().encode(secret),
{ name: "HMAC", hash: "SHA-256" },
false,
["sign"],
);
const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(message));
return [...new Uint8Array(sig)].map((b) => b.toString(16).padStart(2, "0")).join("");
}
function part(header: string, name: string) {
for (const p of header.split(",")) {
const [k, ...rest] = p.trim().split("=");
if (k === name) return rest.join("=");
}
return "";
}
Deno.serve(async (req) => {
const secret = Deno.env.get("MP_WEBHOOK_SECRET") ?? "";
const xSignature = req.headers.get("x-signature") ?? "";
const xRequestId = req.headers.get("x-request-id") ?? "";
let dataId = new URL(req.url).searchParams.get("data.id") ?? "";
if (/[A-Z]/.test(dataId)) dataId = dataId.toLowerCase();
const ts = part(xSignature, "ts");
const v1 = part(xSignature, "v1");
let manifest = "";
if (dataId) manifest += `id:${dataId};`;
if (xRequestId) manifest += `request-id:${xRequestId};`;
manifest += `ts:${ts};`;
const expected = await hmacHex(secret, manifest);
if (!secret || !v1 || expected !== v1) {
return new Response("unauthorized", { status: 401 });
}
// Assinatura válida: consultar o pagamento na API (abaixo) e só então ativar o plano.
return new Response("ok", { status: 200 });
});
Os SDKs oficiais expõem um WebhookSignatureValidator que faz a mesma conferência (guia de webhooks do SDK Node).
5. Responda 200 em até 22 segundos e trate o aviso como um sinal
Quando a notificação chega, o Mercado Pago espera um HTTP 200 ou 201 em 22 segundos. Se não receber, tenta de novo a cada 15 minutos; depois da terceira tentativa o prazo é prorrogado, mas os envios continuam (documentação de webhooks).
Por isso a função precisa ser idempotente: a mesma notificação pode chegar mais de uma vez e também fora de ordem. O guia do SDK oficial recomenda tratar o aviso como um sinal de mudança e a consulta à API como a fonte da verdade atual.
6. Consulte o pagamento na API e só ative se estiver approved
Com a assinatura já validada, busque o recurso com o access token. Para um pagamento da Payments API ou do Checkout Pro:
GET https://api.mercadopago.com/v1/payments/{id}
Authorization: Bearer <MP_ACCESS_TOKEN>
Ative o plano do usuário só se status for approved. Guarde o id do pagamento na sua base e não processe o mesmo id duas vezes. Não use o valor nem o status que vierem no corpo da notificação como verdade final.
Se você guarda os pedidos numa tabela do Supabase, ative Row Level Security e deixe que só a Edge Function (com a chave secreta do servidor) escreva o status. O usuário autenticado pode ler o próprio pedido, não marcar a si mesmo como “pro”.
Antes de ir para produção, use as credenciais de teste do Mercado Pago, faça uma compra de teste com Pix e confira três coisas: uma assinatura inválida responde 401, uma válida consulta a API, e um reenvio não ativa o plano duas vezes. A documentação do Checkout Transparente tem uma seção específica para a compra de teste com Pix (visão geral).
Erros comuns (o que a documentação pede para não fazer)
Estes pontos saem das próprias guias citadas acima, não de um diário de incidentes:
- Access token no frontend. Com ele é possível criar cobranças e ler pagamentos da conta.
- Preço enviado pelo navegador. O valor é definido na Edge Function que cria o pagamento.
- Liberar o acesso na tela de “obrigado”. Sem webhook validado, qualquer pessoa chega nessa URL sem pagar.
- Webhook sem validar
x-signature. A URL da função, sozinha, não autentica o remetente. - Sem
X-Idempotency-Keyna criação do pagamento. Um clique duplo pode gerar dois Pix. - Edge Function com a verificação de JWT padrão. O Mercado Pago não envia um JWT do Supabase; o aviso nem chega a ser processado.
- Tratar cada notificação como um evento único. Os reenvios a cada 15 minutos exigem idempotência.
Transparência: fiz uma ferramenta gratuita que, num repositório público de GitHub, procura segredos expostos no frontend e outros pontos de um checklist de lançamento (não substitui validar o webhook nem consultar o pagamento na API): https://rodrix91.github.io/launchlatam/pt/#escaneo