PaymentButton

Το PaymentButton component είναι ένα React component που παρέχει μια ολοκληρωμένη διεπαφή πληρωμών για την αποδοχή πληρωμών Solana. Χειρίζεται εσωτερικά τη σύνδεση πορτοφολιού, την επιλογή token, την επεξεργασία συναλλαγών και τη διαχείριση κατάστασης UI. Από προεπιλογή, έρχεται με προσαρμόσιμα κουμπιά και modals:

Κουμπί Φιλοδωρήματος

Κουμπί Φιλοδωρήματος

Modal Πληρωμής

Modal Πληρωμής

Modal QR Code Solana Pay

Modal Καλαθιού

Εγκατάσταση

pnpm add @solana-commerce/kit

Props του Component

PaymentButtonProps

Το PaymentButton component δέχεται τα ακόλουθα props:

Υποχρεωτικά Props

• config (SolanaCommerceConfig) - Κύριο αντικείμενο διαμόρφωσης για το payment component. Αυτό είναι το μόνο υποχρεωτικό prop. Δείτε SolanaCommerceConfig παρακάτω.

Προαιρετικά Props

• paymentConfig (PaymentConfig) - Διαμόρφωση ειδική για την πληρωμή που περιλαμβάνει προϊόντα, παρακάμψεις τιμολόγησης και προσαρμοσμένα price fetchers. Δείτε PaymentConfig παρακάτω.

• onPayment ((amount: number, currency: string) => void) - Καλείται όταν μια πληρωμή ξεκινά αφού ο χρήστης επιβεβαιώσει το ποσό και το νόμισμα. Λαμβάνει το ποσό πληρωμής (σε μονάδες token, όχι lamports) και το αναγνωριστικό νομίσματος.

• onPaymentStart (() => void) - Καλείται όταν ξεκινά η ροή πληρωμής, πριν υποβληθεί η πραγματική συναλλαγή. Χρησιμοποιήστε το για να εμφανίσετε καταστάσεις φόρτωσης ή παρακολούθηση analytics.

• onPaymentSuccess ((signature: string) => void) - Καλείται όταν η συναλλαγή επιβεβαιωθεί on-chain. Λαμβάνει την υπογραφή της συναλλαγής. Εδώ θα πρέπει να ενημερώσετε την κατάσταση της παραγγελίας, να στείλετε emails επιβεβαίωσης κ.λπ.

• onPaymentError ((error: Error) => void) - Καλείται όταν η πληρωμή αποτύχει σε οποιοδήποτε στάδιο (σύνδεση πορτοφολιού, υποβολή συναλλαγής ή επιβεβαίωση). Το αντικείμενο σφάλματος περιέχει λεπτομέρειες για το τι πήγε στραβά.

• onCancel (() => void) - Καλείται όταν ο χρήστης ακυρώνει ρητά τη ροή πληρωμής (κλείνει το modal ή κάνει κλικ στο κουμπί ακύρωσης).

• children (React.ReactNode) - Προαιρετικό προσαρμοσμένο στοιχείο ενεργοποίησης. Εάν παρέχεται, αντικαθιστά το προεπιλεγμένο κουμπί πληρωμής. Το θυγατρικό στοιχείο πρέπει να είναι κλικάρισμο (π.χ., ένα κουμπί).

• className (string) - Όνομα κλάσης CSS που εφαρμόζεται στο κουμπί ενεργοποίησης (χρησιμοποιείται μόνο όταν δεν παρέχονται προσαρμοσμένα θυγατρικά στοιχεία).

• style (React.CSSProperties) - Ενσωματωμένα στυλ που εφαρμόζονται στο κουμπί ενεργοποίησης (χρησιμοποιείται μόνο όταν δεν παρέχονται προσαρμοσμένα θυγατρικά στοιχεία).

• variant ('default' | 'icon-only') - Παραλλαγή κουμπιού. Η προεπιλογή εμφανίζει κείμενο και εικονίδιο, το 'icon-only' εμφανίζει μόνο το εικονίδιο πληρωμής.

Αντικείμενα Διαμόρφωσης

SolanaCommerceConfig

Το κύριο αντικείμενο διαμόρφωσης που μεταβιβάζεται στο config prop.

Υποχρεωτικά Πεδία

• merchant (MerchantConfig) - Πληροφορίες εμπόρου και λεπτομέρειες παραλήπτη πληρωμής. Δείτε MerchantConfig.

• mode ('cart' | 'tip' | 'buyNow') - Λειτουργία πληρωμής που καθορίζει το κείμενο εμφάνισης του κουμπιού και τη ροή UI:

  • 'buyNow' - Αγορά μεμονωμένου προϊόντος με σταθερό ποσό
  • 'cart' - Καλάθι αγορών με πολλαπλά προϊόντα
  • 'tip' - Ο χρήστης επιλέγει το δικό του ποσό (δωρεές/φιλοδωρήματα)

