بخش‌های صفحه
FA

چگونه در اپلیکیشن Lovable با SnapEX Pay پرداخت کریپتو بگیریم

پرداخت کریپتو در اپلیکیشن Lovable با SnapEX Pay

Lovable از روی یک گفتگو، یک اپلیکیشن وب کارا می‌سازد. اگر اپلیکیشن شما چیزی می‌فروشد، می‌توانید با SnapEX Pay پرداخت کریپتو بگیرید: مشتری دکمه‌ای را می‌زند، در صفحه SnapEX Pay با USDT یا بیش از ۷۰ کوین دیگر پرداخت می‌کند و اپلیکیشن شما از طریق یک وب‌هوک امضاشده از پرداخت باخبر می‌شود. این راهنما روش امن اتصال را نشان می‌دهد: پرامپتی که می‌توانید در 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 را نمی‌بیند و نه قیمت را تعیین می‌کند و نه وضعیت پرداخت را. نکته اصلی همین است: هر کسی می‌تواند تابعی از اپلیکیشن شما را صدا بزند یا آنچه مرورگر می‌فرستد را تغییر دهد؛ پس قیمت و علامت «پرداخت‌شده» باید از سرور بیایند.

مرحله ۱. کلید 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 است.

مرحله ۲. از Lovable بخواهید پرداخت را بسازد

این پرامپت را در گفتگوی پروژه بچسبانید. پرامپت انگلیسی است و Lovable در هر پروژه‌ای آن را می‌فهمد. وقتی Lovable SNAPEX_API_KEY را خواست، کلید را در فرم امن سکرت وارد کنید، نه در گفتگو. SNAPEX_WEBHOOK_SECRET را فعلاً رد کنید (Skip): آن را در مرحله ۳ می‌گیرید.

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 پرامپت را به کد کارا تبدیل می‌کند؛ می‌توانید کد را باز کنید و با کد مرجع پایین مقایسه کنید.

مرحله ۳. وب‌هوک را وصل کنید

  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"]} یک endpoint برای رویدادهای فهرست‌شده می‌سازد (همراه invoice.paid، رویداد invoice.partially_paid هم می‌آید) و secret را یک بار برمی‌گرداند.

مرحله ۴. بدون پول واقعی تست کنید

تا وقتی SNAPEX_ENVIRONMENT برابر test است، همه فاکتورها تستی‌اند:

  1. در اپلیکیشن یک سفارش بسازید و Pay with crypto را بزنید. صفحه پرداخت نشان Test دارد.
  2. هر کوینی را انتخاب کنید. لازم نیست چیزی ارسال کنید: حدود ۱۰ ثانیه بعد فاکتور خودبه‌خود پرداخت‌شده می‌شود.
  3. وب‌هوک با data.environment = "test" می‌رسد و سفارش در اپلیکیشن پرداخت‌شده می‌شود.

فاکتور تستی همان وضعیت‌ها را طی می‌کند و همان وب‌هوک‌ها را می‌فرستد که فاکتور واقعی، و هرگز موجودی شما را تغییر نمی‌دهد. اگر سفارش پرداخت‌شده نشد، در پنل توسعه‌دهندگان ← ارسال‌های وب‌هوک (کد پاسخی که تابع برگرداند، و دکمه ارسال دوباره) و لاگ‌های تابع در Lovable را ببینید. درباره حالت تست: چگونه پرداخت کریپتو را بدون پول واقعی تست کنیم.

مرحله ۵. حالت واقعی را روشن کنید

سکرت SNAPEX_ENVIRONMENT را به live تغییر دهید. فاکتورهای جدید واقعی می‌شوند و تابع وب‌هوک از این پس رویدادهای تستی را نادیده می‌گیرد؛ پس یک پرداخت تستی هرگز سفارش واقعی را پرداخت‌شده علامت نمی‌زند. فاکتورهای پرداخت‌شده به صورت USDT به موجودی SnapEX Pay شما واریز می‌شوند.

کد

