PaymentButton

Il componente PaymentButton è un componente React che fornisce un'interfaccia di pagamento completa per accettare pagamenti Solana. Gestisce internamente la connessione del wallet, la selezione dei token, l'elaborazione delle transazioni e la gestione dello stato dell'UI. Include di default pulsanti e modali personalizzabili:

Pulsante Mancia

Pulsante Mancia

Modale di Pagamento

Modale di Pagamento

Modale QR Code Solana Pay

Modale Carrello

Installazione

pnpm add @solana-commerce/kit

Proprietà del Componente

PaymentButtonProps

Il componente PaymentButton accetta le seguenti proprietà:

Proprietà Obbligatorie

• config (SolanaCommerceConfig) - Oggetto di configurazione principale per il componente di pagamento. Questa è l'unica proprietà obbligatoria. Vedi SolanaCommerceConfig di seguito.

Proprietà Opzionali

• paymentConfig (PaymentConfig) - Configurazione specifica per il pagamento che include prodotti, sovrascritture di prezzo e recuperatori di prezzi personalizzati. Vedi PaymentConfig di seguito.

• onPayment ((amount: number, currency: string) => void) - Chiamata quando viene avviato un pagamento dopo che l'utente conferma l'importo e la valuta. Riceve l'importo del pagamento (in unità di token, non lamport) e l'identificatore della valuta.

• onPaymentStart (() => void) - Chiamata quando inizia il flusso di pagamento, prima che la transazione effettiva venga inviata. Usala per mostrare stati di caricamento o tracciamento analitico.

• onPaymentSuccess ((signature: string) => void) - Chiamata quando la transazione viene confermata on-chain. Riceve la firma della transazione. Qui è dove dovresti aggiornare lo stato dell'ordine, inviare email di conferma, ecc.

• onPaymentError ((error: Error) => void) - Chiamata quando il pagamento fallisce in qualsiasi fase (connessione del wallet, invio della transazione o conferma). L'oggetto errore contiene dettagli su cosa è andato storto.

• onCancel (() => void) - Chiamata quando l'utente annulla esplicitamente il flusso di pagamento (chiude il modale o clicca su annulla).

• children (React.ReactNode) - Elemento trigger personalizzato opzionale. Se fornito, sostituisce il pulsante di pagamento predefinito. L'elemento figlio deve essere cliccabile (ad esempio, un pulsante).

• className (string) - Nome della classe CSS applicato al pulsante trigger (utilizzato solo quando non vengono forniti elementi figlio personalizzati).

• style (React.CSSProperties) - Stili inline applicati al pulsante trigger (utilizzati solo quando non vengono forniti elementi figlio personalizzati).

• variant ('default' | 'icon-only') - Variante del pulsante. L'impostazione predefinita mostra testo e icona, 'icon-only' mostra solo l'icona di pagamento.

Oggetti di Configurazione

SolanaCommerceConfig

L'oggetto di configurazione principale passato alla prop config.

Campi Obbligatori

• merchant (MerchantConfig) - Informazioni del commerciante e dettagli del destinatario del pagamento. Vedi MerchantConfig.

• mode ('cart' | 'tip' | 'buyNow') - Modalità di pagamento che determina il testo visualizzato sul pulsante e il flusso dell'interfaccia:

  • 'buyNow' - Acquisto di un singolo prodotto con importo fisso
  • 'cart' - Carrello con più prodotti
  • 'tip' - L'utente sceglie il proprio importo (donazioni/mance)

Campi Opzionali

• position ('inline' | 'overlay') - Come viene visualizzata l'interfaccia di pagamento. Predefinito su 'overlay'.

  • 'overlay' - Si apre in una sovrapposizione modale/drawer
  • 'inline' - Incorporato direttamente nella pagina

• theme (ThemeConfig) - Opzioni di personalizzazione visiva. Vedi ThemeConfig.

• network ('mainnet' | 'devnet' | 'testnet') - Rete Solana da utilizzare. Predefinito su 'mainnet'.

• rpcUrl (string) - URL endpoint RPC personalizzato. Se non fornito, utilizza un endpoint pubblico predefinito per la rete selezionata.

• allowedMints (string[]) - Array di indirizzi mint dei token per limitare i metodi di pagamento. Se non fornito, tutti i token supportati (SOL, USDC, USDT) sono disponibili.

