Sayfa bölümleri
TR

SnapEX Pay ile Lovable uygulamasında kripto ödeme nasıl alınır

SnapEX Pay ile Lovable uygulamasında kripto ödemeler

Lovable bir sohbetten çalışan bir web uygulaması oluşturur. Uygulamanız bir şey satıyorsa SnapEX Pay ile kripto ödeme alabilirsiniz: müşteri bir düğmeye basar, SnapEX Pay sayfasında USDT veya 70+ başka coin ile öder, uygulamanız da ödemeyi imzalı bir webhook'tan öğrenir. Bu rehber, bunu güvenli şekilde nasıl bağlayacağınızı gösteriyor: Lovable'a yapıştırabileceğiniz bir prompt ve ortaya çıkması gereken kod.

Nasıl çalışır

Ödeme akışı: Lovable uygulaması → create-invoice fonksiyonu → SnapEX Pay → webhook → siparişler tablosu

  1. Müşteri uygulamanızda Pay with crypto düğmesine basar.
  2. Bir backend fonksiyonu (create-invoice) siparişi veritabanınızdan okur ve POST /api/v1/merchant/invoices ile fatura oluşturur. API anahtarı sunucudaki bir sırdan okunur.
  3. Fonksiyon pay_url döndürür ve tarayıcı SnapEX Pay ödeme sayfasını açar.
  4. Fatura ödendiğinde SnapEX Pay ikinci bir fonksiyona (snapex-webhook) imzalı invoice.paid webhook'u gönderir.
  5. Bu fonksiyon imzayı kontrol eder ve siparişi veritabanında ödendi olarak işaretler.

Tarayıcı API anahtarını hiç görmez; fiyatı da ödeme durumunu da o belirlemez. Bütün mesele bu: uygulamanızdaki bir fonksiyonu herkes çağırabilir, tarayıcının gönderdiği veriyi de herkes değiştirebilir; bu yüzden fiyat ve «ödendi» işareti sunucudan gelmelidir.

Adım 1. API anahtarı alın

pay.snapex.pro üzerinde hesap açın, ardından üye işyeri panelinde Geliştiriciler → API anahtarı al yolunu izleyin. Anahtar smk_ ile başlar ve yalnızca bir kez gösterilir: hemen kopyalayın. Ödeme gönderimleri dahil tüm Merchant API yetkilerine sahiptir; bu yüzden yalnızca backend sırrında durmalıdır, asla frontend kodunda, bir VITE_ değişkeninde ya da sohbette değil. Panelde anahtarı yeniden oluşturmak öncekini anında iptal eder.

Hesabı web sitesine girmeden API ile de açabilirsiniz:

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

Yanıtta api_key (bir kez gösterilir), panel için bir login ve oluşturulmuş bir password, ayrıca cabinet_url bulunur.

Adım 2. Ödeme akışını Lovable'a kurdurun

Bu prompt'u projenin sohbetine yapıştırın. İngilizcedir; Lovable her projede anlar. Lovable SNAPEX_API_KEY istediğinde anahtarı sohbete değil, güvenli sır formuna girin. SNAPEX_WEBHOOK_SECRET için şimdilik Skip deyin: onu 3. adımda alacaksınız.

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 prompt'u çalışan koda dönüştürür; kodu açıp aşağıdaki referans kodla karşılaştırabilirsiniz.

Adım 3. Webhook'u bağlayın

  1. snapex-webhook fonksiyonunun adresini kopyalayın. Yerleşik backend kullanan bir uygulamada: More → Database → Manage → Edge functions, fonksiyonu açın ve Copy URL'ye basın. Bulamazsanız sohbette Lovable'dan fonksiyonun herkese açık URL'sini isteyin.
  2. SnapEX Pay panelinde Geliştiriciler → Webhook bölümünü açın, URL'yi yapıştırın ve Kaydet'e basın. URL herkese açık bir https:// adresi olmalıdır.
  3. İlk kayıtta panel imzalama sırrını whsec_… yalnızca bir kez gösterir. Bunu Lovable'da More → Settings → Secrets → Add secret altında SNAPEX_WEBHOOK_SECRET adıyla ekleyin.

