PaymentButton

PaymentButton bileşeni, Solana ödemelerini kabul etmek için eksiksiz bir ödeme arayüzü sağlayan bir React bileşenidir. Cüzdan bağlantısını, token seçimini, işlem sürecini ve kullanıcı arayüzü durum yönetimini dahili olarak ele alır. Hazır olarak, özelleştirilebilir buton ve modallarla birlikte gelir:

Bahşiş Butonu

Bahşiş Butonu

Ödeme Modalı

Ödeme Modalı

Solana Pay QR Kod Modalı

Sepet Modalı

Kurulum

pnpm add @solana-commerce/kit

Bileşen Özellikleri

PaymentButtonProps

PaymentButton bileşeni aşağıdaki özellikleri kabul eder:

Zorunlu Özellikler

• config (SolanaCommerceConfig) - Ödeme bileşeni için ana yapılandırma nesnesi. Bu tek zorunlu özelliktir. Aşağıdaki SolanaCommerceConfig bölümüne bakın.

İsteğe Bağlı Özellikler

• paymentConfig (PaymentConfig) - Ürünler, fiyatlandırma geçersiz kılmaları ve özel fiyat alıcıları dahil olmak üzere ödemeye özgü yapılandırma. Aşağıdaki PaymentConfig bölümüne bakın.

• onPayment ((amount: number, currency: string) => void) - Kullanıcı tutarı ve para birimini onayladıktan sonra bir ödeme başlatıldığında çağrılır. Ödeme tutarını (lamport değil, token birimi cinsinden) ve para birimi tanımlayıcısını alır.

• onPaymentStart (() => void) - Gerçek işlem gönderilmeden önce ödeme akışı başladığında çağrılır. Yükleme durumlarını göstermek veya analitik takibi için kullanın.

• onPaymentSuccess ((signature: string) => void) - İşlem zincir üzerinde onaylandığında çağrılır. İşlem imzasını alır. Sipariş durumunu güncellemeniz, onay e-postaları göndermeniz vb. gereken yer burasıdır.

• onPaymentError ((error: Error) => void) - Ödeme herhangi bir aşamada (cüzdan bağlantısı, işlem gönderimi veya onay) başarısız olduğunda çağrılır. Hata nesnesi neyin yanlış gittiğine dair ayrıntılar içerir.

