PaymentButton

Die PaymentButton-Komponente ist eine React-Komponente, die eine vollständige Zahlungsoberfläche für die Annahme von Solana-Zahlungen bereitstellt. Sie übernimmt intern die Wallet-Verbindung, Token-Auswahl, Transaktionsverarbeitung und UI-Statusverwaltung. Sie wird standardmäßig mit anpassbaren Schaltflächen und Dialogen ausgeliefert:

Trinkgeld-Schaltfläche

Trinkgeld-Schaltfläche

Zahlungsdialog

Zahlungsdialog

Solana Pay QR-Code-Dialog

Warenkorb-Dialog

Installation

pnpm add @solana-commerce/kit

Komponenten-Props

PaymentButtonProps

Die PaymentButton-Komponente akzeptiert folgende Props:

Erforderliche Props

• config (SolanaCommerceConfig) - Hauptkonfigurationsobjekt für die Zahlungskomponente. Dies ist die einzige erforderliche Prop. Siehe SolanaCommerceConfig unten.

Optionale Props

• paymentConfig (PaymentConfig) - Zahlungsspezifische Konfiguration einschließlich Produkte, Preisüberschreibungen und benutzerdefinierter Preisabrufer. Siehe PaymentConfig unten.

• onPayment ((amount: number, currency: string) => void) - Wird aufgerufen, wenn eine Zahlung initiiert wird, nachdem der Benutzer den Betrag und die Währung bestätigt hat. Empfängt den Zahlungsbetrag (in Token-Einheiten, nicht Lamports) und die Währungskennung.

• onPaymentStart (() => void) - Wird aufgerufen, wenn der Zahlungsablauf beginnt, bevor die eigentliche Transaktion übermittelt wird. Verwenden Sie dies, um Ladezustände anzuzeigen oder Analytics-Tracking durchzuführen.

• onPaymentSuccess ((signature: string) => void) - Wird aufgerufen, wenn die Transaktion on-chain bestätigt wurde. Empfängt die Transaktionssignatur. Hier sollten Sie den Bestellstatus aktualisieren, Bestätigungs-E-Mails versenden usw.

• onPaymentError ((error: Error) => void) - Wird aufgerufen, wenn die Zahlung in einer beliebigen Phase fehlschlägt (Wallet-Verbindung, Transaktionsübermittlung oder Bestätigung). Das Fehlerobjekt enthält Details darüber, was schiefgelaufen ist.

• onCancel (() => void) - Wird aufgerufen, wenn der Benutzer den Zahlungsablauf explizit abbricht (den Dialog schließt oder auf Abbrechen klickt).

• children (React.ReactNode) - Optionales benutzerdefiniertes Auslöserelement. Falls angegeben, ersetzt es die Standard-Zahlungsschaltfläche. Das untergeordnete Element sollte anklickbar sein (z. B. eine Schaltfläche).

• className (string) - CSS-Klassenname, der auf die Auslöserschaltfläche angewendet wird (wird nur verwendet, wenn keine benutzerdefinierten Kindelemente bereitgestellt werden).

• style (React.CSSProperties) - Inline-Stile, die auf die Auslöserschaltfläche angewendet werden (wird nur verwendet, wenn keine benutzerdefinierten Kindelemente bereitgestellt werden).

• variant ('default' | 'icon-only') - Schaltflächenvariante. Standardmäßig werden Text und Symbol angezeigt, 'icon-only' zeigt nur das Zahlungssymbol an.

Konfigurationsobjekte

SolanaCommerceConfig

Das Hauptkonfigurationsobjekt, das an die config-Eigenschaft übergeben wird.

Erforderliche Felder

• merchant (MerchantConfig) - Händlerinformationen und Zahlungsempfängerdetails. Siehe MerchantConfig.

• mode ('cart' | 'tip' | 'buyNow') - Zahlungsmodus, der den Anzeigetext der Schaltfläche und den UI-Ablauf bestimmt:

  • 'buyNow' - Einzelproduktkauf mit festem Betrag
  • 'cart' - Warenkorb mit mehreren Produkten
  • 'tip' - Benutzer wählt seinen eigenen Betrag (Spenden/Trinkgelder)

Optionale Felder

• position ('inline' | 'overlay') - Wie die Zahlungsbenutzeroberfläche angezeigt wird. Standardmäßig 'overlay'.

  • 'overlay' - Öffnet sich in einem modalen Overlay/Drawer
  • 'inline' - Direkt in die Seite eingebettet

• theme (ThemeConfig) - Optionen für visuelle Anpassungen. Siehe ThemeConfig.

• network ('mainnet' | 'devnet' | 'testnet') - Zu verwendendes Solana-Netzwerk. Standardmäßig 'mainnet'.

• rpcUrl (string) - Benutzerdefinierte RPC-Endpunkt-URL. Falls nicht angegeben, wird ein öffentlicher Standard-Endpunkt für das ausgewählte Netzwerk verwendet.

• allowedMints (string[]) - Array von Token-Mint-Adressen zur Einschränkung der Zahlungsmethoden. Falls nicht angegeben, sind alle unterstützten Token (SOL, USDC, USDT) verfügbar.