Paneldeki webhook tüm olay türlerini alır; fonksiyon yalnızca invoice.paid'e tepki verir, diğerlerine 200 döner. API'yi tercih ederseniz POST /api/v1/merchant/webhooks ve {"url": "…", "events": ["invoice.paid"]} listelediğiniz olaylar için bir uç nokta oluşturur (invoice.paid ile birlikte invoice.partially_paid de gelir) ve secret'ı bir kez döndürür.

Adım 4. Gerçek para olmadan test edin

SNAPEX_ENVIRONMENT değeri test olduğu sürece tüm faturalar test faturasıdır:

  1. Uygulamada bir sipariş oluşturun ve Pay with crypto'ya basın. Ödeme sayfasında Test etiketi görünür.
  2. Herhangi bir coin seçin. Hiçbir şey göndermeniz gerekmez: yaklaşık 10 saniye sonra fatura kendiliğinden ödenmiş olur.
  3. Webhook data.environment = "test" ile gelir ve sipariş uygulamanızda ödendi olur.

Test faturası canlı faturayla aynı durumlardan geçer ve aynı webhook'ları gönderir; bakiyenizi asla değiştirmez. Sipariş ödendi olmazsa panelde Geliştiriciler → Webhook gönderimleri bölümüne (fonksiyonunuzun döndürdüğü yanıt kodu ve Yeniden gönder düğmesi) ve Lovable'daki fonksiyon loglarına bakın. Test modu hakkında daha fazlası: Kripto ödemeleri gerçek para olmadan nasıl test edilir.

Adım 5. Canlıya geçin

SNAPEX_ENVIRONMENT sırrını live yapın. Yeni faturalar canlı olur ve webhook fonksiyonu artık test olaylarını yok sayar; böylece bir test ödemesi gerçek bir siparişi asla ödendi olarak işaretleyemez. Ödenen faturalar SnapEX Pay bakiyenize USDT olarak yatırılır.

Kod

İki fonksiyon yerleşik backend'de (Supabase Edge Functions, Deno) böyle görünür. Yazmanıza gerek yok: Lovable'ın yazdığını kontrol etmeniz ya da ona referans olarak vermeniz için burada.

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

Önemli noktalar:

  • Idempotency-Key zorunludur. Aynı anahtarla yapılan tekrar, ikinci bir fatura yerine aynı faturayı döndürür.
  • Her external_id hesap başına yalnızca bir kez kullanılabilir, test ve canlıda aynı şekilde. Bu yüzden kısa, rastgele bir son ek alır: fatura süresi dolduğunda (varsayılan 30 dakika; expires_in 60 saniye ile 24 saat arası ayarlanabilir) sonraki tıklama aynı sipariş için yeni bir fatura oluşturur.
  • Yanıt, invoice_id, pay_url, status, expires_at, environment, amount_usd ve sizin external_id değerinizi içeren {"data": {...}} biçimindedir.
  • Başka bir para biriminde fiyat da olur: amount_usd yerine price_amount ve price_currency (örneğin "EUR") gönderin, SnapEX Pay çevirir. fee_on: "customer" ile komisyonu müşteri fiyatın üstüne öder; bkz. Who pays the crypto payment fee (İngilizce).

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 bu fonksiyonu kullanıcı oturumu olmadan çağırır; bu yüzden backend bunun için kullanıcı token'ı istememelidir. Supabase'te bu, supabase/config.toml içinde fonksiyon bazında ayarlanır:

[functions.snapex-webhook]
verify_jwt = false

Burada imza kontrolü giriş kontrolünün yerini alır: isteği güvenilir kılan tek şey odur. Gelenler:

Başlık Anlamı
Webhook-Id Olayın benzersiz kimliği; her tekrarda aynıdır.
Webhook-Timestamp Bu denemenin saniye cinsinden Unix zamanı; her tekrarda yenidir.
Webhook-Signature v1= + {Webhook-Timestamp}.{ham gövde} üzerinden HMAC-SHA256'nın küçük harfli hex değeri.

