Ροές Πληρωμών

Το πακέτο @solana-commerce/headless παρέχει συναρτήσεις ανεξάρτητες από framework για τη δημιουργία ροών πληρωμών εμπορίου. Αυτά τα εργαλεία βοηθούν στη δημιουργία αντικειμένων αιτημάτων πληρωμής, τη δημιουργία URLs Solana Pay και την επαλήθευση on-chain πληρωμών. Το πακέτο είναι σχεδιασμένο να λειτουργεί σε οποιοδήποτε περιβάλλον JavaScript: React, Vue, Svelte, vanilla JS, Node.js ή serverless functions.

Εγκατάσταση

pnpm add @solana-commerce/headless

Συναρτήσεις Αιτημάτων Πληρωμής

Αυτές οι συναρτήσεις δημιουργούν τυποποιημένα αντικείμενα αιτημάτων πληρωμής για διαφορετικά μοτίβα εμπορίου. Δεν εκτελούν καμία λειτουργία blockchain—απλώς δομούν δεδομένα για χρήση σε πορτοφόλια, URLs Solana Pay ή προσαρμοσμένα UI πληρωμών.

createBuyNowRequest()

Δημιουργεί ένα τυποποιημένο αίτημα πληρωμής για την αγορά ενός μόνο προϊόντος.

function createBuyNowRequest(
  recipient: string,
  product: any,
  options?: {
    memo?: string;
    label?: string;
    message?: string;
  }
): PaymentRequest;

Παράμετροι

• recipient (string, υποχρεωτικό) - Διεύθυνση πορτοφολιού εμπόρου (δημόσιο κλειδί Solana κωδικοποιημένο σε base58) που θα λάβει την πληρωμή.

• product (any, υποχρεωτικό) - Αντικείμενο προϊόντος που περιέχει:

  • price (number, υποχρεωτικό) - Τιμή προϊόντος. Η μονάδα εξαρτάται από το πλαίσιο (π.χ., lamport για SOL, μικρές μονάδες για tokens).
  • currency (string, υποχρεωτικό) - Νόμισμα πληρωμής. Μπορεί να είναι 'SOL' ή διεύθυνση mint token.
  • name (string, υποχρεωτικό) - Όνομα προϊόντος, χρησιμοποιείται για προεπιλεγμένο memo/label αν δεν παρέχεται.
  • Πρόσθετα πεδία (id, description, image κ.λπ.) μεταβιβάζονται στον πίνακα products.

• options (object, προαιρετικό) - Επιλογές προσαρμογής:

  • memo (string) - Σημείωση on-chain για τη συναλλαγή. Προεπιλογή: "Purchase: {product.name}".
  • label (string) - Ετικέτα εμφάνισης για το αίτημα πληρωμής (χρησιμοποιείται στο Solana Pay). Προεπιλογή: product.name.
  • message (string) - Μήνυμα επιτυχίας που εμφανίζεται μετά την πληρωμή. Προεπιλογή: "Thank you for purchasing {product.name}!".

Επιστρέφει

Ένα αντικείμενο PaymentRequest που περιέχει:

• recipient - Η διεύθυνση πορτοφολιού του εμπόρου
• amount - Η τιμή του προϊόντος (αντιγραφή από product.price)
• currency - Νόμισμα πληρωμής (αντιγραφή από product.currency)
• products - Πίνακας που περιέχει το μεμονωμένο προϊόν
• memo - Σημείωση συναλλαγής (επιλογή ή προεπιλογή: "Purchase: (product.name)")
• label - Ετικέτα πληρωμής (επιλογή ή προεπιλογή: "product.name")
• message - Μήνυμα επιτυχίας (επιλογή ή προεπιλογή: "Thank you for purchasing (product.name)!")

Παράδειγμα:

const payment = createBuyNowRequest(
  "merchant-wallet-address",
  {
    id: "prod_123",
    name: "Premium Subscription",
    price: 50000000, // 0.05 SOL in lamports
    currency: "SOL"
  },
  {
    label: "Premium Subscription",
    message: "Thank you for subscribing!"
  }
);

createCartRequest()

Δημιουργεί ένα αίτημα πληρωμής για πολλαπλά προϊόντα σε ένα καλάθι αγορών.

function createCartRequest(
  recipient: string,
  products: any[],
  options?: {
    memo?: string;
    label?: string;
    message?: string;
    currency?: string;
  }
): PaymentRequest;

Παράμετροι

• recipient (string, απαιτείται) - Διεύθυνση πορτοφολιού εμπόρου που θα λάβει την πληρωμή.

• products (any[], απαιτείται) - Πίνακας αντικειμένων προϊόντων.

