1

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:

  1. Access token no frontend. Com ele é possível criar cobranças e ler pagamentos da conta.
  2. Preço enviado pelo navegador. O valor é definido na Edge Function que cria o pagamento.
  3. Liberar o acesso na tela de “obrigado”. Sem webhook validado, qualquer pessoa chega nessa URL sem pagar.
  4. Webhook sem validar x-signature. A URL da função, sozinha, não autentica o remetente.
  5. Sem X-Idempotency-Key na criação do pagamento. Um clique duplo pode gerar dois Pix.
  6. 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.
  7. 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

Carregando publicação patrocinada...