PaymentButton

PaymentButton-komponentti on React-komponentti, joka tarjoaa täydellisen maksukäyttöliittymän Solana-maksujen vastaanottamiseen. Se käsittelee lompakkoyhteyden, tokenin valinnan, tapahtumien käsittelyn ja käyttöliittymän tilanhallinnan sisäisesti. Valmiina se sisältää mukautettavat painikkeet ja modaalit:

Tippipainike

Maksumodaali

Solana Pay QR-koodimodaali

Ostoskorimodaali

Asennus

pnpm add @solana-commerce/kit

Komponentin propsit

`PaymentButtonProps`

PaymentButton-komponentti hyväksyy seuraavat propsit:

Pakolliset propsit

config (SolanaCommerceConfig) - Maksukomponentin pääasetukset sisältävä objekti. Tämä on ainoa pakollinen propsi. Katso SolanaCommerceConfig alta.

Valinnaiset propsit

paymentConfig (PaymentConfig) - Maksukohtaiset asetukset, mukaan lukien tuotteet, hinnoittelun ohitukset ja mukautetut hinnanhakijat. Katso PaymentConfig alta.
onPayment ((amount: number, currency: string) => void) - Kutsutaan, kun maksu aloitetaan sen jälkeen, kun käyttäjä vahvistaa summan ja valuutan. Vastaanottaa maksusumman (token-yksikköinä, ei lamporteina) ja valuutan tunnisteen.
onPaymentStart (() => void) - Kutsutaan, kun maksuvirta alkaa, ennen varsinaisen tapahtuman lähettämistä. Käytä tätä lataustilojen näyttämiseen tai analytiikan seurantaan.
onPaymentSuccess ((signature: string) => void) - Kutsutaan, kun tapahtuma on vahvistettu lohkoketjussa. Vastaanottaa tapahtuman allekirjoituksen. Tässä sinun tulisi päivittää tilauksen tila, lähettää vahvistussähköpostit jne.
onPaymentError ((error: Error) => void) - Kutsutaan, kun maksu epäonnistuu missä tahansa vaiheessa (lompakkoyhteys, tapahtuman lähetys tai vahvistus). Virhe-objekti sisältää tiedot siitä, mikä meni pieleen.
onCancel (() => void) - Kutsutaan, kun käyttäjä nimenomaisesti peruuttaa maksuvirran (sulkee modaalin tai napsauttaa peruuta).
children (React.ReactNode) - Valinnainen mukautettu laukaisuelementti. Jos annettu, korvaa oletusmaksupainikkeen. Lapsielementin tulisi olla klikattava (esim. painike).
className (string) - CSS-luokan nimi, jota sovelletaan laukaisupainikkeeseen (käytetään vain, kun mukautettuja lapsia ei ole annettu).
style (React.CSSProperties) - Inline-tyylit, joita sovelletaan laukaisupainikkeeseen (käytetään vain, kun mukautettuja lapsia ei ole annettu).
variant ('default' | 'icon-only') - Painikkeen variaatio. Oletus näyttää tekstin ja kuvakkeen, 'icon-only' näyttää vain maksukuvakkeen.

Konfiguraatio-objektit

`SolanaCommerceConfig`

Päämäärittelyobjekti, joka välitetään config-propille.

Pakolliset kentät

merchant (MerchantConfig) - Kauppiaan tiedot ja maksun vastaanottajan tiedot. Katso MerchantConfig.
mode ('cart' | 'tip' | 'buyNow') - Maksutila, joka määrittää painikkeen näyttötekstin ja käyttöliittymän kulun:
- 'buyNow' - Yksittäisen tuotteen osto kiinteällä summalla
- 'cart' - Ostoskori useilla tuotteilla
- 'tip' - Käyttäjä valitsee oman summansa (lahjoitukset/juomarahat)

Valinnaiset kentät

position ('inline' | 'overlay') - Miten maksukäyttöliittymä näytetään. Oletuksena 'overlay'.
- 'overlay' - Avautuu modaalina/laatikkona päällä
- 'inline' - Upotettu suoraan sivulle
theme (ThemeConfig) - Visuaaliset mukautusvaihtoehdot. Katso ThemeConfig.
network ('mainnet' | 'devnet' | 'testnet') - Käytettävä Solana-verkko. Oletuksena 'mainnet'.
rpcUrl (string) - Mukautettu RPC-päätepisteen URL. Jos ei anneta, käyttää oletusarvoista julkista päätepistettä valitulle verkolle.
allowedMints (string[]) - Taulukko token mint -osoitteista maksutapojen rajoittamiseksi. Jos ei anneta, kaikki tuetut tokenit (SOL, USDC, USDT) ovat käytettävissä.
showQR (boolean) - Näytetäänkö QR-koodimaksuvaihtoehto. Hyödyllinen mobiilissa ja Solana Pay -integraatiossa.
enableWalletConnect (boolean) - Määrittää, otetaanko lompakkoyhteys käyttöön. Aseta arvoksi false, jos käsittelet lompakkoyhteyden ulkoisesti.
showMerchantInfo (boolean) - Määrittää, näytetäänkö kauppiaan nimi ja logo maksukäyttöliittymässä.
debug (boolean) - Ottaa käyttöön yksityiskohtaisen konsolilokituksen virheenkorjausta varten.

