Разделы страницы
RU

Как принимать криптоплатежи в приложении на Lovable через SnapEX Pay

Криптоплатежи в приложении на Lovable через SnapEX Pay

Lovable собирает работающее веб-приложение из чата. Если приложение что-то продаёт, оплату можно принимать в криптовалюте через SnapEX Pay: клиент нажимает кнопку, платит на странице SnapEX Pay в USDT или ещё в 70+ монетах, а приложение узнаёт об оплате из подписанного вебхука. Ниже — как подключить это безопасно: промпт, который можно вставить в Lovable, и код, который должен получиться.

Как это работает

Схема оплаты: приложение Lovable → функция create-invoice → SnapEX Pay → вебхук → таблица заказов

  1. Клиент нажимает в приложении кнопку Pay with crypto.
  2. Серверная функция (create-invoice) читает заказ из вашей базы и создаёт счёт запросом POST /api/v1/merchant/invoices. API-ключ она берёт из секрета на сервере.
  3. Функция возвращает pay_url, и браузер открывает страницу оплаты SnapEX Pay.
  4. Когда счёт оплачен, SnapEX Pay отправляет подписанный вебхук invoice.paid во вторую функцию (snapex-webhook).
  5. Функция проверяет подпись и отмечает заказ оплаченным в базе.

Браузер не видит API-ключ и не решает ни цену, ни статус оплаты. В этом весь смысл: функцию вашего приложения может вызвать кто угодно, а то, что отправляет браузер, можно подменить, поэтому цена и отметка «оплачено» должны приходить с сервера.

Шаг 1. Получите API-ключ

Откройте аккаунт на pay.snapex.pro, затем в кабинете мерчанта — Разработчикам → Получить API-ключ. Ключ начинается с smk_ и показывается один раз: сразу скопируйте его. У ключа есть все права Merchant API, включая выплаты, поэтому его место — только в секрете бэкенда, а не во фронтенде, не в переменной VITE_ и не в чате. Перевыпуск ключа в кабинете сразу отключает прежний.

Аккаунт можно открыть и через API, без сайта:

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"}'

В ответе — api_key (показывается один раз), login и сгенерированный password для входа в кабинет, и cabinet_url.

Шаг 2. Попросите Lovable собрать оплату

Вставьте этот промпт в чат проекта. Он на английском — Lovable поймёт его в любом проекте. Когда Lovable попросит SNAPEX_API_KEY, введите ключ в защищённую форму секрета, а не в чат. SNAPEX_WEBHOOK_SECRET пока пропустите (Skip): он появится на шаге 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 превратит промпт в рабочий код; его можно открыть и сравнить с эталоном ниже.

Шаг 3. Подключите вебхук

  1. Скопируйте адрес функции snapex-webhook. В приложении на встроенном бэкенде: More → Database → Manage → Edge functions, откройте функцию и нажмите Copy URL. Если не находите — спросите в чате Lovable публичный адрес функции.
  2. В кабинете SnapEX Pay откройте Разработчикам → Webhook, вставьте адрес и нажмите Сохранить. Адрес должен быть публичным, https://.
  3. При первом сохранении кабинет один раз покажет секрет подписи whsec_…. Добавьте его в Lovable: More → Settings → Secrets → Add secret, имя SNAPEX_WEBHOOK_SECRET.

Вебхук из кабинета получает события всех типов; функция реагирует только на invoice.paid, на остальные отвечает 200. Через API — POST /api/v1/merchant/webhooks с {"url": "…", "events": ["invoice.paid"]}: так создаётся адрес для перечисленных событий (вместе с invoice.paid приходит и invoice.partially_paid), а secret возвращается один раз.

Шаг 4. Проверьте без реальных денег

Пока SNAPEX_ENVIRONMENT равен test, все счета тестовые:

  1. Создайте заказ в приложении и нажмите Pay with crypto. На странице оплаты — значок Test.
  2. Выберите любую монету. Ничего отправлять не нужно: примерно через 10 секунд счёт сам станет оплаченным.
  3. Придёт вебхук с data.environment = "test", и заказ в приложении станет оплаченным.

Тестовый счёт проходит те же статусы и шлёт те же вебхуки, что и боевой, и никогда не меняет баланс. Если заказ не стал оплаченным, посмотрите в кабинете Разработчикам → Доставки webhook (какой код ответа вернула функция, там же кнопка Повторить) и логи функции в Lovable. Подробнее о тестовом режиме: Как протестировать криптоплатежи без реальных денег.

Шаг 5. Включите боевой режим

Поменяйте секрет SNAPEX_ENVIRONMENT на live. Новые счета станут боевыми, а функция вебхука начнёт пропускать тестовые события, так что тестовая оплата никогда не отметит настоящий заказ. Оплаченные счета зачисляются на ваш баланс SnapEX Pay в USDT.

Код

