تدفقات الدفع

توفر حزمة @solana-commerce/headless وظائف مستقلة عن إطار العمل لبناء تدفقات الدفع التجارية. تساعد هذه الأدوات في إنشاء كائنات طلب الدفع، وتوليد روابط Solana Pay، والتحقق من المدفوعات على السلسلة. الحزمة مصممة للعمل في أي بيئة JavaScript: React أو Vue أو Svelte أو JavaScript الأساسي أو Node.js أو الوظائف بدون خادم.

التثبيت

pnpm add @solana-commerce/headless

وظائف طلب الدفع

تُنشئ هذه الوظائف كائنات طلب دفع موحدة لأنماط تجارية مختلفة. لا تقوم بإجراء أي عمليات على البلوكشين—إنها تقوم ببساطة بتنظيم البيانات للاستخدام في المحافظ أو روابط Solana Pay أو واجهات دفع مخصصة.

createBuyNowRequest()

تُنشئ طلب دفع موحدًا لشراء منتج واحد.

function createBuyNowRequest(
  recipient: string,
  product: any,
  options?: {
    memo?: string;
    label?: string;
    message?: string;
  }
): PaymentRequest;

المعاملات

• recipient (string، مطلوب) - عنوان محفظة التاجر (مفتاح عام لـ سولانا مشفر بصيغة base58) الذي سيستلم الدفع.

• product (any، مطلوب) - كائن المنتج الذي يحتوي على:

  • price (رقم، مطلوب) - سعر المنتج. تعتمد الوحدة على السياق (مثل lamport لـ SOL، وحدات صغيرة للرموز المميزة).
  • currency (نص، مطلوب) - عملة الدفع. يمكن أن يكون 'SOL' أو عنوان إصدار رمز مميز.
  • name (نص، مطلوب) - اسم المنتج، يُستخدم كمذكرة/تسمية افتراضية إذا لم يتم تقديمه.
  • يتم تمرير الحقول الإضافية (المعرف، الوصف، الصورة، إلخ) في مصفوفة products.

• options (كائن، اختياري) - خيارات التخصيص:

  • memo (نص) - مذكرة على السلسلة للمعاملة. افتراضي: "Purchase: {product.name}".
  • label (نص) - تسمية العرض لطلب الدفع (تُستخدم في Solana Pay). افتراضي: product.name.
  • message (نص) - رسالة النجاح المعروضة بعد الدفع. افتراضي: "Thank you for purchasing {product.name}!".

القيمة المُرجعة

كائن PaymentRequest يحتوي على:

• recipient - عنوان محفظة التاجر
• amount - سعر المنتج (منسوخ من product.price)
• currency - عملة الدفع (منسوخة من product.currency)
• products - مصفوفة تحتوي على المنتج الواحد
• memo - مذكرة المعاملة (خيار أو افتراضي: "شراء: (product.name)")
• label - تسمية الدفع (خيار أو افتراضي: "product.name")
• message - رسالة النجاح (خيار أو افتراضي: "شكرًا لشرائك (product.name)!")

مثال:

const payment = createBuyNowRequest(
  "merchant-wallet-address",
  {
    id: "prod_123",
    name: "Premium Subscription",
    price: 50000000, // 0.05 SOL in lamports
    currency: "SOL"
  },
  {
    label: "Premium Subscription",
    message: "Thank you for subscribing!"
  }
);

createCartRequest()

ينشئ طلب دفع لمنتجات متعددة في سلة التسوق.

function createCartRequest(
  recipient: string,
  products: any[],
  options?: {
    memo?: string;
    label?: string;
    message?: string;
    currency?: string;
  }
): PaymentRequest;

المعاملات

• recipient (string، مطلوب) - عنوان محفظة التاجر الذي سيستلم الدفع.

• products (any[]، مطلوب) - مصفوفة من كائنات المنتجات.

• options (كائن، اختياري) - خيارات التخصيص:

  • currency (نص) - عملة الدفع لسلة التسوق بالكامل.
  • memo (نص) - مذكرة على السلسلة. افتراضي: "Cart purchase (products.length items)".
  • label (نص) - تسمية الدفع. افتراضي: "Cart Checkout".
  • message (نص) - رسالة النجاح. افتراضي: "Thank you for your purchase!".