`MerchantConfig`

Määrittää maksun vastaanottajan ja yritystiedot.

Pakolliset kentät

name (string) - Yrityksen tai kauppiaan nimi, joka näytetään käyttäjille kassalla.
wallet (string) - Solana-lompakko-osoite, joka vastaanottaa maksut. Täytyy olla kelvollinen base58-koodattu Solana-osoite.

Valinnaiset kentät

logo (string) - URL kauppiaan logokuvaan. Näytetään maksukäyttöliittymässä, kun showMerchantInfo on käytössä.
description (string) - Yrityksen kuvaus, joka näytetään käyttäjille.

`ThemeConfig`

Visuaalinen mukauttaminen maksukäyttöliittymälle.

Kaikki kentät ovat valinnaisia ja niillä on järkevät oletusarvot.

primaryColor (string) - Ensisijainen brändiväri, jota käytetään painikkeissa ja korostuksissa. Oletusarvo: '#9945FF' (Solanan violetti).
secondaryColor (string) - Toissijainen korostusväri. Oletusarvo: '#14F195' (Solanan vihreä).
backgroundColor (string) - Modaalin/säilön taustaväri. Oletusarvo: '#ffffff'.
textColor (string) - Ensisijainen tekstin väri. Oletusarvo: '#111827'.
borderRadius ('none' | 'sm' | 'md' | 'lg' | 'xl' | 'full') - Reunan pyöristys, jota sovelletaan käyttöliittymäelementteihin. Oletusarvo: 'lg'.
- 'none' = 0px
- 'sm' = 12px
- 'md' = 16px
- 'lg' = 20px
- 'xl' = 24px
- 'full' = Täysin pyöristetty (kontekstiriippuvainen)
fontFamily (string) - Kirjasintyyppi kaikelle tekstille. Oletusarvo: 'system-ui, -apple-system, sans-serif'.
buttonShadow ('none' | 'sm' | 'md' | 'lg' | 'xl') - Varjostus painikkeille. Oletusarvo: 'md'.
buttonBorder ('none' | 'black-10') - Reunatyyli painikkeille. Oletusarvo: 'black-10' (hienovarainen musta reunus).

`PaymentConfig`

Kehittynyt maksukonfiguraatio hinnoittelua, desimaaleja ja tuotteita varten.

Kaikki kentät ovat valinnaisia.

products (Product[]) - Tuotteiden taulukko 'cart'- tai 'buyNow'-tiloille. Vaaditaan käytettäessä näitä tiloja. Jokaisella tuotteella on:
- id (merkkijono, vaaditaan) - Yksilöllinen tuotetunniste
- name (merkkijono, vaaditaan) - Käyttäjälle näytettävä tuotteen nimi
- quantity (numero, vaaditaan) - Tämän tuotteen määrä
- price (numero, valinnainen) - Yksikköhinta USD:na
- unitAmount (numero, valinnainen) - Vaihtoehto price-kentälle
- description (merkkijono, valinnainen) - Tuotteen kuvaus
solPriceUsd (number) - Kiinteä SOL-hinta USD:na. Käytä tätä testaukseen tai kun haluat lukita SOL-hinnan. Jos arvoa ei anneta, komponentti hakee nykyisen hinnan CoinGeckosta.
getSolPrice (() => Promise<number>) - Mukautettu funktio SOL-hinnan hakemiseen. Käytä tätä:
- Yksityisiin hintaoraakkeleihin
- Julkisten API-pyyntörajoitusten välttämiseen
- Mukautettuun hinnoittelulogiikkaan
- Yrityskäyttöön
Jos arvoa ei anneta, oletuksena käytetään CoinGeckon julkista API:a yhden minuutin välimuistilla.
tokenDecimals ({ [currency: string]: number }) - Ohita tokenin desimaalitarkkuus. Hyödyllinen mukautetuille tokeneille. Esimerkki:
```
tokenDecimals: {
  'CUSTOM': 8,
  'USDC': 6  // Can override defaults
}
```
fallbackSolPriceUsd (number) - Varahinta SOL:lle, jos hinta-API epäonnistuu eikä välimuistia ole saatavilla. Ilman tätä maksukäyttöliittymä näyttää virheen, jos hinnan haku epäonnistuu.

Sisäiset hookit

PaymentButton-komponentti käyttää useita sisäisiä hookeja tilan hallintaan ja arvojen laskemiseen:

`useTheme(theme?: ThemeConfig)`

Yhdistää käyttäjän antaman teemakonfiguraation oletusteema-arvoihin. Palauttaa täydellisen ThemeConfig-objektin, jossa kaikki kentät on täytetty.