• onCancel (() => void) - Kullanıcı ödeme akışını açıkça iptal ettiğinde (modalı kapatır veya iptal'e tıklar) çağrılır.

• children (React.ReactNode) - İsteğe bağlı özel tetikleyici öğe. Sağlanırsa, varsayılan ödeme düğmesini değiştirir. Alt öğe tıklanabilir olmalıdır (örneğin, bir düğme).

• className (string) - Tetikleyici düğmeye uygulanan CSS sınıf adı (yalnızca özel alt öğe sağlanmadığında kullanılır).

• style (React.CSSProperties) - Tetikleyici düğmeye uygulanan satır içi stiller (yalnızca özel alt öğe sağlanmadığında kullanılır).

• variant ('default' | 'icon-only') - Düğme varyantı. Varsayılan olarak metin ve simge gösterir, 'icon-only' yalnızca ödeme simgesini gösterir.

Yapılandırma Nesneleri

SolanaCommerceConfig

config prop'una iletilen ana yapılandırma nesnesi.

Gerekli Alanlar

• merchant (MerchantConfig) - Satıcı bilgileri ve ödeme alıcısı detayları. Bkz. MerchantConfig.

• mode ('cart' | 'tip' | 'buyNow') - Düğme görüntüleme metnini ve UI akışını belirleyen ödeme modu:

  • 'buyNow' - Sabit tutarlı tek ürün satın alma
  • 'cart' - Birden fazla ürünlü alışveriş sepeti
  • 'tip' - Kullanıcı kendi tutarını seçer (bağışlar/bahşişler)

İsteğe Bağlı Alanlar

• position ('inline' | 'overlay') - Ödeme arayüzünün nasıl görüntüleneceği. Varsayılan olarak 'overlay'.

  • 'overlay' - Modal/çekmece katmanında açılır
  • 'inline' - Doğrudan sayfaya gömülü

• theme (ThemeConfig) - Görsel özelleştirme seçenekleri. Bkz. ThemeConfig.

• network ('mainnet' | 'devnet' | 'testnet') - Kullanılacak Solana ağı. Varsayılan olarak 'mainnet'.

• rpcUrl (string) - Özel RPC uç nokta URL'si. Sağlanmazsa, seçilen ağ için varsayılan genel uç nokta kullanılır.

• allowedMints (string[]) - Ödeme yöntemlerini kısıtlamak için token mint adreslerinin dizisi. Sağlanmazsa, desteklenen tüm tokenler (SOL, USDC, USDT) kullanılabilir.

• showQR (boolean) - QR kod ödeme seçeneğinin gösterilip gösterilmeyeceği. Mobil ve Solana Pay entegrasyonu için kullanışlıdır.

• enableWalletConnect (boolean) - Cüzdan bağlantısının etkinleştirilip etkinleştirilmeyeceği. Cüzdan bağlantısını harici olarak yönetiyorsanız false olarak ayarlayın.

• showMerchantInfo (boolean) - Ödeme arayüzünde satıcı adı ve logosunun görüntülenip görüntülenmeyeceği.

• debug (boolean) - Hata ayıklama için ayrıntılı konsol günlüğünü etkinleştirir.

MerchantConfig

Ödeme alıcısını ve işletme bilgilerini tanımlar.

Gerekli Alanlar

• name (string) - Ödeme sırasında kullanıcılara gösterilen işletme veya satıcı adı.

• wallet (string) - Ödemeleri alacak Solana cüzdan adresi. Geçerli bir base58 kodlu Solana adresi olmalıdır.

İsteğe Bağlı Alanlar

• logo (string) - Satıcı logosu görsel URL'si. showMerchantInfo etkinleştirildiğinde ödeme arayüzünde görüntülenir.

• description (string) - Kullanıcılara gösterilen işletme açıklaması.

ThemeConfig

Ödeme arayüzü için görsel özelleştirme.

Tüm alanlar isteğe bağlıdır ve mantıklı varsayılan değerlere sahiptir.

• primaryColor (string) - Düğmeler ve vurgular için kullanılan birincil marka rengi. Varsayılan: '#9945FF' (Solana moru).

• secondaryColor (string) - İkincil vurgu rengi. Varsayılan: '#14F195' (Solana yeşili).

• backgroundColor (string) - Modal/kapsayıcı arka plan rengi. Varsayılan: '#ffffff'.

• textColor (string) - Birincil metin rengi. Varsayılan: '#111827'.

• borderRadius ('none' | 'sm' | 'md' | 'lg' | 'xl' | 'full') - Arayüz öğelerine uygulanan köşe yuvarlaklığı. Varsayılan: 'lg'.

  • 'none' = 0px
  • 'sm' = 12px
  • 'md' = 16px
  • 'lg' = 20px
  • 'xl' = 24px
  • 'full' = Tamamen yuvarlak (bağlama bağlı)

• fontFamily (string) - Tüm metinler için yazı tipi ailesi. Varsayılan: 'system-ui, -apple-system, sans-serif'.

• buttonShadow ('none' | 'sm' | 'md' | 'lg' | 'xl') - Düğmeler için gölge efekti. Varsayılan: 'md'.

• buttonBorder ('none' | 'black-10') - Düğmeler için kenarlık stili. Varsayılan: 'black-10' (hafif siyah kenarlık).

PaymentConfig

Fiyatlandırma, ondalık sayılar ve ürünler için gelişmiş ödeme yapılandırması.

Tüm alanlar isteğe bağlıdır.

• products (Product[]) - 'cart' veya 'buyNow' modları için ürün dizisi. Bu modları kullanırken zorunludur. Her ürün şunları içerir:

  • id (string, zorunlu) - Benzersiz ürün tanımlayıcısı
  • name (string, zorunlu) - Kullanıcıya gösterilen ürün adı
  • quantity (number, zorunlu) - Bu üründen miktar
  • price (number, isteğe bağlı) - Birim başına USD fiyatı
  • unitAmount (number, isteğe bağlı) - price alanına alternatif
  • description (string, isteğe bağlı) - Ürün açıklaması

• solPriceUsd (number) - USD cinsinden sabit SOL fiyatı. Test için veya SOL fiyatını sabitlemek istediğinizde bunu kullanın. Sağlanmadığı takdirde, bileşen mevcut fiyatı CoinGecko'dan alır.

• getSolPrice (() => Promise<number>) - SOL fiyatını almak için özel fonksiyon. Şunlar için kullanın:

  • Özel fiyat oracle'ları
  • Genel API hız limitlerinden kaçınma
  • Özel fiyatlandırma mantığı
  • Kurumsal uygulamalar

  Sağlanmadığı takdirde, 1 dakikalık önbellekleme ile CoinGecko genel API'sine varsayılan olarak ayarlanır.

• tokenDecimals ({ [currency: string]: number }) - Token ondalık hassasiyetini geçersiz kılma. Özel tokenler için kullanışlıdır. Örnek:

  tokenDecimals: {
    'CUSTOM': 8,
    'USDC': 6  // Can override defaults
  }

• fallbackSolPriceUsd (number) - Fiyat API'si başarısız olursa ve kullanılabilir önbellek yoksa yedek SOL fiyatı. Bu olmadan, fiyat alımı başarısız olursa ödeme arayüzü bir hata gösterecektir.

Dahili Hook'lar

PaymentButton bileşeni, durumu yönetmek ve değerleri hesaplamak için birkaç dahili hook kullanır:

useTheme(theme?: ThemeConfig)

Kullanıcı tarafından sağlanan tema yapılandırmasını varsayılan tema değerleriyle birleştirir. Tüm alanları doldurulmuş tam bir ThemeConfig nesnesi döndürür.

Varsayılan tema değerleri:

• primaryColor: '#9945FF'
• secondaryColor: '#14F195'
• backgroundColor: '#ffffff'
• textColor: '#111827'
• borderRadius: 'lg'
• fontFamily: 'system-ui, -apple-system, sans-serif'
• buttonShadow: 'md'
• buttonBorder: 'black-10'

Hook hafızaya alınır ve yalnızca tema yapılandırması değiştiğinde yeniden hesaplanır.

useTotalAmount(mode, paymentConfig?)

Ticaret moduna ve ürünlere göre toplam ödeme tutarını hesaplar.

Moda göre davranış:

• 'tip' modu - 0 döndürür (tutar kullanıcı tarafından belirlenir)
• 'cart' ve 'buyNow' modları - paymentConfig.products içindeki tüm ürünler için price * quantity değerlerini toplar

Hook uç durumları yönetir:

• Eksik veya geçersiz fiyatlar varsayılan olarak 0 değerini alır
• Eksik veya geçersiz miktarlar varsayılan olarak 0 değerini alır
• Tüm değerlerin sonlu sayılar olmasını sağlar
• Hem price hem de unitAmount ürün alanlarını destekler

Toplam tutarı sayı olarak döndürür (cart/buyNow için USD cinsinden, tip için 0).

usePaymentUrl(merchant, amount, mode)

Ödeme için bir Solana Pay URL'si oluşturur. Bu URL, mobil cüzdan taraması için QR kodu olarak kodlanabilir.

Döndürür: Aşağıdaki sorgu parametrelerini içeren bir solana: protokol URL'si:

• recipient - Satıcı cüzdan adresi
• amount - Ödeme tutarı
• reference - Benzersiz ödeme referansı (zaman damgası + rastgele dizeden oluşturulur)
• label - Satıcı adı (URL güvenliği için temizlenmiş)
• message - Moda göre bağlamsal mesaj

Satıcı cüzdanı geçersizse veya tutar <= 0 ise boş dize döndürür.

Güvenlik: Satıcı adı, URL enjeksiyonu yoluyla XSS saldırılarını önlemek için sanitizeString() kullanılarak temizlenir.

Doğrulama ve Hata İşleme

Bileşen işleme öncesinde doğrulama gerçekleştirir:

1. Cüzdan Doğrulama - Satıcı cüzdan adresini doğrulamak için gill'den isAddress() kullanır. Geçersizse, ödeme arayüzü yerine hata durumu işler.

2. Fiyatlandırma Doğrulama - Geçerli fiyatlandırmanın yapılandırıldığından emin olur:

   • 'tip' modu için: Her zaman geçerlidir (kullanıcı tutarı seçer)
   • 'cart' ve 'buyNow' modları için: totalAmount > 0 değerinin geçerli olduğunu doğrular

3. SSR Güvenliği - Hidrasyon uyuşmazlıklarını önlemek için istemci tarafı algılama kullanır. isClient durumu, tarayıcıya özgü özelliklerin (cüzdan kalıcılığı için localStorage gibi) yalnızca istemci tarafında çalışmasını sağlar.

Bileşen Mimarisi

PaymentButton tüm alt bileşenleri iki context sağlayıcı içine sarar:

1. AppProvider - Cüzdan bağlantı durumu ve bağlayıcı istemcisini sağlar

   • Otomatik bağlanma: varsayılan olarak devre dışı
   • Depolama: Kullanılabilir olduğunda localStorage kullanır (yalnızca istemci tarafı)
   • Hata ayıklama modu: yapılandırma üzerinden ayarlanabilir

2. ArcProvider - Solana blockchain istemcisi ve RPC bağlantısı sağlar

   • Ağ: config.network üzerinden belirlenir
   • RPC URL: Genel uç noktalara geri dönüş ile sunucu tarafı çözümleme kullanır

RPC URL Çözümleme

Bileşen gelişmiş RPC URL çözümleme içerir:

• config.rpcUrl sağlanmışsa doğrudan kullanılır
• Aksi takdirde güvenilir uç noktaları seçen sunucu tarafı çözümleyiciyi çağırır
• Çözümleme başarısız olursa https://api.mainnet-beta.solana.com'e geri döner
• Çözümleme, mount sırasında asenkron olarak gerçekleşir ve durumu günceller

İşleme Modları

Kaplama modu (position: 'overlay' veya varsayılan):

• Bir tetikleme düğmesi işler (özel veya varsayılan)
• Ödeme arayüzünü duyarlı bir modal (masaüstü) veya çekmece (mobil) içinde açar
• Uyarlanabilir düzenler için ResponsiveShell bileşenini kullanır

Satır içi mod (position: 'inline'):

• Ödeme arayüzünü doğrudan sayfaya gömer
• Tetikleme düğmesine gerek yoktur
• Özel ödeme sayfaları için kullanışlıdır

Her iki mod da güvenlik için sandboxlanmış bir iframe içinde ödeme arayüzünü işlemek üzere dahili olarak SecureIframeShell kullanır.

Kullanım Örnekleri

Temel Ödeme

<PaymentButton
  config={{
    merchant: {
      name: "Coffee Shop",
      wallet: "your-wallet-address"
    },
    mode: "buyNow"
  }}
  paymentConfig={{
    products: [
      {
        id: "coffee-001",
        name: "Espresso",
        price: 4.5,
        quantity: 1
      }
    ]
  }}
  onPaymentSuccess={(sig) => {
    console.log("Payment confirmed:", sig);
  }}
/>

Özel Fiyat Getirici ile Bahşiş Widget'ı

<PaymentButton
  config={{
    merchant: {
      name: "Content Creator",
      wallet: "creator-wallet"
    },
    mode: "tip"
  }}
  paymentConfig={{
    // Use your own price API to avoid rate limits
    getSolPrice: async () => {
      const res = await fetch("/custom-api/solana-price");
      const data = await res.json();
      return data.price;
    },
    // Fallback if your API fails
    fallbackSolPriceUsd: 200
  }}
/>

Özel Tema ile Alışveriş Sepeti

<PaymentButton
  config={{
    merchant: {
      name: "My Store",
      wallet: "store-wallet",
      logo: "/logo.png"
    },
    mode: "cart",
    theme: {
      primaryColor: "#FF6B6B",
      backgroundColor: "#1a1a1a",
      textColor: "#ffffff",
      borderRadius: "xl",
      buttonShadow: "lg"
    },
    showMerchantInfo: true
  }}
  paymentConfig={{
    products: [
      { id: "1", name: "T-Shirt", price: 25, quantity: 2 },
      { id: "2", name: "Hoodie", price: 45, quantity: 1 }
    ]
  }}
  onPaymentSuccess={(signature) => {
    // Verify transaction on your backend
    fetch("/api/verify-payment", {
      method: "POST",
      body: JSON.stringify({ signature })
    });
  }}
/>

Özel Tetikleme Düğmesi

<PaymentButton
  config={{
    merchant: { name: "Shop", wallet: "address" },
    mode: "buyNow"
  }}
  paymentConfig={{
    products: [{ id: "1", name: "Product", price: 10, quantity: 1 }]
  }}
>
  <button className="custom-button">🚀 Pay with Solana</button>
</PaymentButton>