• showQR (boolean) - Se mostrare l'opzione di pagamento con codice QR. Utile per mobile e integrazione Solana Pay.

• enableWalletConnect (boolean) - Se abilitare la connessione del wallet. Imposta su false se gestisci la connessione del wallet esternamente.

• showMerchantInfo (boolean) - Se visualizzare il nome e il logo del commerciante nell'interfaccia di pagamento.

• debug (boolean) - Abilita il logging dettagliato nella console per il debug.

MerchantConfig

Definisce il destinatario del pagamento e le informazioni aziendali.

Campi Obbligatori

• name (string) - Nome dell'azienda o del commerciante visualizzato agli utenti durante il checkout.

• wallet (string) - Indirizzo del wallet Solana che riceverà i pagamenti. Deve essere un indirizzo Solana valido codificato in base58.

Campi Opzionali

• logo (string) - URL dell'immagine del logo del commerciante. Visualizzato nell'interfaccia di pagamento quando showMerchantInfo è abilitato.

• description (string) - Descrizione dell'azienda mostrata agli utenti.

ThemeConfig

Personalizzazione visiva dell'interfaccia di pagamento.

Tutti i campi sono opzionali e hanno valori predefiniti sensati.

• primaryColor (string) - Colore principale del brand utilizzato per pulsanti e accenti. Predefinito: '#9945FF' (viola Solana).

• secondaryColor (string) - Colore accento secondario. Predefinito: '#14F195' (verde Solana).

• backgroundColor (string) - Colore di sfondo del modale/contenitore. Predefinito: '#ffffff'.

• textColor (string) - Colore del testo principale. Predefinito: '#111827'.

• borderRadius ('none' | 'sm' | 'md' | 'lg' | 'xl' | 'full') - Raggio del bordo applicato agli elementi dell'interfaccia. Predefinito: 'lg'.

  • 'none' = 0px
  • 'sm' = 12px
  • 'md' = 16px
  • 'lg' = 20px
  • 'xl' = 24px
  • 'full' = Completamente arrotondato (dipende dal contesto)

• fontFamily (string) - Famiglia di caratteri per tutto il testo. Predefinito: 'system-ui, -apple-system, sans-serif'.

• buttonShadow ('none' | 'sm' | 'md' | 'lg' | 'xl') - Ombra per i pulsanti. Predefinito: 'md'.

• buttonBorder ('none' | 'black-10') - Stile del bordo per i pulsanti. Predefinito: 'black-10' (bordo nero sottile).

PaymentConfig

Configurazione avanzata del pagamento per prezzi, decimali e prodotti.

Tutti i campi sono opzionali.

• products (Product[]) - Array di prodotti per le modalità 'cart' o 'buyNow'. Richiesto quando si utilizzano queste modalità. Ogni prodotto ha:

  • id (string, richiesto) - Identificatore univoco del prodotto
  • name (string, richiesto) - Nome del prodotto mostrato all'utente
  • quantity (number, richiesto) - Quantità di questo prodotto
  • price (number, opzionale) - Prezzo per unità in USD
  • unitAmount (number, opzionale) - Alternativa al campo price
  • description (string, opzionale) - Descrizione del prodotto

• solPriceUsd (number) - Prezzo fisso di SOL in USD. Utilizzalo per test o quando vuoi bloccare il prezzo di SOL. Se non fornito, il componente recupera il prezzo corrente da CoinGecko.

• getSolPrice (() => Promise<number>) - Funzione personalizzata per recuperare il prezzo di SOL. Utilizzala per:

  • Oracle di prezzo privati
  • Evitare limiti di rate delle API pubbliche
  • Logica di pricing personalizzata
  • Applicazioni enterprise

  Se non fornita, viene utilizzata l'API pubblica di CoinGecko con cache di 1 minuto.

• tokenDecimals ({ [currency: string]: number }) - Sovrascrivi la precisione decimale del token. Utile per token personalizzati. Esempio:

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

• fallbackSolPriceUsd (number) - Prezzo di fallback di SOL se l'API dei prezzi fallisce e non è disponibile alcuna cache. Senza questo, l'interfaccia di pagamento mostrerà un errore se il recupero del prezzo fallisce.

Hook Interni

Il componente PaymentButton utilizza diversi hook interni per gestire lo stato e calcolare i valori:

useTheme(theme?: ThemeConfig)

