أقسام الصفحة
AR

كيف تقبل مدفوعات العملات المشفرة في تطبيق Lovable عبر SnapEX Pay

مدفوعات العملات المشفرة في تطبيق Lovable عبر SnapEX Pay

يبني Lovable تطبيق ويب يعمل انطلاقًا من محادثة. إذا كان تطبيقك يبيع شيئًا، فيمكنك قبول الدفع بالعملات المشفرة عبر SnapEX Pay: يضغط العميل زرًّا، ويدفع في صفحة SnapEX Pay بـ USDT أو بأكثر من 70 عملة أخرى، ويعرف تطبيقك بالدفع من Webhook موقَّع. يشرح هذا الدليل الطريقة الآمنة للربط، مع موجّه (prompt) تلصقه في Lovable والشيفرة التي يجب أن ينتهي إليها.

كيف يعمل

مسار الدفع: تطبيق Lovable ← دالة create-invoice ← SnapEX Pay ← Webhook ← جدول الطلبات

  1. يضغط العميل زر Pay with crypto في تطبيقك.
  2. تقرأ دالة على الخادم (create-invoice) الطلب من قاعدة بياناتك وتنشئ فاتورة عبر POST /api/v1/merchant/invoices. يُقرأ مفتاح API من سرّ على الخادم.
  3. تعيد الدالة pay_url، فيفتح المتصفح صفحة الدفع في SnapEX Pay.
  4. عند دفع الفاتورة يرسل SnapEX Pay إشعار Webhook موقَّعًا 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. اربط Webhook

  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.

يستقبل Webhook المضبوط في اللوحة كل أنواع الأحداث؛ والدالة لا تتفاعل إلا مع 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. تعرض صفحة الدفع شارة تجريبي.
  2. اختر أي عملة. لا حاجة إلى إرسال أي شيء: بعد نحو 10 ثوانٍ تصبح الفاتورة مدفوعة تلقائيًا.
  3. يصل Webhook مع data.environment = "test"، ويصبح الطلب مدفوعًا في تطبيقك.

تمر الفاتورة التجريبية بالحالات نفسها وترسل إشعارات Webhook نفسها التي ترسلها الفاتورة الحقيقية، ولا تغيّر رصيدك أبدًا. إن لم يصبح الطلب مدفوعًا فانظر في اللوحة إلى للمطورين ← عمليات تسليم Webhook (رمز الاستجابة الذي أعادته دالتك، وزر إعادة الإرسال) وإلى سجلات الدالة في Lovable. المزيد عن الوضع التجريبي: كيف تختبر مدفوعات العملات المشفرة بدون أموال حقيقية.

الخطوة 5. انتقل إلى الوضع الحقيقي

غيّر السرّ SNAPEX_ENVIRONMENT إلى live. تصبح الفواتير الجديدة حقيقية، وتتجاهل دالة Webhook الأحداث التجريبية، فلا يمكن لدفعة تجريبية أن تضع علامة «مدفوع» على طلب حقيقي. تُضاف الفواتير المدفوعة إلى رصيدك في 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 الخاص بك.
  • يمكن التسعير بعملة أخرى أيضًا: أرسل price_amount وprice_currency (مثل "EUR") بدل amount_usd، ويحوّلها SnapEX Pay. ومع fee_on: "customer" يدفع العميل الرسوم فوق السعر؛ راجع Who pays the crypto payment fee (بالإنجليزية).

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 وقت Unix بالثواني لهذه المحاولة؛ جديد في كل إعادة محاولة.
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⁩ تُعد نجاحًا؛ المهلة 5 ثوانٍ للاتصال و15 ثانية للطلب كاملًا؛ ويُعاد إرسال invoice.paid الفاشل حتى 5 محاولات إجمالًا (بعد نحو 10 ثوانٍ ثم دقيقة ثم 5 دقائق ثم 15 دقيقة). قد يصل الحدث نفسه مرتين، ولهذا لا يغيّر التحديث أعلاه إلا طلبًا لم يُدفع بعد. وحده invoice.paid يعني «سلِّم الطلب»: أما invoice.partially_paid فيعني أن العميل دفع جزءًا وانتهت مهلة الإكمال. المزيد: إشعارات Webhook لمدفوعات العملات المشفرة: التوقيع وإعادة المحاولة والتكرار.

زر الدفع

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؛ ويجب أن تقرأ صفحة الطلب الحالة من قاعدة البيانات، لأن ما يجعل الطلب مدفوعًا هو Webhook وليس عودة العميل إلى موقعك.

تطبيقات Lovable الأحدث

تطبيقات Lovable المنشأة منذ 13 مايو 2026 مبنية على TanStack Start، وغالبًا ما تشغّل شيفرة الخادم داخل التطبيق نفسه على شكل server functions وAPI routes بدل Edge Functions. الخطة لا تتغير: المفتاح سرّ، والفاتورة تُنشأ على الخادم، وWebhook يصل إلى مسار عام يقرأ الجسم الخام ويتحقق من التوقيع قبل أي شيء. الموجّه أعلاه لا يذكر تقنية بعينها، فيختار Lovable المناسب لتطبيقك. يصبح عنوان Webhook عندها رابط تطبيقك مضافًا إليه مسار route؛ اسأل Lovable عنه. تتغير مسارات الخادم عند النشر: انشر التطبيق قبل اختبار Webhook.

هل يمكنني استخدام خادم 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_.
  • يُقرأ السعر على الخادم؛ والمتصفح يرسل معرّف الطلب فقط.
  • تقرأ دالة Webhook الجسم الخام، وتقارن التوقيع في زمن ثابت، وتتحقق من الطابع الزمني، وتردّ بـ 400 عند عدم التطابق.
  • يصبح الطلب مدفوعًا فقط مع invoice.paid ومرة واحدة فقط.
  • الوضع التجريبي والحقيقي منفصلان بواسطة SNAPEX_ENVIRONMENT.

المرجع الكامل لـ API: توثيق SnapEX Pay API.

أدلة أخرى

جاهز لقبول العملات المشفرة؟

أنشئ حساب تاجر واحصل على مفتاح API. عمولة ⁦1%⁩ على كل دفعة، بلا رسوم شهرية.

سحب على $200

لمشترك عشوائي.

ينتهي خلال 2يوم 13ساعة 13دقيقة 32ثانية اشترك @snapex_pay