Seções da página
PT

Como aceitar pagamentos em cripto em um app do Lovable com o SnapEX Pay

Pagamentos em cripto em um app do Lovable com o SnapEX Pay

O Lovable cria um app web funcional a partir de um chat. Se o app vende algo, você pode receber em cripto com o SnapEX Pay: o cliente clica em um botão, paga na página do SnapEX Pay em USDT ou em mais 70+ moedas, e o app fica sabendo do pagamento por um webhook assinado. Este guia mostra como ligar tudo com segurança, com um prompt para colar no Lovable e o código ao qual ele deve chegar.

Como funciona

O fluxo do pagamento: app do Lovable → função create-invoice → SnapEX Pay → webhook → tabela de pedidos

  1. O cliente clica no botão Pay with crypto do seu app.
  2. Uma função do backend (create-invoice) lê o pedido do seu banco de dados e cria uma fatura com POST /api/v1/merchant/invoices. A chave de API é lida de um segredo no servidor.
  3. A função devolve pay_url, e o navegador abre a página de pagamento do SnapEX Pay.
  4. Quando a fatura é paga, o SnapEX Pay envia um webhook assinado invoice.paid para uma segunda função (snapex-webhook).
  5. Essa função verifica a assinatura e marca o pedido como pago no banco de dados.

O navegador nunca vê a chave de API e nunca decide o preço nem o status do pagamento. É esse o ponto: qualquer pessoa pode chamar uma função do seu app ou alterar o que o navegador envia, então o preço e a marcação de «pago» precisam vir do servidor.

Passo 1. Obtenha uma chave de API

Abra uma conta em pay.snapex.pro e, no painel do comerciante, vá em Desenvolvedores → Obter chave de API. A chave começa com smk_ e aparece uma única vez: copie-a na hora. Ela tem todas as permissões da Merchant API, inclusive saques, então só pode ficar em um segredo do backend: nunca no código do frontend, em uma variável VITE_ ou no chat. Reemitir a chave no painel desativa a anterior na hora.

Também dá para abrir a conta pela API, sem o site:

curl -sS -X POST https://pay.snapex.pro/api/v1/merchant/signup \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"email": "[email protected]", "agent": "lovable"}'

A resposta traz api_key (mostrada uma vez), um login e uma password gerada para o painel, e cabinet_url.

Passo 2. Peça ao Lovable para montar o checkout

Cole este prompt no chat do projeto. Ele está em inglês; o Lovable entende em qualquer projeto. Quando o Lovable pedir SNAPEX_API_KEY, digite a chave no formulário seguro de segredos, não no chat. Pule SNAPEX_WEBHOOK_SECRET por enquanto (Skip): você o recebe no passo 3.

Add a crypto checkout with SnapEX Pay.
API docs: https://pay.snapex.pro/partner/merchant/docs