Gövde {"id", "type", "created_at", "data"} biçimindedir; invoice.* olaylarında data, API'nin döndürdüğü biçimdeki faturadır: invoice_id, status, environment, amount_usd, paid_at ve sizin external_id değeriniz.

Teslimat hakkında bilinmesi gerekenler: herhangi bir 2xx başarıdır; zaman aşımları bağlantı için 5, toplamda 15 saniyedir; başarısız bir invoice.paid tekrar gönderilir, toplamda en fazla 5 deneme (yaklaşık 10 sn, 1 dk, 5 dk ve 15 dk sonra). Aynı olay iki kez gelebilir; bu yüzden yukarıdaki güncelleme yalnızca henüz ödenmemiş bir siparişi değiştirir. «Siparişi gönderin» anlamına gelen tek olay invoice.paid'dir: invoice.partially_paid, müşterinin bir kısmını ödediği ve tamamlama süresinin bittiği anlamına gelir. Daha fazlası: Kripto ödeme webhook'ları: imza, yeniden denemeler ve tekrarlar.

Ödeme düğmesi

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

Düğme yalnızca sipariş kimliğini gönderir. Ödemeden sonra müşteri success_url'ye döner; sipariş sayfası durumu veritabanından okumalıdır, çünkü siparişi ödendi yapan sitenize dönüş değil, webhook'tur.

Yeni Lovable uygulamaları

13 Mayıs 2026'dan itibaren oluşturulan Lovable uygulamaları TanStack Start üzerine kuruludur ve sunucu kodunu genellikle Edge Functions yerine uygulamanın içinde, server functions ve API routes olarak çalıştırır. Plan aynı kalır: anahtar bir sırdır, fatura sunucuda oluşturulur ve webhook, ham gövdeyi okuyup her şeyden önce imzayı kontrol eden herkese açık bir route'a gelir. Yukarıdaki prompt bir teknoloji belirtmez, bu yüzden Lovable uygulamanıza uygun olanı seçer. Webhook adresi bu durumda uygulamanızın URL'si artı route yoludur; Lovable'a sorun. Sunucu route'ları yayınlayınca değişir: webhook'u test etmeden önce uygulamayı yayınlayın.

Bunun yerine SnapEX Pay MCP sunucusunu kullanabilir miyim?

Yalnızca geliştirirken yardımcı olarak. SnapEX Pay'in https://pay.snapex.pro/mcp adresinde bir MCP sunucusu var ve Lovable bunu özel MCP sunucusu olarak ekleyebilir (Connectors → Add custom → MCP server, kimlik doğrulama Bearer token or API key, smk_ anahtarınızla). Böylece Lovable sohbeti uygulamanızı kurarken coinlere, kurlara ve komisyonlara bakabilir ya da bir test faturasını kontrol edebilir. Ancak sohbet bağlantıları yayınlanan uygulamanın parçası olmaz; ödemenin kendisi için yine yukarıdaki iki fonksiyon gerekir. MCP ayrıntıları: pay.snapex.pro/mcp.

Kontrol listesi

  • SNAPEX_API_KEY ve SNAPEX_WEBHOOK_SECRET yalnızca backend sırlarında; hiçbir şey VITE_ ile başlamıyor.
  • Fiyat sunucuda okunuyor; tarayıcı yalnızca sipariş kimliğini gönderiyor.
  • Webhook fonksiyonu ham gövdeyi okuyor, imzayı sabit sürede karşılaştırıyor, zaman damgasını kontrol ediyor ve uyuşmazlıkta 400 döndürüyor.
  • Sipariş yalnızca invoice.paid ile ve yalnızca bir kez ödendi oluyor.
  • Test ve canlı SNAPEX_ENVIRONMENT ile ayrılıyor.

Tam API başvurusu: SnapEX Pay API belgeleri.

Diğer rehberler

Kripto ile ödeme almaya hazır mısınız?

Üye işyeri hesabı oluşturun ve API anahtarınızı alın. Ödeme başına %1, aylık ücret yok.

$200 çekiliş

Rastgele bir üyeye.

Bitişe 2gün 13sa 25dk 17sn Abone ol @snapex_pay