القيمة المُرجعة

كائن PaymentRequest يحتوي على:

• recipient - عنوان محفظة التاجر
• amount - مجموع أسعار جميع المنتجات (products.reduce((sum, p) => sum + p.price, 0))
• currency - عملة الدفع (من الخيارات، أو غير معرّفة)
• products - مصفوفة المنتجات
• memo، label، message - قيم الخيارات أو الافتراضيات

مثال:

const cart = createCartRequest(
  "merchant-wallet-address",
  [
    { id: "1", name: "Product A", price: 25 },
    { id: "2", name: "Product B", price: 15 },
    { id: "3", name: "Product C", price: 10 }
  ],
  {
    currency: "USDC",
    label: "My Store Checkout",
    message: "Thank you for your order!"
  }
);
// cart.amount === 50 (sum of prices)

createTipRequest()

ينشئ طلب دفع للإكراميات أو التبرعات بمبلغ يحدده المستخدم.

function createTipRequest(
  recipient: string,
  amount: number,
  options?: {
    currency?: string;
    memo?: string;
    label?: string;
    message?: string;
  }
): PaymentRequest;

المعاملات

• recipient (string، مطلوب) - عنوان محفظة مستلم الإكرامية (منشئ المحتوى، مذيع البث المباشر، مؤسسة خيرية، إلخ).

• amount (number، مطلوب) - مبلغ الإكرامية. الوحدة تعتمد على العملة (lamport لـ SOL، وحدات فرعية للرموز المميزة).

• options (كائن، اختياري) - خيارات التخصيص:

  • currency (نص) - عملة الدفع. افتراضي: غير معرّفة (عادةً تُعامل على أنها SOL من قبل المستهلكين).
  • memo (نص) - مذكرة على السلسلة. افتراضي: "Thank you for your support!".
  • label (نص) - تسمية الدفع. افتراضي: "Tip".
  • message (نص) - رسالة النجاح. افتراضي: "Thanks for the tip!".

القيمة المُرجعة

كائن PaymentRequest يحتوي على:

• recipient - عنوان محفظة مستلم الإكرامية
• amount - مبلغ الإكرامية
• currency - عملة الدفع (من الخيارات، أو غير معرّفة)
• memo، label، message - قيم الخيارات أو الافتراضيات

مثال:

const tip = createTipRequest(
  "creator-wallet-address",
  5_000_000, // 0.005 SOL in lamports
  {
    currency: "SOL",
    label: "Tip for Content Creator",
    message: "Thanks for the support!"
  }
);

دوال التحقق من الدفع

تتفاعل هذه الدوال مع سولانا للتحقق من المعاملات وانتظار التأكيدات. تتطلب عميل Solana RPC من مكتبة gill.

verifyPayment()

تتحقق من وجود معاملة على السلسلة واختيارياً تتحقق من صحة مبلغ الدفع والمستلم والرمز المميز.

async function verifyPayment(
  rpc: SolanaClient["rpc"],
  signatureString: string,
  expectedAmount?: number,
  expectedRecipient?: string,
  expectedMint?: string
): Promise<PaymentVerificationResult>;

المعاملات

• rpc (SolanaClient['rpc']، مطلوب) - عميل RPC من gill. يتم إنشاؤه باستخدام createSolanaClient(rpcUrl).rpc.

• signatureString (string، مطلوب) - توقيع المعاملة (مشفر بصيغة base58) للتحقق منه.

• expectedAmount (number، اختياري) - مبلغ الدفع المتوقع للتحقق من صحته. يجب أن تتطابق الوحدة مع العملة:

  • بالنسبة لـ SOL: lamport (1 SOL = 1,000,000,000 lamport)
  • بالنسبة لرموز SPL المميزة: وحدات صغرى بناءً على عدد الكسور العشرية للرمز (على سبيل المثال، USDC يستخدم 6 كسور عشرية)

  إذا لم يتم تقديمه، يتم تخطي التحقق من المبلغ.