Προαιρετικά Πεδία

• position ('inline' | 'overlay') - Πώς εμφανίζεται η διεπαφή πληρωμής. Η προεπιλογή είναι 'overlay'.

  • 'overlay' - Ανοίγει σε επικάλυψη modal/drawer
  • 'inline' - Ενσωματωμένο απευθείας στη σελίδα

• theme (ThemeConfig) - Επιλογές οπτικής προσαρμογής. Δείτε ThemeConfig.

• network ('mainnet' | 'devnet' | 'testnet') - Δίκτυο Solana προς χρήση. Η προεπιλογή είναι 'mainnet'.

• rpcUrl (string) - Προσαρμοσμένη διεύθυνση URL τελικού σημείου RPC. Εάν δεν παρέχεται, χρησιμοποιεί ένα προεπιλεγμένο δημόσιο τελικό σημείο για το επιλεγμένο δίκτυο.

• allowedMints (string[]) - Πίνακας διευθύνσεων mint token για περιορισμό μεθόδων πληρωμής. Εάν δεν παρέχεται, όλα τα υποστηριζόμενα tokens (SOL, USDC, USDT) είναι διαθέσιμα.

• showQR (boolean) - Εάν θα εμφανίζεται η επιλογή πληρωμής με κωδικό QR. Χρήσιμο για κινητά και ενσωμάτωση Solana Pay.

• enableWalletConnect (boolean) - Καθορίζει εάν θα ενεργοποιηθεί η σύνδεση πορτοφολιού. Ορίστε το σε false εάν διαχειρίζεστε τη σύνδεση πορτοφολιού εξωτερικά.

• showMerchantInfo (boolean) - Καθορίζει εάν θα εμφανίζεται το όνομα και το λογότυπο του εμπόρου στη διεπαφή πληρωμής.

• debug (boolean) - Ενεργοποιεί λεπτομερή καταγραφή στην κονσόλα για αποσφαλμάτωση.

MerchantConfig

Καθορίζει τον παραλήπτη πληρωμής και τις επιχειρηματικές πληροφορίες.

Υποχρεωτικά Πεδία

• name (string) - Όνομα επιχείρησης ή εμπόρου που εμφανίζεται στους χρήστες κατά τη διαδικασία ολοκλήρωσης αγοράς.

• wallet (string) - Διεύθυνση πορτοφολιού Solana που θα λαμβάνει τις πληρωμές. Πρέπει να είναι έγκυρη διεύθυνση Solana κωδικοποιημένη σε base58.

Προαιρετικά Πεδία

• logo (string) - URL εικόνας λογοτύπου εμπόρου. Εμφανίζεται στη διεπαφή πληρωμής όταν το showMerchantInfo είναι ενεργοποιημένο.

• description (string) - Περιγραφή επιχείρησης που εμφανίζεται στους χρήστες.

ThemeConfig

Οπτική προσαρμογή για τη διεπαφή πληρωμής.

Όλα τα πεδία είναι προαιρετικά και έχουν λογικές προεπιλογές.

• primaryColor (string) - Κύριο χρώμα επωνυμίας που χρησιμοποιείται για κουμπιά και τονισμούς. Προεπιλογή: '#9945FF' (μωβ Solana).

• secondaryColor (string) - Δευτερεύον χρώμα τονισμού. Προεπιλογή: '#14F195' (πράσινο Solana).

• backgroundColor (string) - Χρώμα φόντου παραθύρου/περιέκτη. Προεπιλογή: '#ffffff'.

• textColor (string) - Κύριο χρώμα κειμένου. Προεπιλογή: '#111827'.

• borderRadius ('none' | 'sm' | 'md' | 'lg' | 'xl' | 'full') - Ακτίνα στρογγυλοποίησης που εφαρμόζεται στα στοιχεία της διεπαφής. Προεπιλογή: 'lg'.

  • 'none' = 0px
  • 'sm' = 12px
  • 'md' = 16px
  • 'lg' = 20px
  • 'xl' = 24px
  • 'full' = Πλήρως στρογγυλεμένο (ανάλογα με το πλαίσιο)

• fontFamily (string) - Οικογένεια γραμματοσειράς για όλο το κείμενο. Προεπιλογή: 'system-ui, -apple-system, sans-serif'.

• buttonShadow ('none' | 'sm' | 'md' | 'lg' | 'xl') - Σκιά για τα κουμπιά. Προεπιλογή: 'md'.

• buttonBorder ('none' | 'black-10') - Στυλ περιγράμματος για τα κουμπιά. Προεπιλογή: 'black-10' (διακριτικό μαύρο περίγραμμα).

PaymentConfig

