
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 cliente clica no botão Pay with crypto do seu app.
- Uma função do backend (
create-invoice) lê o pedido do seu banco de dados e cria uma fatura comPOST /api/v1/merchant/invoices. A chave de API é lida de um segredo no servidor. - A função devolve
pay_url, e o navegador abre a página de pagamento do SnapEX Pay. - Quando a fatura é paga, o SnapEX Pay envia um webhook assinado
invoice.paidpara uma segunda função (snapex-webhook). - 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
- 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. - 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://. - 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 nomeSNAPEX_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:
- Crie um pedido no app e clique em Pay with crypto. A página de pagamento mostra o selo Test.
- Escolha qualquer moeda. Não é preciso enviar nada: cerca de 10 segundos depois a fatura fica paga sozinha.
- 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_idsó 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_inaceita de 60 segundos a 24 horas), o próximo clique cria uma fatura nova para o mesmo pedido. - A resposta é
{"data": {...}}cominvoice_id,pay_url,status,expires_at,environment,amount_usde o seuexternal_id. - Um preço em outra moeda também funciona: envie
price_amounteprice_currency(por exemplo"EUR") em vez deamount_usd, e o SnapEX Pay converte. Comfee_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_KEYeSNAPEX_WEBHOOK_SECRETficam só em segredos do backend; nada começa comVITE_.- 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.paide 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.