Oletusteema-arvot:

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

Koukku on memoizoitu ja laskee uudelleen vain, kun teeman konfiguraatio muuttuu.

`useTotalAmount(mode, paymentConfig?)`

Laskee maksun kokonaissumman kaupankäyntitilan ja tuotteiden perusteella.

Toiminta tilasta riippuen:

'tip'-tila - Palauttaa 0 (käyttäjä määrittää summan)
'cart'- ja 'buyNow'-tilat - Laskee yhteen price * quantity kaikille tuotteille kohteessa paymentConfig.products

Koukku käsittelee poikkeustilanteet:

Puuttuvat tai virheelliset hinnat oletuksena 0
Puuttuvat tai virheelliset määrät oletuksena 0
Varmistaa, että kaikki arvot ovat äärellisiä lukuja
Tukee sekä price- että unitAmount-tuotekenttiä

Palauttaa kokonaissumman numerona (USD:nä ostoskorille/buyNow:lle, 0 juomarahalle).

`usePaymentUrl(merchant, amount, mode)`

Luo Solana Pay -URL:n maksua varten. Tämä URL voidaan koodata QR-koodiksi mobiililompakon skannausta varten.

Palauttaa: solana:-protokollan URL:n kyselyparametreilla:

recipient - Kauppiaan lompakko-osoite
amount - Maksun summa
reference - Yksilöllinen maksuun liittyvä viite (luotu aikaleimasta + satunnainen merkkijono)
label - Kauppiaan nimi (URL-turvallisesti käsitelty)
message - Tilaan perustuva kontekstuaalinen viesti

Palauttaa tyhjän merkkijonon, jos kauppiaan lompakko on virheellinen tai summa on <= 0.

Turvallisuus: Kauppiaan nimi käsitellään käyttäen sanitizeString() XSS-hyökkäysten estämiseksi URL-injektoinnin kautta.

Validointi ja virheiden käsittely

Komponentti suorittaa validoinnin ennen renderöintiä:

Lompakon validointi - Käyttää isAddress() funktiota kohteesta gill kauppiaan lompakko-osoitteen validointiin. Jos osoite on virheellinen, renderöi virhetilan maksukäyttöliittymän sijaan.
Hinnoittelun validointi - Varmistaa, että kelvollinen hinnoittelu on määritetty:
- 'tip'-tilassa: Aina kelvollinen (käyttäjä valitsee summan)
- 'cart'- ja 'buyNow'-tiloissa: Validoi, että totalAmount > 0
SSR-turvallisuus - Käyttää asiakaspuolen tunnistusta hydraatiovirheiden estämiseksi. isClient-tila varmistaa, että vain selaimessa toimivat ominaisuudet (kuten localStorage lompakon pysyvyyteen) suoritetaan vain asiakaspuolella.

Komponenttiarkkitehtuuri

PaymentButton käärii kaikki lapset kahteen kontekstipalveluntarjoajaan:

AppProvider - Tarjoaa lompakon yhteystilan ja liittimen asiakkaan
- Automaattinen yhdistäminen: oletuksena pois käytöstä
- Tallennus: Käyttää localStorage:ta, kun saatavilla (vain asiakaspuolella)
- Virheenkorjaustila: määritettävissä konfiguraation kautta
ArcProvider - Tarjoaa Solana-lohkoketjuasiakkaan ja RPC-yhteyden
- Verkko: Määräytyy config.network:n perusteella
- RPC-URL: Käyttää palvelinpuolen selvitystä varalla julkisiin päätepisteiden

RPC-URL:n selvitys

Komponentti sisältää kehittyneen RPC-URL:n selvityksen:

Jos config.rpcUrl on annettu, sitä käytetään suoraan
Muussa tapauksessa se kutsuu palvelinpuolen selvittäjää, joka valitsee luotettavat päätepisteet
Palaa https://api.mainnet-beta.solana.com:iin, jos selvitys epäonnistuu
Selvitys tapahtuu asynkronisesti asennuksen yhteydessä ja päivittää tilan

Renderöintitilat

Päällystila (position: 'overlay' tai oletus):

Renderöi laukaisupainikkeen (mukautettu tai oletus)
Avaa maksukäyttöliittymän responsiivisessa modaalissa (työpöytä) tai laatikossa (mobiili)
Käyttää ResponsiveShell-komponenttia mukautuviin asetteluihin

Sisäänrakennettu tila (position: 'inline'):

Upottaa maksukäyttöliittymän suoraan sivulle
Laukaisupainiketta ei tarvita
Hyödyllinen omistettuihin kassasivuihin

Molemmat tilat käyttävät SecureIframeShell:ta sisäisesti maksukäyttöliittymän renderöimiseen eristetyssä iframessa turvallisuuden vuoksi.

Käyttöesimerkit

Perusmaksu

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

Tippivimpain mukautetulla hinnanhakijalla

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

Ostoskori mukautetulla teemalla

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

Mukautettu laukaisupainike

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

Sisällysluettelo