• options (object, προαιρετικό) - Επιλογές προσαρμογής:

  • currency (string) - Νόμισμα πληρωμής για ολόκληρο το καλάθι.
  • memo (string) - Σημείωση on-chain. Προεπιλογή: "Cart purchase (products.length items)".
  • label (string) - Ετικέτα πληρωμής. Προεπιλογή: "Cart Checkout".
  • message (string) - Μήνυμα επιτυχίας. Προεπιλογή: "Thank you for your purchase!".

Επιστρέφει

Ένα αντικείμενο PaymentRequest με:

• recipient - Η διεύθυνση πορτοφολιού του εμπόρου
• amount - Άθροισμα όλων των τιμών προϊόντων (products.reduce((sum, p) => sum + p.price, 0))
• currency - Νόμισμα πληρωμής (από τις επιλογές ή undefined)
• products - Ο πίνακας των προϊόντων
• memo, label, message - Τιμές επιλογών ή προεπιλογές

Παράδειγμα:

const cart = createCartRequest(
  "merchant-wallet-address",
  [
    { id: "1", name: "Product A", price: 25 },
    { id: "2", name: "Product B", price: 15 },
    { id: "3", name: "Product C", price: 10 }
  ],
  {
    currency: "USDC",
    label: "My Store Checkout",
    message: "Thank you for your order!"
  }
);
// cart.amount === 50 (sum of prices)

createTipRequest()

Δημιουργεί ένα αίτημα πληρωμής για φιλοδωρήματα ή δωρεές με ποσό που ορίζεται από τον χρήστη.

function createTipRequest(
  recipient: string,
  amount: number,
  options?: {
    currency?: string;
    memo?: string;
    label?: string;
    message?: string;
  }
): PaymentRequest;

Παράμετροι

• recipient (string, απαιτείται) - Διεύθυνση πορτοφολιού του παραλήπτη του φιλοδωρήματος (δημιουργός, streamer, φιλανθρωπικός οργανισμός κ.λπ.).

• amount (number, απαιτείται) - Ποσό φιλοδωρήματος. Η μονάδα εξαρτάται από το νόμισμα (lamport για SOL, μικρότερες μονάδες για tokens).

• options (object, προαιρετικό) - Επιλογές προσαρμογής:

  • currency (string) - Νόμισμα πληρωμής. Προεπιλογή: undefined (συνήθως αντιμετωπίζεται ως SOL από τους καταναλωτές).
  • memo (string) - Σημείωση on-chain. Προεπιλογή: "Thank you for your support!".
  • label (string) - Ετικέτα πληρωμής. Προεπιλογή: "Tip".
  • message (string) - Μήνυμα επιτυχίας. Προεπιλογή: "Thanks for the tip!".

Επιστρέφει

Ένα αντικείμενο PaymentRequest με:

• recipient - Η διεύθυνση πορτοφολιού του παραλήπτη του φιλοδωρήματος
• amount - Το ποσό του φιλοδωρήματος
• currency - Νόμισμα πληρωμής (από τις επιλογές ή undefined)
• memo, label, message - Τιμές επιλογών ή προεπιλογές

Παράδειγμα:

const tip = createTipRequest(
  "creator-wallet-address",
  5_000_000, // 0.005 SOL in lamports
  {
    currency: "SOL",
    label: "Tip for Content Creator",
    message: "Thanks for the support!"
  }
);

Συναρτήσεις Επαλήθευσης Πληρωμών

Αυτές οι συναρτήσεις αλληλεπιδρούν με το Solana για να επαληθεύσουν συναλλαγές και να περιμένουν για επιβεβαιώσεις. Απαιτούν έναν Solana RPC client από τη βιβλιοθήκη gill.

verifyPayment()

Επαληθεύει ότι μια συναλλαγή υπάρχει on-chain και προαιρετικά επικυρώνει το ποσό πληρωμής, τον παραλήπτη και το token.

async function verifyPayment(
  rpc: SolanaClient["rpc"],
  signatureString: string,
  expectedAmount?: number,
  expectedRecipient?: string,
  expectedMint?: string
): Promise<PaymentVerificationResult>;

Παράμετροι

• rpc (SolanaClient['rpc'], υποχρεωτικό) - RPC client από το gill. Δημιουργήστε με createSolanaClient(rpcUrl).rpc.

• signatureString (string, υποχρεωτικό) - Υπογραφή συναλλαγής (κωδικοποιημένη σε base58) προς επαλήθευση.

• expectedAmount (number, προαιρετικό) - Αναμενόμενο ποσό πληρωμής προς επικύρωση. Η μονάδα πρέπει να ταιριάζει με το νόμισμα:

  • Για SOL: lamport (1 SOL = 1.000.000.000 lamport)
  • Για SPL tokens: μικρές μονάδες βάσει των δεκαδικών του token (π.χ., το USDC χρησιμοποιεί 6 δεκαδικά)

  Αν δεν παρέχεται, η επικύρωση ποσού παραλείπεται.