• showQR (boolean) - Ob die QR-Code-Zahlungsoption angezeigt werden soll. Nützlich für Mobilgeräte und Solana Pay-Integration.

• enableWalletConnect (boolean) - Legt fest, ob die Wallet-Verbindung aktiviert werden soll. Setzen Sie dies auf false, wenn Sie die Wallet-Verbindung extern verwalten.

• showMerchantInfo (boolean) - Legt fest, ob der Name und das Logo des Händlers in der Zahlungsoberfläche angezeigt werden sollen.

• debug (boolean) - Aktiviert ausführliche Konsolenausgaben zur Fehlersuche.

MerchantConfig

Definiert den Zahlungsempfänger und die Geschäftsinformationen.

Pflichtfelder

• name (string) - Geschäfts- oder Händlername, der den Nutzern während des Bezahlvorgangs angezeigt wird.

• wallet (string) - Solana-Wallet-Adresse, die Zahlungen empfängt. Muss eine gültige base58-kodierte Solana-Adresse sein.

Optionale Felder

• logo (string) - URL zum Händler-Logo-Bild. Wird in der Zahlungsoberfläche angezeigt, wenn showMerchantInfo aktiviert ist.

• description (string) - Geschäftsbeschreibung, die den Nutzern angezeigt wird.

ThemeConfig

Visuelle Anpassung der Zahlungsoberfläche.

Alle Felder sind optional und verfügen über sinnvolle Standardwerte.

• primaryColor (string) - Primäre Markenfarbe für Buttons und Akzente. Standard: '#9945FF' (Solana-Violett).

• secondaryColor (string) - Sekundäre Akzentfarbe. Standard: '#14F195' (Solana-Grün).

• backgroundColor (string) - Hintergrundfarbe für Modals/Container. Standard: '#ffffff'.

• textColor (string) - Primäre Textfarbe. Standard: '#111827'.

• borderRadius ('none' | 'sm' | 'md' | 'lg' | 'xl' | 'full') - Eckenradius für UI-Elemente. Standard: 'lg'.

  • 'none' = 0px
  • 'sm' = 12px
  • 'md' = 16px
  • 'lg' = 20px
  • 'xl' = 24px
  • 'full' = Vollständig abgerundet (kontextabhängig)

• fontFamily (string) - Schriftart für alle Texte. Standard: 'system-ui, -apple-system, sans-serif'.

• buttonShadow ('none' | 'sm' | 'md' | 'lg' | 'xl') - Schlagschatten für Buttons. Standard: 'md'.

• buttonBorder ('none' | 'black-10') - Rahmenstil für Buttons. Standard: 'black-10' (dezenter schwarzer Rahmen).

PaymentConfig

Erweiterte Zahlungskonfiguration für Preisgestaltung, Dezimalstellen und Produkte.

Alle Felder sind optional.

• products (Product[]) - Array von Produkten für die Modi 'cart' oder 'buyNow'. Erforderlich bei Verwendung dieser Modi. Jedes Produkt hat:

  • id (string, erforderlich) - Eindeutige Produktkennung
  • name (string, erforderlich) - Dem Benutzer angezeigter Produktname
  • quantity (number, erforderlich) - Menge dieses Produkts
  • price (number, optional) - Preis pro Einheit in USD
  • unitAmount (number, optional) - Alternative zum Feld price
  • description (string, optional) - Produktbeschreibung

• solPriceUsd (number) - Fester SOL-Preis in USD. Verwenden Sie dies zum Testen oder wenn Sie den SOL-Preis festlegen möchten. Wenn nicht angegeben, ruft die Komponente den aktuellen Preis von CoinGecko ab.

• getSolPrice (() => Promise<number>) - Benutzerdefinierte Funktion zum Abrufen des SOL-Preises. Verwenden Sie dies für:

  • Private Preis-Orakel
  • Vermeidung von Rate Limits öffentlicher APIs
  • Benutzerdefinierte Preislogik
  • Unternehmensanwendungen

  Wenn nicht angegeben, wird standardmäßig die öffentliche CoinGecko-API mit 1-minütigem Caching verwendet.

• tokenDecimals ({ [currency: string]: number }) - Überschreibt die Dezimalstellengenauigkeit des Tokens. Nützlich für benutzerdefinierte Tokens. Beispiel:

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

• fallbackSolPriceUsd (number) - Fallback-SOL-Preis, falls die Preis-API fehlschlägt und kein Cache verfügbar ist. Ohne diesen zeigt die Zahlungsoberfläche einen Fehler an, wenn das Abrufen des Preises fehlschlägt.

Interne Hooks

Die Komponente PaymentButton verwendet mehrere interne Hooks zur Verwaltung des Zustands und zur Berechnung von Werten:

useTheme(theme?: ThemeConfig)

Führt die vom Benutzer bereitgestellte Theme-Konfiguration mit den Standard-Theme-Werten zusammen. Gibt ein vollständiges ThemeConfig-Objekt mit allen ausgefüllten Feldern zurück.

