PaymentButton

De PaymentButton component is een React-component die een complete betalingsinterface biedt voor het accepteren van Solana-betalingen. Het behandelt portemonnee-connectie, tokenselectie, transactieverwerking en UI-statusbeheer intern. Out of the box wordt het geleverd met aanpasbare knoppen en modals:

Fooiknop

Betaalmodal

Winkelwagenmodal

Installatie

pnpm add @solana-commerce/kit

Component Props

`PaymentButtonProps`

De PaymentButton component accepteert de volgende props:

Verplichte Props

config (SolanaCommerceConfig) - Hoofdconfiguratieobject voor de betalingscomponent. Dit is de enige verplichte prop. Zie SolanaCommerceConfig hieronder.

Optionele Props

paymentConfig (PaymentConfig) - Betalingsspecifieke configuratie inclusief producten, prijsoverschrijvingen en aangepaste prijsophalers. Zie PaymentConfig hieronder.
onPayment ((amount: number, currency: string) => void) - Wordt aangeroepen wanneer een betaling wordt gestart nadat de gebruiker het bedrag en de valuta heeft bevestigd. Ontvangt het betalingsbedrag (in token-eenheden, geen lamports) en valuta-identificatie.
onPaymentStart (() => void) - Wordt aangeroepen wanneer het betalingsproces begint, voordat de daadwerkelijke transactie wordt ingediend. Gebruik dit om laadstatus weer te geven of analysetracking uit te voeren.
onPaymentSuccess ((signature: string) => void) - Wordt aangeroepen wanneer de transactie on-chain is bevestigd. Ontvangt de transactiehandtekening. Dit is waar u de bestelstatus moet bijwerken, bevestigingsmails moet versturen, enz.
onPaymentError ((error: Error) => void) - Wordt aangeroepen wanneer de betaling in elke fase mislukt (portemonnee-connectie, transactie-indiening of bevestiging). Het error-object bevat details over wat er is misgegaan.
onCancel (() => void) - Wordt aangeroepen wanneer de gebruiker expliciet het betalingsproces annuleert (de modal sluit of op annuleren klikt).
children (React.ReactNode) - Optioneel aangepast triggerelement. Indien opgegeven, vervangt het de standaard betaalknop. Het child-element moet klikbaar zijn (bijv. een knop).
className (string) - CSS-klassenaam toegepast op de triggerknop (alleen gebruikt wanneer geen aangepaste children zijn opgegeven).
style (React.CSSProperties) - Inline stijlen toegepast op de triggerknop (alleen gebruikt wanneer geen aangepaste children zijn opgegeven).
variant ('default' | 'icon-only') - Knopvariant. Standaard toont tekst en icoon, 'icon-only' toont alleen het betaalicoon.

Configuratieobjecten

`SolanaCommerceConfig`

Het hoofdconfiguratieobject dat wordt doorgegeven aan de config prop.

Verplichte velden

merchant (MerchantConfig) - Handelaarsinformatie en gegevens van de betalingsontvanger. Zie MerchantConfig.
mode ('cart' | 'tip' | 'buyNow') - Betaalmodus die de knopdisplaytekst en UI-flow bepaalt:
- 'buyNow' - Aankoop van één product met vast bedrag
- 'cart' - Winkelwagen met meerdere producten
- 'tip' - Gebruiker kiest eigen bedrag (donaties/fooien)

Optionele velden

position ('inline' | 'overlay') - Hoe de betalings-UI wordt weergegeven. Standaard ingesteld op 'overlay'.
- 'overlay' - Opent in een modal/drawer overlay
- 'inline' - Direct in de pagina ingesloten
theme (ThemeConfig) - Visuele aanpassingsopties. Zie ThemeConfig.
network ('mainnet' | 'devnet' | 'testnet') - Te gebruiken Solana-netwerk. Standaard ingesteld op 'mainnet'.
rpcUrl (string) - Aangepaste RPC-endpoint-URL. Indien niet opgegeven, wordt een standaard publiek endpoint voor het geselecteerde netwerk gebruikt.
allowedMints (string[]) - Array van token mint-adressen om betaalmethoden te beperken. Indien niet opgegeven, zijn alle ondersteunde tokens (SOL, USDC, USDT) beschikbaar.
showQR (boolean) - Of de QR-code betalingsoptie moet worden getoond. Nuttig voor mobiel en Solana Pay-integratie.
enableWalletConnect (boolean) - Of wallet-verbinding moet worden ingeschakeld. Stel in op false als u de wallet-verbinding extern afhandelt.
showMerchantInfo (boolean) - Of de handelaarsnaam en het logo moeten worden weergegeven in de betalings-UI.
debug (boolean) - Schakelt uitgebreide console-logging in voor foutopsporing.