Προηγμένη διαμόρφωση πληρωμών για τιμολόγηση, δεκαδικά ψηφία και προϊόντα.

Όλα τα πεδία είναι προαιρετικά.

• products (Product[]) - Πίνακας προϊόντων για τις λειτουργίες 'cart' ή 'buyNow'. Απαιτείται όταν χρησιμοποιούνται αυτές οι λειτουργίες. Κάθε προϊόν έχει:

  • id (string, απαιτείται) - Μοναδικό αναγνωριστικό προϊόντος
  • name (string, απαιτείται) - Όνομα προϊόντος που εμφανίζεται στον χρήστη
  • quantity (number, απαιτείται) - Ποσότητα αυτού του προϊόντος
  • price (number, προαιρετικό) - Τιμή ανά μονάδα σε USD
  • unitAmount (number, προαιρετικό) - Εναλλακτική στο πεδίο price
  • description (string, προαιρετικό) - Περιγραφή προϊόντος

• solPriceUsd (number) - Σταθερή τιμή SOL σε USD. Χρησιμοποιήστε το για δοκιμές ή όταν θέλετε να κλειδώσετε την τιμή του SOL. Εάν δεν παρέχεται, το component ανακτά την τρέχουσα τιμή από το CoinGecko.

• getSolPrice (() => Promise<number>) - Προσαρμοσμένη συνάρτηση για ανάκτηση της τιμής του SOL. Χρησιμοποιήστε το για:

  • Ιδιωτικά oracles τιμών
  • Αποφυγή ορίων ρυθμού δημόσιων API
  • Προσαρμοσμένη λογική τιμολόγησης
  • Εταιρικές εφαρμογές

  Εάν δεν παρέχεται, χρησιμοποιεί από προεπιλογή το δημόσιο API του CoinGecko με cache 1 λεπτού.

• tokenDecimals ({ [currency: string]: number }) - Παράκαμψη της ακρίβειας δεκαδικών ψηφίων του token. Χρήσιμο για προσαρμοσμένα tokens. Παράδειγμα:

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

• fallbackSolPriceUsd (number) - Εφεδρική τιμή SOL εάν το API τιμών αποτύχει και δεν υπάρχει διαθέσιμη cache. Χωρίς αυτό, η διεπαφή πληρωμών θα εμφανίσει σφάλμα εάν η ανάκτηση τιμής αποτύχει.

Εσωτερικά Hooks

Το component PaymentButton χρησιμοποιεί διάφορα εσωτερικά hooks για τη διαχείριση κατάστασης και τον υπολογισμό τιμών:

useTheme(theme?: ThemeConfig)

Συγχωνεύει τη διαμόρφωση θέματος που παρέχεται από τον χρήστη με τις προεπιλεγμένες τιμές θέματος. Επιστρέφει ένα πλήρες αντικείμενο ThemeConfig με όλα τα πεδία συμπληρωμένα.

Προεπιλεγμένες τιμές θέματος:

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

Το hook είναι memoized και επαναυπολογίζεται μόνο όταν αλλάζει η διαμόρφωση του θέματος.

useTotalAmount(mode, paymentConfig?)

Υπολογίζει το συνολικό ποσό πληρωμής με βάση τη λειτουργία εμπορίου και τα προϊόντα.

Συμπεριφορά ανά λειτουργία:

• Λειτουργία 'tip' - Επιστρέφει 0 (το ποσό καθορίζεται από τον χρήστη)
• Λειτουργίες 'cart' και 'buyNow' - Αθροίζει το price * quantity για όλα τα προϊόντα στο paymentConfig.products

Το hook διαχειρίζεται ακραίες περιπτώσεις:

• Οι ελλιπείς ή μη έγκυρες τιμές προεπιλέγονται σε 0
• Οι ελλιπείς ή μη έγκυρες ποσότητες προεπιλέγονται σε 0
• Διασφαλίζει ότι όλες οι τιμές είναι πεπερασμένοι αριθμοί
• Υποστηρίζει τόσο τα πεδία προϊόντων price όσο και unitAmount

Επιστρέφει το συνολικό ποσό ως αριθμό (σε USD για cart/buyNow, 0 για tip).

usePaymentUrl(merchant, amount, mode)

Δημιουργεί ένα URL Solana Pay για την πληρωμή. Αυτό το URL μπορεί να κωδικοποιηθεί ως κωδικός QR για σάρωση από κινητό πορτοφόλι.

Επιστρέφει: Ένα URL πρωτοκόλλου solana: με παραμέτρους ερωτήματος για:

• recipient - Διεύθυνση πορτοφολιού εμπόρου
• amount - Ποσό πληρωμής
• reference - Μοναδική αναφορά πληρωμής (δημιουργείται από χρονική σήμανση + τυχαία συμβολοσειρά)
• label - Όνομα εμπόρου (απολυμασμένο για ασφάλεια URL)
• message - Μήνυμα βάσει πλαισίου ανάλογα με τη λειτουργία