Так выглядят обе функции на встроенном бэкенде (Supabase Edge Functions, Deno). Набирать их не нужно: код здесь, чтобы проверить, что написал Lovable, или дать ему как образец.

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 });
});

Что здесь важно:

  • Idempotency-Key обязателен. Повтор с тем же ключом вернёт тот же счёт, а не создаст второй.
  • external_id можно использовать один раз на аккаунт — и в тестовом, и в боевом режиме. Поэтому к нему добавлен короткий случайный суффикс: когда счёт истёк (по умолчанию через 30 минут, expires_in задаёт от 60 секунд до 24 часов), следующее нажатие создаст новый счёт для того же заказа.
  • Ответ — {"data": {...}} с invoice_id, pay_url, status, expires_at, environment, amount_usd и вашим external_id.
  • Цену можно указать и в другой валюте: вместо amount_usd отправьте price_amount и price_currency (например, "EUR"), SnapEX Pay пересчитает. fee_on: "customer" перекладывает комиссию на клиента, см. Кто платит комиссию за криптоплатёж.

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 вызывает эту функцию без сессии пользователя, поэтому бэкенд не должен требовать для неё токен пользователя. В Supabase это задаётся для каждой функции в supabase/config.toml:

[functions.snapex-webhook]
verify_jwt = false

Проверка подписи здесь заменяет проверку входа: только она делает запрос достоверным. Что приходит:

Заголовок Значение
Webhook-Id Уникальный id события; при повторах тот же.
Webhook-Timestamp Unix-время этой попытки в секундах; у каждого повтора новое.
Webhook-Signature v1= + HMAC-SHA256 в нижнем регистре hex от {Webhook-Timestamp}.{сырое тело}.

Тело — {"id", "type", "created_at", "data"}; у событий invoice.* в data — счёт в том же виде, что отдаёт API: invoice_id, status, environment, amount_usd, paid_at и ваш external_id.

Что полезно знать о доставке: успех — любой 2xx; таймауты — 5 секунд на соединение и 15 секунд на весь запрос; неудачный invoice.paid повторяется, всего до 5 попыток (примерно через 10 с, 1 мин, 5 мин и 15 мин). Одно и то же событие может прийти дважды, поэтому обновление выше меняет только ещё не оплаченный заказ. «Отгружайте заказ» означает только invoice.paid: invoice.partially_paid — клиент оплатил часть, и окно доплаты закончилось. Подробнее: Вебхуки криптоплатежей: подпись, повторы и дубли.

Кнопка оплаты

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>
  );
}

Кнопка отправляет только id заказа. После оплаты клиент возвращается на success_url; страница заказа должна брать статус из базы, потому что заказ оплаченным отмечает вебхук, а не возврат на ваш сайт.

Новые приложения Lovable

Приложения Lovable, созданные с 13 мая 2026 года, построены на TanStack Start и обычно выполняют серверный код внутри самого приложения — как server functions и API routes, а не Edge Functions. Схема та же: ключ — в секрете, счёт создаётся на сервере, вебхук приходит на публичный маршрут, который читает сырое тело и первым делом проверяет подпись. Промпт выше не называет технологию, поэтому Lovable выберет подходящую для вашего приложения. Адрес для вебхука тогда — адрес приложения плюс путь маршрута; спросите его у Lovable. Серверные маршруты обновляются при публикации: опубликуйте приложение, прежде чем проверять вебхук.

Можно ли вместо этого подключить MCP-сервер SnapEX Pay?

Только как помощника на время разработки. У SnapEX Pay есть MCP-сервер https://pay.snapex.pro/mcp, и Lovable умеет добавить его как свой MCP-сервер (Connectors → Add custom → MCP server, аутентификация Bearer token or API key с вашим ключом smk_). Тогда чат Lovable во время сборки сможет посмотреть монеты, курсы и комиссии или проверить тестовый счёт. Но подключения чата никогда не входят в опубликованное приложение, так что для самой оплаты всё равно нужны две функции выше. Про MCP: pay.snapex.pro/mcp.

Чек-лист

  • SNAPEX_API_KEY и SNAPEX_WEBHOOK_SECRET — только в секретах бэкенда; ничего не начинается с VITE_.
  • Цена читается на сервере; браузер отправляет только id заказа.
  • Функция вебхука читает сырое тело, сравнивает подпись за постоянное время, проверяет метку времени и отвечает 400, если что-то не сходится.
  • Заказ становится оплаченным только по invoice.paid и только один раз.
  • Тест и боевой режим разделены секретом SNAPEX_ENVIRONMENT.

Полный справочник API: документация SnapEX Pay API.

Другие гайды

Готовы принимать криптовалюту?

Создайте аккаунт мерчанта и получите API-ключ. 1% с платежа, без абонентской платы.

Розыгрыш $200

Случайному участнику.

До конца 2дн 13ч 25мин 16сек Подписаться @snapex_pay