Betalingsstromen

Het @solana-commerce/headless pakket biedt framework-onafhankelijke functies voor het bouwen van commerce betalingsstromen. Deze tools helpen bij het aanmaken van betalingsverzoek objecten, het genereren van Solana Pay URL's en het verifiëren van on-chain betalingen. Het pakket is ontworpen om in elke JavaScript-omgeving te werken: React, Vue, Svelte, vanilla JS, Node.js of serverless functies.

Installatie

pnpm add @solana-commerce/headless

Betalingsverzoek Functies

Deze functies creëren gestandaardiseerde betalingsverzoek objecten voor verschillende commerce patronen. Ze voeren geen blockchain-operaties uit—ze structureren simpelweg data voor gebruik in wallets, Solana Pay URL's of aangepaste betalings-UI's.

createBuyNowRequest()

Creëert een gestandaardiseerd betalingsverzoek voor een enkele productaankoop.

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

Parameters

• recipient (string, verplicht) - Handelaar wallet-adres (base58-gecodeerde Solana public key) dat de betaling zal ontvangen.

• product (any, verplicht) - Product object met:

  • price (number, verplicht) - Productprijs. De eenheid hangt af van de context (bijv. lamport voor SOL, kleine eenheden voor tokens).
  • currency (string, verplicht) - Betalingsvaluta. Kan 'SOL' zijn of een token mint-adres.
  • name (string, verplicht) - Productnaam, gebruikt voor standaard memo/label indien niet opgegeven.
  • Extra velden (id, description, image, etc.) worden doorgegeven in de products array.

• options (object, optioneel) - Aanpassingsopties:

  • memo (string) - On-chain memo voor de transactie. Standaard: "Purchase: {product.name}".
  • label (string) - Weergavelabel voor het betalingsverzoek (gebruikt in Solana Pay). Standaard: product.name.
  • message (string) - Succesbericht getoond na betaling. Standaard: "Thank you for purchasing {product.name}!".

Retourneert

Een PaymentRequest object met:

• recipient - Het handelaar wallet-adres
• amount - De productprijs (gekopieerd van product.price)
• currency - Betalingsvaluta (gekopieerd van product.currency)
• products - Array met het enkele product
• memo - Transactiememo (optie of standaard: "Aankoop: (product.name)")
• label - Betalingslabel (optie of standaard: "product.name")
• message - Succesbericht (optie of standaard: "Bedankt voor het kopen van (product.name)!")

Voorbeeld:

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

Creëert een betalingsverzoek voor meerdere producten in een winkelwagen.

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

Parameters

• recipient (string, verplicht) - Wallet-adres van de verkoper dat de betaling zal ontvangen.

• products (any[], verplicht) - Array van productobjecten.

• options (object, optioneel) - Aanpassingsopties:

  • currency (string) - Betalingsvaluta voor de gehele winkelwagen.
  • memo (string) - On-chain memo. Standaard: "Cart purchase (products.length items)".
  • label (string) - Betalingslabel. Standaard: "Cart Checkout".
  • message (string) - Succesbericht. Standaard: "Thank you for your purchase!".

Retourneert

Een PaymentRequest-object met:

• recipient - Het wallet-adres van de verkoper
• amount - Som van alle productprijzen (products.reduce((sum, p) => sum + p.price, 0))
• currency - Betalingsvaluta (uit opties, of undefined)
• products - De array van producten
• memo, label, message - Optiewaarden of standaardwaarden

Voorbeeld:

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

Creëert een betalingsverzoek voor fooien of donaties met een door de gebruiker bepaald bedrag.

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

Parameters

• recipient (string, verplicht) - Wallet-adres van de fooiontvanger (maker, streamer, goed doel, etc.).

• amount (number, verplicht) - Fooibedrag. Eenheid hangt af van de valuta (lamports voor SOL, kleine eenheden voor tokens).

• options (object, optioneel) - Aanpassingsopties:

  • currency (string) - Betalingsvaluta. Standaard: undefined (wordt doorgaans door consumenten als SOL behandeld).
  • memo (string) - On-chain memo. Standaard: "Thank you for your support!".
  • label (string) - Betalingslabel. Standaard: "Tip".
  • message (string) - Succesbericht. Standaard: "Thanks for the tip!".

Retourneert

Een PaymentRequest-object met:

• recipient - Het wallet-adres van de fooiontvanger
• amount - Het fooibedrag
• currency - Betalingsvaluta (uit opties, of undefined)
• memo, label, message - Optiewaarden of standaardwaarden

Voorbeeld:

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!"
  }
);

Betalingsverificatiefuncties

Deze functies communiceren met Solana om transacties te verifiëren en te wachten op bevestigingen. Ze vereisen een Solana RPC-client uit de gill bibliotheek.

verifyPayment()

Verifieert dat een transactie on-chain bestaat en valideert optioneel het betalingsbedrag, de ontvanger en het token.

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

Parameters

• rpc (SolanaClient['rpc'], verplicht) - RPC-client uit gill. Maak aan met createSolanaClient(rpcUrl).rpc.

• signatureString (string, verplicht) - Transactiehandtekening (base58-gecodeerd) om te verifiëren.