`MerchantConfig`

Definieert de betalingsontvanger en bedrijfsinformatie.

Verplichte velden

name (string) - Bedrijfs- of handelaarsnaam die aan gebruikers wordt getoond tijdens het afrekenen.
wallet (string) - Solana wallet-adres dat betalingen ontvangt. Moet een geldig base58-gecodeerd Solana-adres zijn.

Optionele velden

logo (string) - URL naar het logo van de handelaar. Wordt weergegeven in de betalings-UI wanneer showMerchantInfo is ingeschakeld.
description (string) - Bedrijfsomschrijving die aan gebruikers wordt getoond.

`ThemeConfig`

Visuele aanpassing voor de betalings-UI.

Alle velden zijn optioneel en hebben verstandige standaardwaarden.

primaryColor (string) - Primaire merkkleur gebruikt voor knoppen en accenten. Standaard: '#9945FF' (Solana paars).
secondaryColor (string) - Secundaire accentkleur. Standaard: '#14F195' (Solana groen).
backgroundColor (string) - Achtergrondkleur van modal/container. Standaard: '#ffffff'.
textColor (string) - Primaire tekstkleur. Standaard: '#111827'.
borderRadius ('none' | 'sm' | 'md' | 'lg' | 'xl' | 'full') - Randradius toegepast op UI-elementen. Standaard: 'lg'.
- 'none' = 0px
- 'sm' = 12px
- 'md' = 16px
- 'lg' = 20px
- 'xl' = 24px
- 'full' = Volledig afgerond (contextafhankelijk)
fontFamily (string) - Lettertypefamilie voor alle tekst. Standaard: 'system-ui, -apple-system, sans-serif'.
buttonShadow ('none' | 'sm' | 'md' | 'lg' | 'xl') - Slagschaduw voor knoppen. Standaard: 'md'.
buttonBorder ('none' | 'black-10') - Randstijl voor knoppen. Standaard: 'black-10' (subtiele zwarte rand).

`PaymentConfig`

Geavanceerde betalingsconfiguratie voor prijzen, decimalen en producten.

Alle velden zijn optioneel.

products (Product[]) - Array van producten voor 'cart' of 'buyNow' modi. Vereist bij gebruik van deze modi. Elk product heeft:
- id (string, vereist) - Unieke product-identifier
- name (string, vereist) - Productnaam die aan gebruiker wordt getoond
- quantity (number, vereist) - Aantal van dit product
- price (number, optioneel) - Prijs per eenheid in USD
- unitAmount (number, optioneel) - Alternatief voor price veld
- description (string, optioneel) - Productomschrijving
solPriceUsd (number) - Vaste SOL-prijs in USD. Gebruik dit voor testen of wanneer je de SOL-prijs wilt vastzetten. Indien niet opgegeven, haalt de component de huidige prijs op van CoinGecko.
getSolPrice (() => Promise<number>) - Aangepaste functie voor het ophalen van de SOL- prijs. Gebruik dit voor:
- Privé-prijsorakels
- Vermijden van publieke API-tarieflimieten
- Aangepaste prijslogica
- Enterprise-toepassingen
Indien niet opgegeven, gebruikt het standaard de publieke CoinGecko API met 1 minuut caching.
tokenDecimals ({ [currency: string]: number }) - Overschrijf token decimaalprecisie. Nuttig voor aangepaste tokens. Voorbeeld:
```
tokenDecimals: {
  'CUSTOM': 8,
  'USDC': 6  // Can override defaults
}
```
fallbackSolPriceUsd (number) - Fallback SOL-prijs als de prijs-API faalt en er geen cache beschikbaar is. Zonder deze zal de betalings-UI een foutmelding tonen als het ophalen van de prijs mislukt.

Interne Hooks

De PaymentButton component gebruikt verschillende interne hooks om state te beheren en waarden te berekenen:

`useTheme(theme?: ThemeConfig)`