Server side only, never in frontend code:
- Secrets: SNAPEX_API_KEY, SNAPEX_WEBHOOK_SECRET, SNAPEX_ENVIRONMENT
  ("test" for now), SITE_URL (the app's public URL). Ask me for them
  with the secret form.
- Table orders: id uuid, amount_usd numeric, status text default
  'pending', snapex_invoice_id text, pay_url text, invoice_expires_at
  timestamptz, paid_at timestamptz. Users read only their own orders;
  only server code changes status.
- Function create-invoice, input { orderId }: load the order on the
  server (the amount comes from the database, never from the browser).
  If pay_url is set and invoice_expires_at is in the future, return it.
  Otherwise POST https://pay.snapex.pro/api/v1/merchant/invoices with
  headers Authorization: Bearer SNAPEX_API_KEY, Content-Type and Accept:
  application/json, Idempotency-Key: <external_id>. JSON body:
  amount_usd (string, 2 decimals), external_id "<order id>:<8 random
  characters>", description, environment SNAPEX_ENVIRONMENT, success_url
  and cancel_url SITE_URL/orders/<order id>. Save data.invoice_id,
  data.pay_url and data.expires_at on the order; return { pay_url }.
- Function snapex-webhook, public (no user login check). Read the raw
  body as text. Header Webhook-Signature must equal "v1=" + hex
  HMAC-SHA256 of "<Webhook-Timestamp>.<raw body>" keyed with
  SNAPEX_WEBHOOK_SECRET; compare in constant time; reject a
  Webhook-Timestamp more than 300 seconds off; answer 400 if the check
  fails. On type "invoice.paid" with data.environment equal to
  SNAPEX_ENVIRONMENT: the order id is data.external_id before ":"; if
  data.amount_usd is not below the order amount, set status 'paid' and
  paid_at = data.paid_at only where status is not 'paid'. Answer 200
  quickly; answer 500 only if the database update fails.

Frontend: a "Pay with crypto" button on the order page that calls
create-invoice and opens pay_url; the order page shows the status.

O Lovable transforma o prompt em código funcional; você pode abri-lo e comparar com o código de referência abaixo.

Passo 3. Conecte o webhook

  1. Copie o endereço da função snapex-webhook. Em um app com o backend integrado: More → Database → Manage → Edge functions, abra a função e clique em Copy URL. Se não encontrar, peça ao Lovable no chat a URL pública da função.
  2. No painel do SnapEX Pay, abra Desenvolvedores → Webhook, cole a URL e clique em Salvar. A URL precisa ser um endereço público https://.
  3. No primeiro salvamento, o painel mostra uma única vez o segredo de assinatura whsec_…. Adicione-o no Lovable em More → Settings → Secrets → Add secret com o nome SNAPEX_WEBHOOK_SECRET.

O webhook do painel recebe todos os tipos de evento; a função só reage a invoice.paid e responde 200 aos demais. Se preferir a API, POST /api/v1/merchant/webhooks com {"url": "…", "events": ["invoice.paid"]} cria um endpoint para os eventos listados (com invoice.paid chega também invoice.partially_paid) e devolve secret uma vez.

Passo 4. Teste sem dinheiro real

Enquanto SNAPEX_ENVIRONMENT for test, todas as faturas são de teste:

  1. Crie um pedido no app e clique em Pay with crypto. A página de pagamento mostra o selo Test.
  2. Escolha qualquer moeda. Não é preciso enviar nada: cerca de 10 segundos depois a fatura fica paga sozinha.
  3. O webhook chega com data.environment = "test", e o pedido fica pago no app.

Uma fatura de teste passa pelos mesmos status e envia os mesmos webhooks que uma real, e nunca altera o seu saldo. Se o pedido não ficar pago, veja no painel Desenvolvedores → Entregas do webhook (o código de resposta que a função devolveu, e o botão Reenviar) e os logs da função no Lovable. Mais sobre o modo de teste: Como testar pagamentos em cripto sem dinheiro real.

Passo 5. Entre em produção

Mude o segredo SNAPEX_ENVIRONMENT para live. As novas faturas passam a ser reais, e a função do webhook passa a ignorar eventos de teste, então um pagamento de teste nunca marca um pedido real como pago. Faturas pagas são creditadas no seu saldo do SnapEX Pay em USDT.

O código

É assim que ficam as duas funções no backend integrado (Supabase Edge Functions, Deno). Você não precisa digitá-las: elas estão aqui para conferir o que o Lovable escreveu ou para passar a ele como referência.

create-invoice

// supabase/functions/create-invoice/index.ts
import { createClient } from "npm:@supabase/supabase-js@2";

const SNAPEX_API = "https://pay.snapex.pro/api/v1/merchant";
const cors = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers":
    "authorization, x-client-info, apikey, content-type",
  "Access-Control-Allow-Methods": "POST, OPTIONS",
};
const json = (body: unknown, status = 200) =>
  new Response(JSON.stringify(body), {
    status,
    headers: { ...cors, "Content-Type": "application/json" },
  });

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") return new Response(null, { headers: cors });
  if (req.method !== "POST") return json({ error: "method not allowed" }, 405);

  const { orderId } = await req.json().catch(() => ({}));
  if (typeof orderId !== "string" || orderId === "") {
    return json({ error: "orderId is required" }, 400);
  }

  // The price comes from your database, never from the browser.
  const db = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!,
  );
  const { data: order } = await db.from("orders")
    .select("id, amount_usd, status, pay_url, invoice_expires_at")
    .eq("id", orderId).maybeSingle();
  if (!order) return json({ error: "order not found" }, 404);
  if (order.status === "paid") return json({ error: "already paid" }, 409);

  // An open invoice is reused: a second click opens the same page.
  const open = order.invoice_expires_at &&
    new Date(order.invoice_expires_at) > new Date();
  if (order.pay_url && open) return json({ pay_url: order.pay_url });

  // external_id is unique per merchant account: a new invoice for the
  // same order (after the old one expired) gets a new suffix.
  const externalId = `${order.id}:${crypto.randomUUID().slice(0, 8)}`;
  const site = Deno.env.get("SITE_URL"); // https://your-app.lovable.app
  const back = site ? `${site}/orders/${order.id}` : undefined;

  const res = await fetch(`${SNAPEX_API}/invoices`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${Deno.env.get("SNAPEX_API_KEY")}`,
      "Content-Type": "application/json",
      "Accept": "application/json",
      "Idempotency-Key": externalId,
    },
    body: JSON.stringify({
      amount_usd: Number(order.amount_usd).toFixed(2),
      external_id: externalId,
      description: `Order ${order.id}`,
      environment: Deno.env.get("SNAPEX_ENVIRONMENT") ?? "test",
      success_url: back,
      cancel_url: back,
    }),
  });
  const payload = await res.json().catch(() => ({}));
  if (!res.ok) {
    console.error("SnapEX Pay error", res.status, JSON.stringify(payload));
    return json({ error: "could not create the invoice" }, 502);
  }

  const invoice = payload.data;
  await db.from("orders").update({
    snapex_invoice_id: invoice.invoice_id,
    pay_url: invoice.pay_url,
    invoice_expires_at: invoice.expires_at,
  }).eq("id", order.id);

  return json({ pay_url: invoice.pay_url });
});

O que importa aqui:

  • Idempotency-Key é obrigatório. Uma nova tentativa com a mesma chave devolve a mesma fatura em vez de criar outra.
  • Cada external_id só pode ser usado uma vez por conta, em teste e em produção. Por isso ele ganha um sufixo aleatório curto: quando a fatura expira (por padrão em 30 minutos; expires_in aceita de 60 segundos a 24 horas), o próximo clique cria uma fatura nova para o mesmo pedido.
  • A resposta é {"data": {...}} com invoice_id, pay_url, status, expires_at, environment, amount_usd e o seu external_id.
  • Um preço em outra moeda também funciona: envie price_amount e price_currency (por exemplo "EUR") em vez de amount_usd, e o SnapEX Pay converte. Com fee_on: "customer" o cliente paga a taxa por cima do preço; veja Who pays the crypto payment fee (em inglês).

snapex-webhook

// supabase/functions/snapex-webhook/index.ts
import { createClient } from "npm:@supabase/supabase-js@2";

const enc = new TextEncoder();

async function hmacHex(secret: string, message: string): Promise<string> {
  const key = await crypto.subtle.importKey(
    "raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" },
    false, ["sign"],
  );
  const mac = await crypto.subtle.sign("HMAC", key, enc.encode(message));
  return Array.from(new Uint8Array(mac))
    .map((b) => b.toString(16).padStart(2, "0")).join("");
}

// Constant time: the duration does not depend on where the strings differ.
function safeEqual(a: string, b: string): boolean {
  const x = enc.encode(a);
  const y = enc.encode(b);
  let diff = x.length ^ y.length;
  for (let i = 0; i < Math.max(x.length, y.length); i++) {
    diff |= (x[i] ?? 0) ^ (y[i] ?? 0);
  }
  return diff === 0;
}

const cents = (usd: unknown) => Math.round(Number(usd) * 100);
const reply = (text: string, status = 200) => new Response(text, { status });

Deno.serve(async (req) => {
  if (req.method !== "POST") return reply("method not allowed", 405);
  const secret = Deno.env.get("SNAPEX_WEBHOOK_SECRET");
  if (!secret) return reply("webhook secret is not set", 500);

  // 1. The raw body, exactly as received: the signature covers these bytes.
  const body = await req.text();
  const ts = req.headers.get("Webhook-Timestamp") ?? "";
  const signature = req.headers.get("Webhook-Signature") ?? "";

  // 2. "v1=" + HMAC-SHA256 of "{timestamp}.{body}" keyed with whsec_….
  const expected = "v1=" + await hmacHex(secret, `${ts}.${body}`);
  // 3. Not older than 5 minutes: every retry carries a fresh timestamp.
  const age = Math.abs(Date.now() / 1000 - Number(ts));
  if (!/^\d+$/.test(ts) || age > 300 || !safeEqual(signature, expected)) {
    return reply("invalid signature", 400);
  }

  const event = JSON.parse(body);
  if (event.type !== "invoice.paid") return reply("ok"); // nothing to do

  // Test events never touch live orders, and the other way round.
  const invoice = event.data;
  const env = Deno.env.get("SNAPEX_ENVIRONMENT") ?? "test";
  if (invoice.environment !== env) return reply("ignored");

  const orderId = String(invoice.external_id ?? "").split(":")[0];
  const db = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!,
  );
  const { data: order } = await db.from("orders")
    .select("id, amount_usd, status").eq("id", orderId).maybeSingle();
  if (!order) {
    console.error("paid invoice of an unknown order", invoice.invoice_id);
    return reply("unknown order");
  }
  if (cents(invoice.amount_usd) < cents(order.amount_usd)) {
    console.error("invoice amount is below the order", invoice.invoice_id);
    return reply("amount mismatch");
  }

  // Only an unpaid order changes: a repeated delivery does nothing.
  const { error } = await db.from("orders").update({
    status: "paid",
    paid_at: invoice.paid_at,
    snapex_invoice_id: invoice.invoice_id,
  }).eq("id", order.id).neq("status", "paid");
  // A non-2xx answer makes SnapEX Pay retry the delivery later.
  if (error) return reply("database error", 500);

  return reply("ok");
});

O SnapEX Pay chama esta função sem sessão de usuário, então o backend não deve exigir um token de usuário para ela. No Supabase isso é configurado por função em supabase/config.toml:

[functions.snapex-webhook]
verify_jwt = false

Aqui a verificação da assinatura substitui o login: é a única coisa que torna a requisição confiável. O que chega:

Cabeçalho Significado
Webhook-Id Id único do evento; o mesmo em cada nova tentativa.
Webhook-Timestamp Hora Unix em segundos desta tentativa; nova a cada tentativa.
Webhook-Signature v1= + HMAC-SHA256 em hex minúsculo de {Webhook-Timestamp}.{corpo bruto}.

O corpo é {"id", "type", "created_at", "data"}; nos eventos invoice.*, data é a fatura no mesmo formato que a API devolve: invoice_id, status, environment, amount_usd, paid_at e o seu external_id.

Detalhes da entrega que vale saber: qualquer 2xx é sucesso; os limites de tempo são 5 segundos para conectar e 15 no total; um invoice.paid que falhou é reenviado, até 5 tentativas no total (após cerca de 10 s, 1 min, 5 min e 15 min). O mesmo evento pode chegar duas vezes, por isso a atualização acima só muda um pedido que ainda não está pago. Só invoice.paid significa «entregue o pedido»: invoice.partially_paid indica que o cliente pagou uma parte e o prazo para completar acabou. Mais: Webhooks de pagamentos cripto: assinatura, novas tentativas e duplicatas.

O botão de pagamento

import { useState } from "react";
import { supabase } from "@/integrations/supabase/client";

export function PayWithCrypto({ orderId }: { orderId: string }) {
  const [busy, setBusy] = useState(false);

  async function pay() {
    setBusy(true);
    const { data, error } = await supabase.functions.invoke(
      "create-invoice",
      { body: { orderId } },
    );
    if (error || !data?.pay_url) {
      setBusy(false);
      alert("Could not start the payment. Please try again.");
      return;
    }
    window.location.href = data.pay_url; // the SnapEX Pay payment page
  }

  return (
    <button onClick={pay} disabled={busy}>
      {busy ? "Opening…" : "Pay with crypto"}
    </button>
  );
}

O botão envia só o id do pedido. Depois de pagar, o cliente volta para success_url; a página do pedido deve ler o status do banco de dados, porque quem marca o pedido como pago é o webhook, não a volta ao seu site.

Apps novos do Lovable

Os apps do Lovable criados a partir de 13 de maio de 2026 usam TanStack Start e costumam rodar o código de servidor dentro do próprio app, como server functions e API routes, em vez de Edge Functions. O plano é o mesmo: a chave fica em um segredo, a fatura é criada no servidor e o webhook chega a uma rota pública que lê o corpo bruto e verifica a assinatura antes de tudo. O prompt acima não cita nenhuma tecnologia, então o Lovable escolhe a certa para o seu app. O endereço do webhook passa a ser a URL do app mais o caminho da rota; peça-o ao Lovable. Rotas de servidor mudam quando você publica: publique o app antes de testar o webhook.

Posso usar o servidor MCP do SnapEX Pay no lugar?

Só como ajuda enquanto você constrói. O SnapEX Pay tem um servidor MCP em https://pay.snapex.pro/mcp, e o Lovable pode adicioná-lo como servidor MCP próprio (Connectors → Add custom → MCP server, autenticação Bearer token or API key com a sua chave smk_). Assim o chat do Lovable pode consultar moedas, cotações e taxas ou verificar uma fatura de teste enquanto monta o app. Mas as conexões do chat nunca fazem parte do app publicado, então o checkout continua precisando das duas funções acima. Sobre o MCP: pay.snapex.pro/mcp.

Checklist

  • SNAPEX_API_KEY e SNAPEX_WEBHOOK_SECRET ficam só em segredos do backend; nada começa com VITE_.
  • O preço é lido no servidor; o navegador envia só o id do pedido.
  • A função do webhook lê o corpo bruto, compara a assinatura em tempo constante, verifica o timestamp e responde 400 se algo não bater.
  • Um pedido fica pago só com invoice.paid e só uma vez.
  • Teste e produção são separados por SNAPEX_ENVIRONMENT.

Referência completa da API: documentação da API do SnapEX Pay.

Mais guias

Pronto para aceitar cripto?

Crie uma conta de comerciante e obtenha uma chave de API. 1% por pagamento, sem mensalidade.

Sorteio de $200

Para um participante aleatório.

Termina em 2d 13h 13min 33s Inscrever-se @snapex_pay