Standard-Theme-Werte:

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

Der Hook ist memoized und wird nur neu berechnet, wenn sich die Theme-Konfiguration ändert.

useTotalAmount(mode, paymentConfig?)

Berechnet den gesamten Zahlungsbetrag basierend auf dem Commerce-Modus und den Produkten.

Verhalten nach Modus:

• 'tip'-Modus - Gibt 0 zurück (Betrag wird vom Benutzer festgelegt)
• 'cart'- und 'buyNow'-Modi - Summiert price * quantity für alle Produkte in paymentConfig.products

Der Hook behandelt Sonderfälle:

• Fehlende oder ungültige Preise werden standardmäßig auf 0 gesetzt
• Fehlende oder ungültige Mengen werden standardmäßig auf 0 gesetzt
• Stellt sicher, dass alle Werte endliche Zahlen sind
• Unterstützt sowohl price- als auch unitAmount-Produktfelder

Gibt den Gesamtbetrag als Zahl zurück (in USD für cart/buyNow, 0 für tip).

usePaymentUrl(merchant, amount, mode)

Generiert eine Solana Pay-URL für die Zahlung. Diese URL kann als QR-Code kodiert werden, um sie mit mobilen Wallets zu scannen.

Rückgabe: Eine solana:-Protokoll-URL mit Abfrageparametern für:

• recipient - Händler-Wallet-Adresse
• amount - Zahlungsbetrag
• reference - Eindeutige Zahlungsreferenz (generiert aus Zeitstempel + zufälliger Zeichenfolge)
• label - Händlername (für URL-Sicherheit bereinigt)
• message - Kontextabhängige Nachricht basierend auf dem Modus

Gibt eine leere Zeichenfolge zurück, wenn die Händler-Wallet ungültig ist oder der Betrag <= 0 beträgt.

Sicherheit: Der Händlername wird mit sanitizeString() bereinigt, um XSS-Angriffe durch URL-Injection zu verhindern.

Validierung & Fehlerbehandlung

Die Komponente führt vor dem Rendern eine Validierung durch:

1. Wallet-Validierung - Verwendet isAddress() von gill, um die Händler-Wallet-Adresse zu validieren. Bei Ungültigkeit wird ein Fehlerstatus anstelle der Zahlungs-UI gerendert.

2. Preisvalidierung - Stellt sicher, dass eine gültige Preisgestaltung konfiguriert ist:

   • Für 'tip'-Modus: Immer gültig (Benutzer wählt den Betrag)
   • Für 'cart'- und 'buyNow'-Modi: Validiert, dass totalAmount > 0

3. SSR-Sicherheit - Verwendet clientseitige Erkennung, um Hydratationsfehler zu vermeiden. Der isClient-Status stellt sicher, dass browserspezifische Funktionen (wie localStorage für Wallet-Persistierung) nur auf dem Client ausgeführt werden.

Komponentenarchitektur

Der PaymentButton umschließt alle untergeordneten Elemente mit zwei Context-Providern:

1. AppProvider - Stellt den Wallet-Verbindungsstatus und den Connector-Client bereit

   • Auto-Connect: standardmäßig deaktiviert
   • Speicherung: Verwendet localStorage, wenn verfügbar (nur clientseitig)
   • Debug-Modus: über Konfiguration anpassbar

2. ArcProvider - Stellt Solana-Blockchain-Client und RPC-Verbindung bereit

   • Netzwerk: Bestimmt durch config.network
   • RPC-URL: Verwendet serverseitige Auflösung mit Fallback auf öffentliche Endpunkte

RPC-URL-Auflösung

Die Komponente enthält eine ausgeklügelte RPC-URL-Auflösung:

• Wenn config.rpcUrl bereitgestellt wird, wird es direkt verwendet
• Andernfalls ruft es einen serverseitigen Resolver auf, der zuverlässige Endpunkte auswählt
• Fällt auf https://api.mainnet-beta.solana.com zurück, wenn die Auflösung fehlschlägt
• Die Auflösung erfolgt asynchron beim Mounting und aktualisiert den Status

Rendering-Modi

Overlay-Modus (position: 'overlay' oder Standard):

• Rendert einen Trigger-Button (benutzerdefiniert oder Standard)
• Öffnet die Zahlungs-UI in einem responsiven Modal (Desktop) oder Drawer (Mobil)
• Verwendet die ResponsiveShell-Komponente für adaptive Layouts

Inline-Modus (position: 'inline'):

• Bettet die Zahlungs-UI direkt in die Seite ein
• Kein Trigger-Button erforderlich
• Nützlich für dedizierte Checkout-Seiten

Beide Modi verwenden intern SecureIframeShell, um die Zahlungsschnittstelle in einem isolierten iframe für erhöhte Sicherheit zu rendern.

Verwendungsbeispiele

Einfache Zahlung

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

Trinkgeld-Widget mit benutzerdefiniertem Price-Fetcher

<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
  }}
/>

Warenkorb mit benutzerdefiniertem Theme

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

Benutzerdefinierter Trigger-Button

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