Voegt door gebruiker opgegeven themaconfiguratie samen met standaard themawaarden. Retourneert een compleet ThemeConfig object met alle velden ingevuld.

Standaard themawaarden:

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

De hook is gememoriseerd en herberekent alleen wanneer de themaconfiguratie wijzigt.

`useTotalAmount(mode, paymentConfig?)`

Berekent het totale betalingsbedrag op basis van de commercemodus en producten.

Gedrag per modus:

'tip' modus - Geeft 0 terug (bedrag wordt bepaald door gebruiker)
'cart' en 'buyNow' modi - Telt price * quantity op voor alle producten in paymentConfig.products

De hook handelt randgevallen af:

Ontbrekende of ongeldige prijzen worden standaard 0
Ontbrekende of ongeldige hoeveelheden worden standaard 0
Zorgt ervoor dat alle waarden eindige getallen zijn
Ondersteunt zowel price als unitAmount productvelden

Geeft het totaalbedrag terug als een getal (in USD voor cart/buyNow, 0 voor tip).

`usePaymentUrl(merchant, amount, mode)`

Genereert een Solana Pay URL voor de betaling. Deze URL kan worden gecodeerd als een QR-code voor het scannen met mobiele wallets.

Geeft terug: Een solana: protocol-URL met queryparameters voor:

recipient - Wallet-adres van verkoper
amount - Betalingsbedrag
reference - Unieke betalingsreferentie (gegenereerd uit tijdstempel + willekeurige string)
label - Naam van verkoper (gesaniteerd voor URL-veiligheid)
message - Contextueel bericht op basis van modus

Geeft een lege string terug als de wallet van de verkoper ongeldig is of het bedrag <= 0 is.

Beveiliging: De naam van de verkoper wordt gesaniteerd met sanitizeString() om XSS-aanvallen via URL-injectie te voorkomen.

Validatie & Foutafhandeling

Het component voert validatie uit voordat het wordt weergegeven:

Wallet-validatie - Gebruikt isAddress() van gill om het wallet-adres van de verkoper te valideren. Bij ongeldigheid wordt een foutstatus weergegeven in plaats van de betalings-UI.
Prijsvalidatie - Zorgt ervoor dat geldige prijzen zijn geconfigureerd:
- Voor 'tip' modus: Altijd geldig (gebruiker kiest bedrag)
- Voor 'cart' en 'buyNow' modi: Valideert dat totalAmount > 0
SSR-veiligheid - Gebruikt client-side detectie om hydratatie-mismatches te voorkomen. De isClient-status zorgt ervoor dat browser-specifieke functies (zoals localStorage voor wallet-persistentie) alleen op de client worden uitgevoerd.

Componentarchitectuur

De PaymentButton wikkelt alle child-elementen in twee context providers:

AppProvider - Levert wallet-verbindingsstatus en connector-client
- Auto-connect: standaard uitgeschakeld
- Opslag: Gebruikt localStorage indien beschikbaar (alleen client-side)
- Debug-modus: configureerbaar via config
ArcProvider - Levert Solana blockchain-client en RPC-verbinding
- Netwerk: Bepaald door config.network
- RPC-URL: Gebruikt server-side resolutie met fallback naar publieke endpoints

RPC-URL-resolutie

Het component bevat geavanceerde RPC-URL-resolutie:

Als config.rpcUrl is opgegeven, wordt deze direct gebruikt
Anders roept het een server-side resolver aan die betrouwbare endpoints selecteert
Valt terug op https://api.mainnet-beta.solana.com als resolutie mislukt
Resolutie vindt asynchroon plaats bij mounting en werkt de status bij

Weergavemodi

Overlay-modus (position: 'overlay' of standaard):

Rendert een trigger-knop (aangepast of standaard)
Opent betaal-UI in een responsieve modal (desktop) of drawer (mobiel)
Gebruikt ResponsiveShell-component voor adaptieve layouts

Inline-modus (position: 'inline'):

Integreert betaal-UI direct in de pagina
Geen trigger-knop nodig
Handig voor toegewijde checkout-pagina's

Beide modi gebruiken intern SecureIframeShell om de betalingsinterface weer te geven in een afgeschermde iframe voor beveiliging.

Gebruiksvoorbeelden

Basisbetaling

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

Fooiwidget met aangepaste prijsopvrager

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

Winkelwagen met aangepast thema

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

Aangepaste trigger-knop

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

Inhoudsopgave