Unisce la configurazione del tema fornita dall'utente con i valori di default del tema. Restituisce un oggetto ThemeConfig completo con tutti i campi popolati.

Valori di default del tema:

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

L'hook è memoizzato e ricalcola solo quando cambia la configurazione del tema.

useTotalAmount(mode, paymentConfig?)

Calcola l'importo totale del pagamento in base alla modalità commerciale e ai prodotti.

Comportamento per modalità:

• Modalità 'tip' - Restituisce 0 (l'importo è determinato dall'utente)
• Modalità 'cart' e 'buyNow' - Somma price * quantity per tutti i prodotti in paymentConfig.products

L'hook gestisce i casi limite:

• Prezzi mancanti o non validi vengono impostati di default a 0
• Quantità mancanti o non valide vengono impostate di default a 0
• Garantisce che tutti i valori siano numeri finiti
• Supporta sia i campi prodotto price che unitAmount

Restituisce l'importo totale come numero (in USD per cart/buyNow, 0 per tip).

usePaymentUrl(merchant, amount, mode)

Genera un URL Solana Pay per il pagamento. Questo URL può essere codificato come codice QR per la scansione tramite wallet mobile.

Restituisce: Un URL con protocollo solana: con parametri di query per:

• recipient - Indirizzo del wallet del commerciante
• amount - Importo del pagamento
• reference - Riferimento di pagamento univoco (generato da timestamp + stringa casuale)
• label - Nome del commerciante (sanitizzato per sicurezza URL)
• message - Messaggio contestuale basato sulla modalità

Restituisce una stringa vuota se il wallet del commerciante non è valido o l'importo è <= 0.

Sicurezza: Il nome del commerciante viene sanitizzato utilizzando sanitizeString() per prevenire attacchi XSS attraverso l'iniezione di URL.

Validazione e gestione degli errori

Il componente esegue la validazione prima del rendering:

1. Validazione del wallet - Utilizza isAddress() da gill per validare l'indirizzo del wallet del commerciante. Se non valido, renderizza uno stato di errore invece dell'interfaccia di pagamento.

2. Validazione dei prezzi - Garantisce che sia configurato un prezzo valido:

   • Per la modalità 'tip': Sempre valida (l'utente sceglie l'importo)
   • Per le modalità 'cart' e 'buyNow': Valida che totalAmount > 0

3. Sicurezza SSR - Utilizza il rilevamento lato client per prevenire errori di idratazione. Lo stato isClient garantisce che le funzionalità disponibili solo nel browser (come localStorage per la persistenza del wallet) vengano eseguite solo lato client.

Architettura dei Componenti

Il componente PaymentButton racchiude tutti i figli in due provider di contesto:

1. AppProvider - Fornisce lo stato di connessione del wallet e il client del connettore

   • Connessione automatica: disabilitata per impostazione predefinita
   • Archiviazione: Utilizza localStorage quando disponibile (solo lato client)
   • Modalità debug: configurabile tramite config

2. ArcProvider - Fornisce il client blockchain Solana e la connessione RPC

   • Network: Determinato da config.network
   • URL RPC: Utilizza la risoluzione lato server con fallback su endpoint pubblici

Risoluzione URL RPC

Il componente include una sofisticata risoluzione dell'URL RPC:

• Se config.rpcUrl viene fornito, viene utilizzato direttamente
• Altrimenti, chiama un risolutore lato server che seleziona endpoint affidabili
• Fa fallback a https://api.mainnet-beta.solana.com se la risoluzione fallisce
• La risoluzione avviene in modo asincrono al mount e aggiorna lo stato

Modalità di Rendering

Modalità overlay (position: 'overlay' o predefinita):

• Renderizza un pulsante trigger (personalizzato o predefinito)
• Apre l'interfaccia di pagamento in un modal responsive (desktop) o drawer (mobile)
• Utilizza il componente ResponsiveShell per layout adattivi

Modalità inline (position: 'inline'):

• Incorpora l'interfaccia di pagamento direttamente nella pagina
• Non è necessario alcun pulsante trigger
• Utile per pagine di checkout dedicate

Entrambe le modalità utilizzano SecureIframeShell internamente per renderizzare l'interfaccia di pagamento in un iframe isolato per sicurezza.

Esempi di Utilizzo

Pagamento Base

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

Widget per Mance con Price Fetcher Personalizzato

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

Carrello con Tema Personalizzato

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

Pulsante Trigger Personalizzato

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