• expectedRecipient (string، اختياري) - عنوان محفظة المستلم المتوقع. إذا تم تقديمه (مع expectedAmount)، تتحقق الدالة من أن المستلم قد استلم هذا المبلغ على الأقل. إذا لم يتم تقديمه، يتم تخطي التحقق.

• expectedMint (string، اختياري) - عنوان إصدار رمز SPL المميز. مطلوب فقط لتحويلات رموز SPL المميزة. إذا لم يتم تقديمه، تفترض الدالة تحويل SOL.

القيمة المُرجَعة

كائن Promise<PaymentVerificationResult>:

interface PaymentVerificationResult {
  verified: boolean; // True if payment is valid
  signature?: string; // Transaction signature (echoed back)
  amount?: number; // Expected amount (echoed back)
  recipient?: string; // Expected recipient (echoed back)
  error?: string; // Error message if verification failed
}

منطق التحقق

تقوم الدالة بإجراء هذه الفحوصات:

1. صحة التوقيع: تتحقق من أن التوقيع صالح.

2. وجود المعاملة: تجلب المعاملة باستخدام rpc.getTransaction(). إذا لم يتم العثور عليها، تُرجع verified: false.

3. حالة التأكيد: تتحقق من أن المعاملة قد استقرت على السلسلة.

4. التحقق من تحويل SOL (إذا تم تقديم expectedRecipient و expectedAmount، وليس expectedMint):

   • تجد فهرس حساب المستلم في المعاملة
   • تقارن preBalances و postBalances لحساب فرق الرصيد
   • تتحقق من أن الفرق يساوي expectedAmount على الأقل

5. التحقق من تحويل رمز SPL (إذا تم توفير expectedMint):

   • يستخرج حساب الرمز المرتبط (ATA) للمستلم لكل من برنامج الرموز وبرنامج الرموز-2022
   • يتحقق من postTokenBalances للعثور على ATA مطابق مع عملية السك المتوقعة
   • يتحقق من أن مبلغ الرمز لا يقل عن expectedAmount

اعتبارات الأمان

• التحقق من جانب العميل: تقوم هذه الدالة بجلب بيانات المعاملة من RPC. لا تعرض عنوان URL الخاص بـ RPC للعميل.
• الإنهاء: تتحقق الدالة من المعاملات المؤكدة، ولكن بالنسبة للمدفوعات عالية القيمة، فكر في انتظار حالة finalized.

مثال:

import { verifyPayment } from "@solana-commerce/headless";
import { createSolanaClient } from "gill";

const client = createSolanaClient({
  urlOrMoniker: "mainnet"
});

const result = await verifyPayment(
  client.rpc,
  "transaction-signature-here",
  50_000_000, // 0.05 SOL in lamports
  "merchant-wallet-address"
  // No mint = SOL transfer
);

if (result.verified) {
  console.log("Payment confirmed!");
} else {
  console.error("Verification failed:", result.error);
}

waitForConfirmation()

يستعلم عن سلسلة الكتل حتى تصل المعاملة إلى حالة مؤكدة أو نهائية، أو حتى انتهاء المهلة الزمنية.

async function waitForConfirmation(
  rpc: SolanaClient["rpc"],
  signatureStr: string,
  timeoutMs?: number
): Promise<boolean>;

المعاملات

• rpc (SolanaClient['rpc']، مطلوب) - عميل RPC من gill.

• signatureStr (string، مطلوب) - توقيع المعاملة المراد انتظارها.

• timeoutMs (number، اختياري) - أقصى وقت للانتظار بالميلي ثانية. القيمة الافتراضية: 30000 (30 ثانية).

القيمة المُرجعة

• Promise<boolean> - ترجع true إذا وصلت المعاملة إلى حالة confirmed أو finalized خلال المهلة الزمنية، وإلا ترجع false.

مثال:

import { waitForConfirmation } from "@solana-commerce/headless";
import { createSolanaClient } from "gill";

const client = createSolanaClient({
  urlOrMoniker: "mainnet"
});

