Ödeme Akışları

@solana-commerce/headless paketi, ticari ödeme akışları oluşturmak için framework-bağımsız fonksiyonlar sağlar. Bu araçlar ödeme isteği nesneleri oluşturmaya, Solana Pay URL'leri üretmeye ve zincir üzerindeki ödemeleri doğrulamaya yardımcı olur. Paket, herhangi bir JavaScript ortamında çalışacak şekilde tasarlanmıştır: React, Vue, Svelte, vanilla JS, Node.js veya serverless fonksiyonlar.

Kurulum

pnpm add @solana-commerce/headless

Ödeme İsteği Fonksiyonları

Bu fonksiyonlar, farklı ticaret kalıpları için standartlaştırılmış ödeme isteği nesneleri oluşturur. Herhangi bir blockchain işlemi gerçekleştirmezler—sadece cüzdanlarda, Solana Pay URL'lerinde veya özel ödeme arayüzlerinde kullanılmak üzere veriyi yapılandırırlar.

`createBuyNowRequest()`

Tek bir ürün satın alımı için standartlaştırılmış bir ödeme isteği oluşturur.

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

Parametreler

recipient (string, zorunlu) - Ödemeyi alacak satıcı cüzdan adresi (base58 kodlu Solana public key).
product (any, zorunlu) - Şunları içeren ürün nesnesi:
- price (sayı, zorunlu) - Ürün fiyatı. Birim bağlama göre değişir (örneğin, SOL için lamport, token'lar için küçük birimler).
- currency (string, zorunlu) - Ödeme para birimi. SOL veya bir token mint adresi olabilir.
- name (string, zorunlu) - Ürün adı, sağlanmadıysa varsayılan memo/etiket için kullanılır.
- Ek alanlar (id, description, image, vb.) products dizisinde aktarılır.
options (nesne, opsiyonel) - Özelleştirme seçenekleri:
- memo (string) - İşlem için zincir üzerinde not. Varsayılan: "Purchase: {product.name}".
- label (string) - Ödeme isteği için görüntüleme etiketi (Solana Pay'de kullanılır). Varsayılan: product.name.
- message (string) - Ödemeden sonra gösterilen başarı mesajı. Varsayılan: "Thank you for purchasing {product.name}!".

Dönüş Değeri

Şunları içeren bir PaymentRequest nesnesi:

recipient - Satıcı cüzdan adresi
amount - Ürün fiyatı (product.price'den kopyalanır)
currency - Ödeme para birimi (product.currency'den kopyalanır)
products - Tek ürünü içeren dizi
memo - İşlem notu (seçenek veya varsayılan: "Satın alma: (product.name)")
label - Ödeme etiketi (seçenek veya varsayılan: "product.name")
message - Başarı mesajı (seçenek veya varsayılan: "(product.name) satın aldığınız için teşekkür ederiz!")

Örnek:

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()`

Alışveriş sepetindeki birden fazla ürün için ödeme talebi oluşturur.

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

Parametreler

recipient (string, zorunlu) - Ödemeyi alacak tüccar cüzdan adresi.
products (any[], zorunlu) - Ürün nesneleri dizisi.
options (nesne, isteğe bağlı) - Özelleştirme seçenekleri:
- currency (string) - Tüm sepet için ödeme para birimi.
- memo (string) - Zincir üstü not. Varsayılan: "Cart purchase (products.length items)".
- label (string) - Ödeme etiketi. Varsayılan: "Cart Checkout".
- message (string) - Başarı mesajı. Varsayılan: "Thank you for your purchase!".

Döndürülen Değer

Aşağıdakileri içeren bir PaymentRequest nesnesi:

recipient - Tüccar cüzdan adresi
amount - Tüm ürün fiyatlarının toplamı (products.reduce((sum, p) => sum + p.price, 0))
currency - Ödeme para birimi (seçeneklerden veya tanımsız)
products - Ürünler dizisi
memo, label, message - Seçenek değerleri veya varsayılanlar

Örnek:

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()`

Kullanıcı tanımlı tutarla bahşiş veya bağış için ödeme talebi oluşturur.

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

Parametreler

recipient (string, zorunlu) - Bahşiş alıcısının cüzdan adresi (içerik üretici, yayıncı, hayır kurumu vb.).
amount (number, zorunlu) - Bahşiş tutarı. Birim para birimine bağlıdır (SOL için lamport, tokenlar için küçük birimler).
options (nesne, isteğe bağlı) - Özelleştirme seçenekleri:
- currency (string) - Ödeme para birimi. Varsayılan: tanımsız (tüketiciler tarafından genellikle SOL olarak işlenir).
- memo (string) - Zincir üstü not. Varsayılan: "Thank you for your support!".
- label (string) - Ödeme etiketi. Varsayılan: "Tip".
- message (string) - Başarı mesajı. Varsayılan: "Thanks for the tip!".

Döndürülen Değer

Aşağıdakileri içeren bir PaymentRequest nesnesi:

recipient - Bahşiş alıcısının cüzdan adresi
amount - Bahşiş tutarı
currency - Ödeme para birimi (seçeneklerden veya tanımsız)
memo, label, message - Seçenek değerleri veya varsayılanlar

Örnek:

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

Ödeme Doğrulama Fonksiyonları

Bu fonksiyonlar, işlemleri doğrulamak ve onayları beklemek için Solana ile etkileşime girer. gill kütüphanesinden bir Solana RPC istemcisi gerektirir.

`verifyPayment()`

Bir işlemin zincir üzerinde var olduğunu doğrular ve isteğe bağlı olarak ödeme tutarını, alıcıyı ve token'ı doğrular.

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

Parametreler

rpc (SolanaClient['rpc'], zorunlu) - gill'den RPC istemcisi. createSolanaClient(rpcUrl).rpc ile oluşturun.
signatureString (string, zorunlu) - Doğrulanacak işlem imzası (base58 kodlu).
expectedAmount (number, isteğe bağlı) - Doğrulanacak beklenen ödeme tutarı. Birim para birimiyle eşleşmelidir:
- SOL için: lamport (1 SOL = 1.000.000.000 lamport)
- SPL token'ları için: token ondalık basamaklarına göre küçük birimler (örneğin, USDC 6 ondalık kullanır)
Sağlanmazsa, tutar doğrulaması atlanır.
expectedRecipient (string, isteğe bağlı) - Beklenen alıcı cüzdan adresi. (expectedAmount ile birlikte) sağlanırsa, fonksiyon alıcının en az bu tutarı aldığını doğrular. Sağlanmazsa, doğrulama atlanır.
expectedMint (string, isteğe bağlı) - SPL token basım adresi. Yalnızca SPL token transferleri için gereklidir. Sağlanmazsa, fonksiyon SOL transferi varsayar.

Döndürülen Değer

Bir Promise<PaymentVerificationResult> nesnesi:

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
}

Doğrulama Mantığı

Fonksiyon şu kontrolleri gerçekleştirir:

İmza Geçerliliği: İmzanın geçerli olduğunu kontrol eder.
İşlem Varlığı: rpc.getTransaction() kullanarak işlemi getirir. Bulunamazsa, verified: false döndürür.
Onay Durumu: İşlemin zincir üzerinde gerçekleştiğini kontrol eder.
SOL Transfer Doğrulaması (eğer expectedRecipient ve expectedAmount sağlanmışsa ve expectedMint yoksa):
- İşlemde alıcının hesap dizinini bulur
- Bakiye değişimini hesaplamak için preBalances ve postBalances değerlerini karşılaştırır
- Değişimin en az expectedAmount olduğunu doğrular
SPL Token Transfer Doğrulaması (expectedMint sağlanmışsa):
- Alıcının hem Token Program hem de Token-2022 Program için İlişkili Token Hesabını (ATA) türetir
- Beklenen mint ile eşleşen bir ATA için postTokenBalances kontrol eder
- Token miktarının en az expectedAmount olduğunu doğrular

Güvenlik Hususları

İstemci Tarafı Doğrulaması: Bu fonksiyon RPC'den işlem verilerini alır. RPC URL'nizi istemciye açık hale getirmeyin.
Sonlandırma: Fonksiyon onaylanmış işlemleri kontrol eder, ancak yüksek değerli ödemeler için finalized durumunu beklemeyi düşünün.

Örnek:

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()`

Bir işlem onaylanmış veya sonlandırılmış duruma ulaşana kadar blok zincirini yoklar, veya zaman aşımına uğrar.

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

Parametreler

rpc (SolanaClient['rpc'], zorunlu) - gill'den RPC istemcisi.
signatureStr (string, zorunlu) - Beklenecek işlem imzası.
timeoutMs (number, isteğe bağlı) - Milisaniye cinsinden beklenecek maksimum süre. Varsayılan: 30000 (30 saniye).

Dönüş Değeri

Promise<boolean> - İşlem zaman aşımı içinde confirmed veya finalized durumuna ulaşırsa true, aksi takdirde false döndürür.

Örnek:

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 Fonksiyonları

Bu fonksiyonlar mobil cüzdan taraması için Solana Pay URL'leri ve stilize QR kodları oluşturur.

`createSolanaPayRequest()`

Bir Solana Pay URL'si ve stilize bir QR kodu oluşturur.

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

Parametreler

request (TransferRequestURLFields, zorunlu) - Solana Pay transfer istek alanları:
- recipient - Alıcı genel anahtarı (@solana-commerce/solana-pay'den createRecipient(address) kullanın)
- amount - (isteğe bağlı) Küçük birimler cinsinden ödeme tutarı (SOL için lamport)
- splToken (isteğe bağlı) - SPL token mint genel anahtarı (createSPLToken(address) kullanın)
- reference (isteğe bağlı) - İzleme için referans genel anahtarı
- label (isteğe bağlı) - Satıcı adı
- message (isteğe bağlı) - Başarı mesajı
- memo (isteğe bağlı) - Zincir üstü not
options (SolanaPayRequestOptions, zorunlu) - QR kod stil seçenekleri:
- size (sayı) - QR kodunun piksel cinsinden genişlik/yükseklik değeri. Varsayılan: 256.
- background (string) - Arka plan rengi (hex/rgb). Varsayılan: 'white'.
- color (string) - QR kod rengi (hex/rgb). Varsayılan: 'black'.
- margin (sayı) - QR kodunun etrafındaki modül cinsinden kenar boşluğu.
- errorCorrectionLevel ('L' | 'M' | 'Q' | 'H') - Hata düzeltme seviyesi. Daha yüksek seviyeler daha fazla hasara izin verir ancak daha yoğun kodlar oluşturur.
- logo (string) - QR kodunun merkezine yerleştirilecek logo görsel URL'si.
- logoSize (sayı) - Logo boyutu, QR kod boyutunun yüzdesi olarak.
- logoBackgroundColor (string) - Logonun arkasındaki arka plan rengi.
- logoMargin (sayı) - Logo etrafındaki kenar boşluğu.
- dotStyle ('dots' | 'rounded' | 'square') - QR kod modüllerinin şekli.
- cornerStyle ('square' | 'rounded' | 'extra-rounded' | 'full-rounded' | 'maximum-rounded') - Köşe işaretleyicilerinin şekli.

Dönüş Değeri

Bir Promise, bir nesneye çözümlenir:

url (URL) - Solana Pay URL'si (örn., solana:recipient?amount=10&spl-token=...)
qr (string) - QR kod görselinin Base64 kodlu veri URL'si (<img src={qr} /> olarak kullanın)

Örnek:

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=...

HeadlessÖdeme Akışları

Ödeme Akışları

Kurulum

Ödeme İsteği Fonksiyonları

`createBuyNowRequest()`

Parametreler

Dönüş Değeri

`createCartRequest()`

Parametreler

Döndürülen Değer

`createTipRequest()`

Parametreler

Döndürülen Değer

Ödeme Doğrulama Fonksiyonları

`verifyPayment()`

Parametreler

Döndürülen Değer

Doğrulama Mantığı

Güvenlik Hususları

`waitForConfirmation()`

Parametreler

Dönüş Değeri

Solana Pay Fonksiyonları

`createSolanaPayRequest()`

Parametreler

Dönüş Değeri

İçindekiler