
Lovable crea una app web funcional a partir de un chat. Si esa app vende algo, puedes cobrar en cripto con SnapEX Pay: el cliente pulsa un botón, paga en la página de SnapEX Pay en USDT o en 70+ monedas más, y tu app se entera del pago por un webhook firmado. Esta guía muestra cómo conectarlo de forma segura, con un prompt para pegar en Lovable y el código al que debería llegar.
Cómo funciona

- El cliente pulsa el botón Pay with crypto en tu app.
- Una función del backend (
create-invoice) lee el pedido de tu base de datos y crea una factura conPOST /api/v1/merchant/invoices. La clave API se lee de un secreto en el servidor. - La función devuelve
pay_urly el navegador abre la página de pago de SnapEX Pay. - Cuando la factura se paga, SnapEX Pay envía un webhook firmado
invoice.paida una segunda función (snapex-webhook). - Esa función comprueba la firma y marca el pedido como pagado en tu base de datos.
El navegador nunca ve la clave API y nunca decide ni el precio ni el estado del pago. De eso se trata: cualquiera puede llamar a una función de tu app o cambiar lo que envía el navegador, así que el precio y la marca de «pagado» tienen que venir del servidor.
Paso 1. Consigue una clave API
Abre una cuenta en pay.snapex.pro y en el panel de comercio ve a Desarrolladores → Obtener clave API. La clave empieza por smk_ y se muestra una sola vez: cópiala enseguida. Tiene todos los permisos de la Merchant API, pagos salientes incluidos, así que solo puede estar en un secreto del backend: nunca en el código del frontend, en una variable VITE_ ni en el chat. Al reemitir la clave en el panel, la anterior deja de funcionar al instante.
También puedes abrir la cuenta por API, sin la web:
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"}'
La respuesta trae api_key (se muestra una vez), un login y una password generada para el panel, y cabinet_url.
Paso 2. Pide a Lovable que construya el checkout
Pega este prompt en el chat del proyecto. Está en inglés; Lovable lo entiende en cualquier proyecto. Cuando Lovable pida SNAPEX_API_KEY, escríbela en el formulario seguro de secretos, no en el chat. SNAPEX_WEBHOOK_SECRET déjalo para después (Skip): lo obtienes en el paso 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.
Lovable convierte el prompt en código funcional; puedes abrirlo y compararlo con el código de referencia de abajo.
Paso 3. Conecta el webhook
- Copia la dirección de la función
snapex-webhook. En una app con el backend integrado: More → Database → Manage → Edge functions, abre la función y pulsa Copy URL. Si no la encuentras, pide a Lovable en el chat la URL pública de la función. - En el panel de SnapEX Pay abre Desarrolladores → Webhook, pega la URL y pulsa Guardar. La URL tiene que ser una dirección pública
https://. - Al guardar por primera vez, el panel muestra una sola vez el secreto de firma
whsec_…. Añádelo en Lovable en More → Settings → Secrets → Add secret con el nombreSNAPEX_WEBHOOK_SECRET.
El webhook del panel recibe todos los tipos de evento; la función solo reacciona a invoice.paid y responde 200 al resto. Si prefieres la API, POST /api/v1/merchant/webhooks con {"url": "…", "events": ["invoice.paid"]} crea un endpoint para los eventos que indiques (con invoice.paid llega también invoice.partially_paid) y devuelve secret una vez.
Paso 4. Prueba sin dinero real
Mientras SNAPEX_ENVIRONMENT sea test, todas las facturas son de prueba:
- Crea un pedido en tu app y pulsa Pay with crypto. La página de pago muestra la etiqueta Test.
- Elige cualquier moneda. No hay que enviar nada: unos 10 segundos después la factura pasa a pagada sola.
- Llega el webhook con
data.environment = "test"y el pedido queda pagado en tu app.
Una factura de prueba pasa por los mismos estados y envía los mismos webhooks que una real, y nunca cambia tu saldo. Si el pedido no pasa a pagado, mira en el panel Desarrolladores → Entregas del webhook (el código de respuesta que devolvió tu función, y el botón Reenviar) y los logs de la función en Lovable. Más sobre el modo de prueba: Cómo probar pagos cripto sin dinero real.
Paso 5. Pasa a producción
Cambia el secreto SNAPEX_ENVIRONMENT a live. Las nuevas facturas serán reales y la función del webhook ignorará los eventos de prueba, así que un pago de prueba nunca podrá marcar como pagado un pedido real. Las facturas pagadas se abonan a tu saldo de SnapEX Pay en USDT.
El código
Así son las dos funciones en el backend integrado (Supabase Edge Functions, Deno). No tienes que escribirlas: están aquí para que compruebes lo que escribió Lovable o se las des como referencia.
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 });
});
Lo importante:
Idempotency-Keyes obligatorio. Un reintento con la misma clave devuelve la misma factura en lugar de crear otra.- Cada
external_idse puede usar una sola vez por cuenta, tanto en prueba como en real. Por eso lleva un sufijo aleatorio corto: cuando una factura caduca (por defecto a los 30 minutos;expires_inadmite de 60 segundos a 24 horas), el siguiente clic crea una factura nueva para el mismo pedido. - La respuesta es
{"data": {...}}coninvoice_id,pay_url,status,expires_at,environment,amount_usdy tuexternal_id. - También sirve un precio en otra moneda: envía
price_amountyprice_currency(por ejemplo"EUR") en lugar deamount_usdy SnapEX Pay lo convierte. Confee_on: "customer"la comisión la paga el cliente encima del precio; consulta Quién paga las comisiones de una factura cripto.
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");
});
SnapEX Pay llama a esta función sin sesión de usuario, así que el backend no debe exigirle un token de usuario. En Supabase se configura por función en supabase/config.toml:
[functions.snapex-webhook]
verify_jwt = false
Aquí la verificación de la firma sustituye al inicio de sesión: es lo único que hace fiable la petición. Lo que llega:
| Cabecera | Significado |
|---|---|
Webhook-Id |
Id único del evento; igual en cada reintento. |
Webhook-Timestamp |
Hora Unix en segundos de este intento; nueva en cada reintento. |
Webhook-Signature |
v1= + HMAC-SHA256 en hex minúscula de {Webhook-Timestamp}.{cuerpo sin procesar}. |
El cuerpo es {"id", "type", "created_at", "data"}; en los eventos invoice.*, data es la factura con la misma forma que devuelve la API: invoice_id, status, environment, amount_usd, paid_at y tu external_id.
Detalles de la entrega que conviene saber: cualquier 2xx es éxito; los tiempos límite son 5 segundos para conectar y 15 en total; un invoice.paid fallido se reintenta, hasta 5 intentos en total (tras unos 10 s, 1 min, 5 min y 15 min). El mismo evento puede llegar dos veces, por eso la actualización de arriba solo cambia un pedido que aún no está pagado. Solo invoice.paid significa «entrega el pedido»: invoice.partially_paid indica que el cliente pagó una parte y terminó el plazo para completar. Más: Webhooks de pagos cripto: firma, reintentos y duplicados.
El botón de pago
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>
);
}
El botón solo envía el id del pedido. Tras pagar, el cliente vuelve a success_url; la página del pedido debe leer el estado de la base de datos, porque lo que marca el pedido como pagado es el webhook, no la vuelta a tu web.
Apps nuevas de Lovable
Las apps de Lovable creadas desde el 13 de mayo de 2026 usan TanStack Start y suelen ejecutar el código de servidor dentro de la propia app, como server functions y API routes, en lugar de Edge Functions. El plan no cambia: la clave es un secreto, la factura se crea en el servidor y el webhook llega a una ruta pública que lee el cuerpo sin procesar y comprueba la firma antes que nada. El prompt de arriba no nombra ninguna tecnología, así que Lovable elige la adecuada para tu app. La dirección para el webhook es entonces la URL de tu app más la ruta; pídesela a Lovable. Las rutas de servidor cambian al publicar: publica la app antes de probar el webhook.
¿Puedo usar el servidor MCP de SnapEX Pay en su lugar?
Solo como ayuda mientras construyes. SnapEX Pay tiene un servidor MCP en https://pay.snapex.pro/mcp, y Lovable puede añadirlo como servidor MCP propio (Connectors → Add custom → MCP server, autenticación Bearer token or API key con tu clave smk_). Así el chat de Lovable puede consultar monedas, tipos de cambio y comisiones o revisar una factura de prueba mientras construye tu app. Pero las conexiones del chat nunca forman parte de la app publicada, así que el checkout sigue necesitando las dos funciones de arriba. Sobre MCP: pay.snapex.pro/mcp.
Lista de comprobación
SNAPEX_API_KEYySNAPEX_WEBHOOK_SECRETsolo están en secretos del backend; nada empieza porVITE_.- El precio se lee en el servidor; el navegador solo envía el id del pedido.
- La función del webhook lee el cuerpo sin procesar, compara la firma en tiempo constante, comprueba la marca de tiempo y responde 400 si algo no cuadra.
- Un pedido pasa a pagado solo con
invoice.paidy solo una vez. - Prueba y producción están separadas por
SNAPEX_ENVIRONMENT.
Referencia completa de la API: documentación de la API de SnapEX Pay.