• expectedRecipient (string, προαιρετικό) - Αναμενόμενη διεύθυνση πορτοφολιού παραλήπτη. Αν παρέχεται (μαζί με το expectedAmount), η συνάρτηση επικυρώνει ότι ο παραλήπτης έλαβε τουλάχιστον αυτό το ποσό. Αν δεν παρέχεται, η επικύρωση παραλείπεται.

• expectedMint (string, προαιρετικό) - Διεύθυνση mint του SPL token. Απαιτείται μόνο για μεταφορές SPL token. Αν δεν παρέχεται, η συνάρτηση προϋποθέτει μεταφορά SOL.

Επιστρέφει

Ένα αντικείμενο Promise<PaymentVerificationResult>:

interface PaymentVerificationResult {
  verified: boolean; // True if payment is valid
  signature?: string; // Transaction signature (echoed back)
  amount?: number; // Expected amount (echoed back)
  recipient?: string; // Expected recipient (echoed back)
  error?: string; // Error message if verification failed
}

Λογική Επαλήθευσης

Η συνάρτηση εκτελεί τους εξής ελέγχους:

1. Εγκυρότητα Υπογραφής: Ελέγχει ότι η υπογραφή είναι έγκυρη.

2. Ύπαρξη Συναλλαγής: Ανακτά τη συναλλαγή χρησιμοποιώντας rpc.getTransaction(). Αν δεν βρεθεί, επιστρέφει verified: false.

3. Κατάσταση Επιβεβαίωσης: Ελέγχει ότι η συναλλαγή έχει καταχωρηθεί on-chain.

4. Επικύρωση Μεταφοράς SOL (αν παρέχονται expectedRecipient και expectedAmount, και όχι expectedMint):

   • Βρίσκει τον δείκτη λογαριασμού του παραλήπτη στη συναλλαγή
   • Συγκρίνει preBalances και postBalances για να υπολογίσει τη μεταβολή υπολοίπου
   • Επαληθεύει ότι η μεταβολή είναι τουλάχιστον expectedAmount

5. Επικύρωση Μεταφοράς SPL Token (εάν παρέχεται expectedMint):

   • Παράγει τον Associated Token Account (ATA) του παραλήπτη τόσο για το Token Program όσο και για το Token-2022 Program
   • Ελέγχει το postTokenBalances για αντίστοιχο ATA με το αναμενόμενο mint
   • Επαληθεύει ότι το ποσό του token είναι τουλάχιστον expectedAmount

Ζητήματα Ασφαλείας

• Επαλήθευση από την Πλευρά του Πελάτη: Αυτή η συνάρτηση ανακτά δεδομένα συναλλαγών από το RPC. Μην εκθέτετε τη διεύθυνση URL του RPC σας στον πελάτη.
• Οριστικοποίηση: Η συνάρτηση ελέγχει για επιβεβαιωμένες συναλλαγές, αλλά για πληρωμές υψηλής αξίας, εξετάστε το ενδεχόμενο αναμονής για κατάσταση finalized.

Παράδειγμα:

import { verifyPayment } from "@solana-commerce/headless";
import { createSolanaClient } from "gill";

const client = createSolanaClient({
  urlOrMoniker: "mainnet"
});

const result = await verifyPayment(
  client.rpc,
  "transaction-signature-here",
  50_000_000, // 0.05 SOL in lamports
  "merchant-wallet-address"
  // No mint = SOL transfer
);

if (result.verified) {
  console.log("Payment confirmed!");
} else {
  console.error("Verification failed:", result.error);
}

waitForConfirmation()

Ερωτά επανειλημμένα το blockchain μέχρι μια συναλλαγή να φτάσει σε κατάσταση επιβεβαιωμένη ή οριστικοποιημένη, ή μέχρι να λήξει το χρονικό όριο.

async function waitForConfirmation(
  rpc: SolanaClient["rpc"],
  signatureStr: string,
  timeoutMs?: number
): Promise<boolean>;

Παράμετροι

• rpc (SolanaClient['rpc'], απαιτείται) - Πελάτης RPC από το gill.

• signatureStr (string, απαιτείται) - Υπογραφή συναλλαγής για την οποία θα αναμείνει.

• timeoutMs (number, προαιρετικό) - Μέγιστος χρόνος αναμονής σε χιλιοστά του δευτερολέπτου. Προεπιλογή: 30000 (30 δευτερόλεπτα).

Επιστρέφει