Επιστρέφει κενή συμβολοσειρά εάν το πορτοφόλι του εμπόρου είναι μη έγκυρο ή το ποσό είναι <= 0.

Ασφάλεια: Το όνομα του εμπόρου απολυμαίνεται χρησιμοποιώντας sanitizeString() για την πρόληψη επιθέσεων XSS μέσω εισαγωγής URL.

Επικύρωση & Διαχείριση Σφαλμάτων

Το στοιχείο εκτελεί επικύρωση πριν από την απόδοση:

1. Επικύρωση Πορτοφολιού - Χρησιμοποιεί το isAddress() από το gill για την επικύρωση της διεύθυνσης πορτοφολιού του εμπόρου. Εάν είναι μη έγκυρη, αποδίδει μια κατάσταση σφάλματος αντί του UI πληρωμής.

2. Επικύρωση Τιμολόγησης - Διασφαλίζει ότι έχει διαμορφωθεί έγκυρη τιμολόγηση:

   • Για λειτουργία 'tip': Πάντα έγκυρη (ο χρήστης επιλέγει το ποσό)
   • Για λειτουργίες 'cart' και 'buyNow': Επικυρώνει ότι totalAmount > 0

3. Ασφάλεια SSR - Χρησιμοποιεί ανίχνευση από την πλευρά του πελάτη για την αποφυγή ασυμφωνιών ενυδάτωσης. Η κατάσταση isClient διασφαλίζει ότι οι λειτουργίες που είναι διαθέσιμες μόνο στον περιηγητή (όπως το localStorage για τη διατήρηση του πορτοφολιού) εκτελούνται μόνο στον πελάτη.

Αρχιτεκτονική Στοιχείων

Το PaymentButton τυλίγει όλα τα θυγατρικά στοιχεία σε δύο παρόχους περιβάλλοντος:

1. AppProvider - Παρέχει την κατάσταση σύνδεσης του πορτοφολιού και τον πελάτη του συνδέσμου

   • Αυτόματη σύνδεση: απενεργοποιημένη από προεπιλογή
   • Αποθήκευση: Χρησιμοποιεί το localStorage όταν είναι διαθέσιμο (μόνο από την πλευρά του πελάτη)
   • Λειτουργία αποσφαλμάτωσης: διαμορφώσιμη μέσω της παραμετροποίησης

2. ArcProvider - Παρέχει τον πελάτη blockchain Solana και τη σύνδεση RPC

   • Δίκτυο: Καθορίζεται από το config.network
   • URL RPC: Χρησιμοποιεί επίλυση από την πλευρά του διακομιστή με εναλλακτική λύση σε δημόσια endpoints

Επίλυση URL RPC

Το στοιχείο περιλαμβάνει εξελιγμένη επίλυση URL RPC:

• Εάν παρέχεται το config.rpcUrl, χρησιμοποιείται απευθείας
• Διαφορετικά, καλεί έναν επιλύτη από την πλευρά του διακομιστή που επιλέγει αξιόπιστα endpoints
• Επιστρέφει στο https://api.mainnet-beta.solana.com εάν η επίλυση αποτύχει
• Η επίλυση πραγματοποιείται ασύγχρονα κατά την προσάρτηση και ενημερώνει την κατάσταση

Λειτουργίες Απόδοσης

Λειτουργία επικάλυψης (position: 'overlay' ή προεπιλογή):

• Αποδίδει ένα κουμπί ενεργοποίησης (προσαρμοσμένο ή προεπιλεγμένο)
• Ανοίγει τη διεπαφή πληρωμής σε ένα ανταποκρινόμενο παράθυρο διαλόγου (desktop) ή συρτάρι (mobile)
• Χρησιμοποιεί το στοιχείο ResponsiveShell για προσαρμοστικές διατάξεις

Ενσωματωμένη λειτουργία (position: 'inline'):

• Ενσωματώνει τη διεπαφή πληρωμής απευθείας στη σελίδα
• Δεν απαιτείται κουμπί ενεργοποίησης
• Χρήσιμο για αποκλειστικές σελίδες ολοκλήρωσης αγοράς

Και οι δύο λειτουργίες χρησιμοποιούν το SecureIframeShell εσωτερικά για την απόδοση της διεπαφής πληρωμής σε ένα απομονωμένο iframe για ασφάλεια.

Παραδείγματα Χρήσης

Βασική Πληρωμή

<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 Φιλοδωρήματος με Προσαρμοσμένο Ανακτήτη Τιμών

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

Καλάθι Αγορών με Προσαρμοσμένο Θέμα

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

Προσαρμοσμένο Κουμπί Ενεργοποίησης

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