// After sending transaction
const signature = await wallet.sendTransaction(transaction);

// Wait for confirmation (30 second timeout)
const confirmed = await waitForConfirmation(client.rpc, signature, 30000);

if (confirmed) {
  console.log("Transaction confirmed!");
} else {
  console.log("Timeout - transaction not confirmed within 30 seconds");
}

دوال Solana Pay

تُنشئ هذه الدوال عناوين URL لـ Solana Pay ورموز QR منسقة لمسحها بواسطة المحافظ المحمولة.

createSolanaPayRequest()

تُنشئ عنوان URL لـ Solana Pay ورمز QR منسق.

async function createSolanaPayRequest(
  request: TransferRequestURLFields,
  options: SolanaPayRequestOptions
): Promise<{ url: URL; qr: string }>;

المعاملات

• request (TransferRequestURLFields، مطلوب) - حقول طلب تحويل Solana Pay:

  • recipient - المفتاح العام للمستلم (استخدم createRecipient(address) من @solana-commerce/solana-pay)
  • amount - (اختياري) مبلغ الدفع بالوحدات الصغرى (lamport لـ SOL)
  • splToken (اختياري) - المفتاح العام لسك رمز SPL (استخدم createSPLToken(address))
  • reference (اختياري) - المفتاح العام المرجعي للتتبع
  • label (اختياري) - اسم التاجر
  • message (اختياري) - رسالة النجاح
  • memo (اختياري) - مذكرة على السلسلة

• options (SolanaPayRequestOptions، مطلوب) - خيارات تنسيق رمز الاستجابة السريعة (QR):

  • size (رقم) - عرض/ارتفاع رمز الاستجابة السريعة بالبكسل. الافتراضي: 256.
  • background (نص) - لون الخلفية (hex/rgb). الافتراضي: 'white'.
  • color (نص) - لون رمز الاستجابة السريعة (hex/rgb). الافتراضي: 'black'.
  • margin (رقم) - الهامش حول رمز الاستجابة السريعة بالوحدات.
  • errorCorrectionLevel ('L' | 'M' | 'Q' | 'H') - مستوى تصحيح الأخطاء. المستويات الأعلى تسمح بمزيد من التلف ولكنها تنشئ رموزاً أكثر كثافة.
  • logo (نص) - رابط URL لصورة الشعار لتضمينه في مركز رمز الاستجابة السريعة.
  • logoSize (رقم) - حجم الشعار كنسبة مئوية من حجم رمز الاستجابة السريعة.
  • logoBackgroundColor (نص) - لون الخلفية خلف الشعار.
  • logoMargin (رقم) - الهامش حول الشعار.
  • dotStyle ('dots' | 'rounded' | 'square') - شكل وحدات رمز الاستجابة السريعة.
  • cornerStyle ('square' | 'rounded' | 'extra-rounded' | 'full-rounded' | 'maximum-rounded') - شكل علامات الزوايا.

القيم المُرجعة

Promise يتم حله إلى كائن:

• url (URL) - رابط URL لـ سولانا Pay (مثال، solana:recipient?amount=10&spl-token=...)
• qr (نص) - رابط URL بيانات مشفر بـ Base64 لصورة رمز الاستجابة السريعة (استخدمه كـ <img src={qr} />)

مثال:

import {
  createSolanaPayRequest,
  createRecipient,
  createSPLToken
} from "@solana-commerce/solana-pay";

const payment = await createSolanaPayRequest(
  {
    recipient: createRecipient("merchant-wallet-address"),
    amount: 10_000_000, // 0.01 SOL in lamports
    splToken: createSPLToken("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"), // USDC
    label: "My Store",
    message: "Thank you for your purchase!"
  },
  {
    size: 400,
    background: "#FFFFFF",
    color: "#000000",
    logo: "/logo.png",
    logoSize: 20,
    errorCorrectionLevel: "H"
  }
);

// Display QR code
document.getElementById("qr").src = payment.qr;
console.log(payment.url.toString()); // solana:merchant...?amount=10000000&spl-token=...