• Promise<boolean> - Επιστρέφει true εάν η συναλλαγή φτάσει σε κατάσταση confirmed ή finalized εντός του χρονικού ορίου, διαφορετικά false.

Παράδειγμα:

import { waitForConfirmation } from "@solana-commerce/headless";
import { createSolanaClient } from "gill";

const client = createSolanaClient({
  urlOrMoniker: "mainnet"
});

// After sending transaction
const signature = await wallet.sendTransaction(transaction);

// Wait for confirmation (30 second timeout)
const confirmed = await waitForConfirmation(client.rpc, signature, 30000);

if (confirmed) {
  console.log("Transaction confirmed!");
} else {
  console.log("Timeout - transaction not confirmed within 30 seconds");
}

Συναρτήσεις Solana Pay

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

createSolanaPayRequest()

Δημιουργεί μια διεύθυνση URL Solana Pay και έναν κωδικό QR με στυλ.

async function createSolanaPayRequest(
  request: TransferRequestURLFields,
  options: SolanaPayRequestOptions
): Promise<{ url: URL; qr: string }>;

Παράμετροι

• request (TransferRequestURLFields, απαιτείται) - Πεδία αιτήματος μεταφοράς Solana Pay:

  • recipient - Δημόσιο κλειδί παραλήπτη (χρησιμοποιήστε createRecipient(address) από το @solana-commerce/solana-pay)
  • amount - (προαιρετικό) Ποσό πληρωμής σε μικρές μονάδες (lamports για SOL)
  • splToken (προαιρετικό) - Δημόσιο κλειδί mint token SPL (χρησιμοποιήστε createSPLToken(address))
  • reference (προαιρετικό) - Δημόσιο κλειδί αναφοράς για παρακολούθηση
  • label (προαιρετικό) - Όνομα εμπόρου
  • message (προαιρετικό) - Μήνυμα επιτυχίας
  • memo (προαιρετικό) - Σημείωση στο blockchain

• options (SolanaPayRequestOptions, υποχρεωτικό) - Επιλογές στυλ κώδικα QR:

  • size (αριθμός) - Πλάτος/ύψος κώδικα QR σε pixels. Προεπιλογή: 256.
  • background (συμβολοσειρά) - Χρώμα φόντου (hex/rgb). Προεπιλογή: 'white'.
  • color (συμβολοσειρά) - Χρώμα κώδικα QR (hex/rgb). Προεπιλογή: 'black'.
  • margin (αριθμός) - Περιθώριο γύρω από τον κώδικα QR σε modules.
  • errorCorrectionLevel ('L' | 'M' | 'Q' | 'H') - Επίπεδο διόρθωσης σφαλμάτων. Υψηλότερα επίπεδα επιτρέπουν μεγαλύτερη φθορά αλλά δημιουργούν πυκνότερους κώδικες.
  • logo (συμβολοσειρά) - URL εικόνας λογότυπου για ενσωμάτωση στο κέντρο του κώδικα QR.
  • logoSize (αριθμός) - Μέγεθος λογότυπου ως ποσοστό του μεγέθους του κώδικα QR.
  • logoBackgroundColor (συμβολοσειρά) - Χρώμα φόντου πίσω από το λογότυπο.
  • logoMargin (αριθμός) - Περιθώριο γύρω από το λογότυπο.
  • dotStyle ('dots' | 'rounded' | 'square') - Σχήμα των modules του κώδικα QR.
  • cornerStyle ('square' | 'rounded' | 'extra-rounded' | 'full-rounded' | 'maximum-rounded') - Σχήμα των γωνιακών δεικτών.

Επιστρέφει

Ένα Promise που επιλύεται σε ένα αντικείμενο:

• url (URL) - URL Solana Pay (π.χ., solana:recipient?amount=10&spl-token=...)
• qr (συμβολοσειρά) - Data URL της εικόνας του κώδικα QR κωδικοποιημένο σε Base64 (χρησιμοποιήστε ως <img src={qr} />)

Παράδειγμα:

import {
  createSolanaPayRequest,
  createRecipient,
  createSPLToken
} from "@solana-commerce/solana-pay";

const payment = await createSolanaPayRequest(
  {
    recipient: createRecipient("merchant-wallet-address"),
    amount: 10_000_000, // 0.01 SOL in lamports
    splToken: createSPLToken("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"), // USDC
    label: "My Store",
    message: "Thank you for your purchase!"
  },
  {
    size: 400,
    background: "#FFFFFF",
    color: "#000000",
    logo: "/logo.png",
    logoSize: 20,
    errorCorrectionLevel: "H"
  }
);

// Display QR code
document.getElementById("qr").src = payment.qr;
console.log(payment.url.toString()); // solana:merchant...?amount=10000000&spl-token=...