دو تابع روی بک‌اند داخلی (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 در هر حساب فقط یک بار قابل استفاده است، چه در تست و چه در حالت واقعی. به همین دلیل یک پسوند تصادفی کوتاه می‌گیرد: وقتی فاکتور منقضی شد (به‌طور پیش‌فرض بعد از ۳۰ دقیقه؛ expires_in از ۶۰ ثانیه تا ۲۴ ساعت قابل تنظیم است)، کلیک بعدی برای همان سفارش فاکتور تازه می‌سازد.
  • پاسخ به شکل {"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 شناسه یکتای رویداد؛ در هر تکرار همان است.
Webhook-Timestamp زمان یونیکس (ثانیه) این تلاش؛ در هر تکرار تازه است.
Webhook-Signature v1= + مقدار hex با حروف کوچک HMAC-SHA256 روی {Webhook-Timestamp}.{بدنه خام}.

بدنه {"id", "type", "created_at", "data"} است؛ در رویدادهای invoice.* مقدار data همان فاکتور با شکلی است که API برمی‌گرداند: invoice_id، status، environment، amount_usd، paid_at و external_id شما.

درباره ارسال بهتر است بدانید: هر پاسخ 2xx موفقیت است؛ تایم‌اوت‌ها ۵ ثانیه برای اتصال و ۱۵ ثانیه برای کل درخواست‌اند؛ invoice.paid ناموفق دوباره ارسال می‌شود، در مجموع تا ۵ تلاش (حدود ۱۰ ثانیه، ۱ دقیقه، ۵ دقیقه و ۱۵ دقیقه بعد). یک رویداد ممکن است دو بار برسد، به همین دلیل به‌روزرسانی بالا فقط سفارشی را تغییر می‌دهد که هنوز پرداخت نشده. فقط 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>
  );
}

دکمه فقط شناسه سفارش را می‌فرستد. پس از پرداخت، مشتری به success_url برمی‌گردد؛ صفحه سفارش باید وضعیت را از پایگاه داده بخواند، چون آنچه سفارش را پرداخت‌شده می‌کند وب‌هوک است، نه بازگشت به سایت شما.

اپلیکیشن‌های جدیدتر Lovable

اپلیکیشن‌های Lovable که از ۱۳ مه ۲۰۲۶ ساخته شده‌اند بر پایه TanStack Start هستند و معمولاً کد سرور را به‌جای Edge Functions داخل خود اپلیکیشن، به شکل server functions و API routes اجرا می‌کنند. طرح کلی همان است: کلید یک سکرت است، فاکتور روی سرور ساخته می‌شود و وب‌هوک به یک مسیر عمومی می‌رسد که بدنه خام را می‌خواند و پیش از هر کاری امضا را بررسی می‌کند. پرامپت بالا فناوری خاصی را نام نمی‌برد، پس Lovable گزینه مناسب اپلیکیشن شما را انتخاب می‌کند. آدرس وب‌هوک در این حالت آدرس اپلیکیشن به‌علاوه مسیر route است؛ آن را از 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_ شروع نمی‌شود.
  • قیمت روی سرور خوانده می‌شود؛ مرورگر فقط شناسه سفارش را می‌فرستد.
  • تابع وب‌هوک بدنه خام را می‌خواند، امضا را در زمان ثابت مقایسه می‌کند، زمان را بررسی می‌کند و در صورت عدم تطابق 400 برمی‌گرداند.
  • سفارش فقط با invoice.paid و فقط یک بار پرداخت‌شده می‌شود.
  • تست و حالت واقعی با SNAPEX_ENVIRONMENT از هم جدا هستند.

مرجع کامل API: مستندات API SnapEX Pay.

راهنماهای بیشتر

آماده دریافت کریپتو هستید؟

حساب فروشنده بسازید و کلید API بگیرید. 1٪ برای هر پرداخت، بدون هزینه ماهانه.

قرعه‌کشی $200

برای یک عضو تصادفی.

تا پایان 2روز 13ساعت 25دقیقه 20ثانیه عضویت @snapex_pay