• expectedAmount (number, optioneel) - Verwacht betalingsbedrag om te valideren. Eenheid moet overeenkomen met de valuta:

  • Voor SOL: lamport (1 SOL = 1.000.000.000 lamport)
  • Voor SPL-tokens: kleine eenheden gebaseerd op token-decimalen (bijv. USDC gebruikt 6 decimalen)

  Indien niet opgegeven, wordt bedragvalidatie overgeslagen.

• expectedRecipient (string, optioneel) - Verwacht ontvangerwalletadres. Indien opgegeven (samen met expectedAmount), valideert de functie dat de ontvanger ten minste dit bedrag heeft ontvangen. Indien niet opgegeven, wordt validatie overgeslagen.

• expectedMint (string, optioneel) - SPL-token mint-adres. Alleen vereist voor SPL-tokenoverdrachten. Indien niet opgegeven, gaat de functie uit van een SOL-overdracht.

Retourneert

Een Promise<PaymentVerificationResult> object:

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
}

Verificatielogica

De functie voert deze controles uit:

1. Handtekeninggeldigheid: Controleert of de handtekening geldig is.

2. Transactie-existentie: Haalt de transactie op met rpc.getTransaction(). Indien niet gevonden, retourneert verified: false.

3. Bevestigingsstatus: Controleert of de transactie on-chain is geland.

4. SOL-overdrachtsvalidatie (indien expectedRecipient en expectedAmount opgegeven, en geen expectedMint):

   • Vindt de accountindex van de ontvanger in de transactie
   • Vergelijkt preBalances en postBalances om het saldoverschil te berekenen
   • Verifieert dat het verschil ten minste expectedAmount is

5. SPL Token Transfer Validatie (indien expectedMint opgegeven):

   • Leidt het Associated Token Account (ATA) van de ontvanger af voor zowel het Token Program als het Token-2022 Program
   • Controleert postTokenBalances op een overeenkomend ATA met de verwachte mint
   • Verifieert dat het tokenbedrag minstens expectedAmount is

Beveiligingsoverwegingen

• Client-Side Verificatie: Deze functie haalt transactiegegevens op via RPC. Stel uw RPC URL niet bloot aan de client.
• Finalisatie: De functie controleert op bevestigde transacties, maar voor betalingen met een hoge waarde kunt u overwegen te wachten op finalized status.

Voorbeeld:

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

Pollt de blockchain totdat een transactie de status confirmed of finalized bereikt, of tot er een time-out optreedt.

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

Parameters

• rpc (SolanaClient['rpc'], verplicht) - RPC-client van gill.

• signatureStr (string, verplicht) - Transactiehandtekening om op te wachten.

• timeoutMs (number, optioneel) - Maximale wachttijd in milliseconden. Standaard: 30000 (30 seconden).

Retourneert

• Promise<boolean> - Retourneert true als de transactie de status confirmed of finalized bereikt binnen de time-out, anders false.

Voorbeeld:

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 Functies

Deze functies genereren Solana Pay URL's en gestileerde QR-codes voor scannen met mobiele wallets.

createSolanaPayRequest()

Creëert een Solana Pay URL en een gestileerde QR-code.

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

Parameters

• request (TransferRequestURLFields, verplicht) - Solana Pay transfer request velden:

  • recipient - Publieke sleutel van ontvanger (gebruik createRecipient(address) van @solana-commerce/solana-pay)
  • amount - (optioneel) Betalingsbedrag in kleinste eenheden (lamports voor SOL)
  • splToken (optioneel) - Publieke sleutel van SPL token mint (gebruik createSPLToken(address))
  • reference (optioneel) - Referentie publieke sleutel voor tracking
  • label (optioneel) - Naam van handelaar
  • message (optioneel) - Succesbericht
  • memo (optioneel) - On-chain memo

• options (SolanaPayRequestOptions, verplicht) - QR-code stijlopties:

  • size (number) - Breedte/hoogte van QR-code in pixels. Standaard: 256.
  • background (string) - Achtergrondkleur (hex/rgb). Standaard: 'white'.
  • color (string) - QR-code kleur (hex/rgb). Standaard: 'black'.
  • margin (number) - Marge rondom QR-code in modules.
  • errorCorrectionLevel ('L' | 'M' | 'Q' | 'H') - Foutcorrectieniveau. Hogere niveaus staan meer schade toe maar creëren dichtere codes.
  • logo (string) - Logo afbeeldings-URL om in het midden van de QR-code in te sluiten.
  • logoSize (number) - Logogrootte als percentage van de QR-code grootte.
  • logoBackgroundColor (string) - Achtergrondkleur achter het logo.
  • logoMargin (number) - Marge rondom het logo.
  • dotStyle ('dots' | 'rounded' | 'square') - Vorm van QR-code modules.
  • cornerStyle ('square' | 'rounded' | 'extra-rounded' | 'full-rounded' | 'maximum-rounded') - Vorm van hoekmarkeringen.

Retourneert

Een Promise die oplost naar een object:

• url (URL) - Solana Pay URL (bijv., solana:recipient?amount=10&spl-token=...)
• qr (string) - Base64-gecodeerde data-URL van de QR-code afbeelding (te gebruiken als <img src={qr} />)

Voorbeeld:

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