Siirtopyynnöt

Siirtopyynnöt ovat yksinkertaisin Solana Pay -integraation muoto. Ne luovat ei-interaktiivisia maksu-URL:eja, joiden avulla lompakot voivat suoraan koostaa ja lähettää tapahtumia ilman palvelinta.

Yleiskatsaus

Siirtopyynnön URL noudattaa tätä muotoa:

solana:<recipient>
      ?amount=<amount>
      &spl-token=<spl-token>
      &reference=<reference>
      &label=<label>
      &message=<message>
      &memo=<memo>

Perustason SOL-siirto

Luo yksinkertainen SOL-maksupyyntö:

import { address } from "@solana/kit";
import { encodeURL } from "@solana/pay";

// Recipient's Solana wallet address
const recipient = address("FvJ8k8HhXp4a3zQyFMZd4FvEqcYdYE7gSZWxrEBRfBsB");

// Create the payment URL
const url = encodeURL({
  recipient,
  amount: 0.01, // 0.01 SOL
  label: "My Store",
  message: "Thanks for your purchase!"
});

console.log(url.toString());
// Output: solana:FvJ8k8Hh...?amount=0.01&label=My%20Store&message=Thanks%20for%20your%20purchase!

SPL-token-siirto

Luo USDC-maksupyyntö:

import { address } from "@solana/kit";
import { encodeURL } from "@solana/pay";

// USDC mint address on mainnet
const usdcMint = address("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");

const url = encodeURL({
  recipient: address("FvJ8k8HhXp4a3zQyFMZd4FvEqcYdYE7gSZWxrEBRfBsB"),
  amount: 10.5, // $10.50 USDC
  splToken: usdcMint,
  label: "Coffee Shop",
  message: "Grande Latte + Tip"
});

console.log(url.toString());

URL-parametrit

Pakolliset parametrit

Vastaanottaja

Vastaanottajan Solana-lompakon osoite (base58-koodattu):

const recipient = address("FvJ8k8HhXp4a3zQyFMZd4FvEqcYdYE7gSZWxrEBRfBsB");

Valinnaiset parametrit

Määrä

Maksun määrä käyttäjäystävällisissä yksiköissä (SOL tai token-yksiköt):

// SOL amounts
const solAmount = 1.5; // 1.5 SOL
const smallAmount = 0.001; // 0.001 SOL

// Token amounts (USDC example)
const usdcAmount = 25.99; // $25.99 USDC

Jos määrää ei määritetä, lompakko pyytää käyttäjää syöttämään summan.

SPL-token

Token-siirroissa määritä mint-osoite:

// Common SPL tokens
const USDC = address("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");
const USDT = address("Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB");
// Omit splToken for native SOL transfers

Viite

Yksilölliset tunnisteet maksujen seurantaan. Luo osoite käytettäväksi viiteavaimena:

import { generateKeyPair, getAddressFromPublicKey } from "@solana/kit";

// Generate a unique reference
const keypair = await generateKeyPair();
const reference = await getAddressFromPublicKey(keypair.publicKey);

Tunniste

Käyttäjille näytettävä kauppiaan tai sovelluksen nimi:

const label = "Acme Coffee Shop";

Viesti

Maksun kuvaus:

const message = "Order #12345 - 2x Americano";

Muistiinpano

Lohkoketjumuistiinpano (julkisesti näkyvissä):

const memo = "OrderId:12345";

QR-koodin integrointi

Luo QR-koodeja käyttämällä sisäänrakennettua createQR-funktiota:

import { address } from "@solana/kit";
import { encodeURL, createQR } from "@solana/pay";

const url = encodeURL({
  recipient: address("FvJ8k8HhXp4a3zQyFMZd4FvEqcYdYE7gSZWxrEBRfBsB"),
  amount: 0.05,
  label: "Donation",
  message: "Support our project"
});

// Generate a QR code element
const qr = createQR(url);

// Append to DOM
const element = document.getElementById("qr-code");
qr.append(element);

Maksun vahvistus

Kauppias-asiakkaan käyttäminen

Yksinkertaisin tapa löytää ja vahvistaa maksuja:

import { address } from "@solana/kit";
import { createMerchantClient } from "@solana/pay";

const merchant = createMerchantClient({
  rpcUrl: "https://api.mainnet-beta.solana.com"
});

const recipient = address("FvJ8k8HhXp4a3zQyFMZd4FvEqcYdYE7gSZWxrEBRfBsB");
const reference = address("YOUR_REFERENCE_ADDRESS");

// Find the transaction by reference
const found = await merchant.pay.findReference(reference);

// Validate the transfer matches expected fields
await merchant.pay.validateTransfer(found.signature, {
  recipient,
  amount: 0.1
});

console.log("Payment confirmed!", found.signature);

Itsenäisten funktioiden käyttäminen

import { createSolanaRpc, address } from "@solana/kit";
import { findReference, validateTransfer } from "@solana/pay";

const rpc = createSolanaRpc("https://api.mainnet-beta.solana.com");
const reference = address("YOUR_REFERENCE_ADDRESS");

// Find transaction by reference
const found = await findReference(rpc, reference);

// Validate transaction details
await validateTransfer(rpc, found.signature, {
  recipient: address("FvJ8k8HhXp4a3zQyFMZd4FvEqcYdYE7gSZWxrEBRfBsB"),
  amount: 0.1
});

console.log("Payment confirmed!", found.signature);

Maksujen seuranta (WebSocket)

Suositeltu lähestymistapa — watchReference tilaa WebSocketin kautta ja ratkaisee heti, kun vastaava transaktio saapuu. Kyselyä ei tarvita.

async function waitForPayment(reference, recipient, amount) {
  const merchant = createMerchantClient({
    rpcUrl: "https://api.mainnet-beta.solana.com"
  });

  // Resolves on the first transaction mentioning this reference
  const result = await merchant.pay.watchReference(reference);

  if (result.err) {
    throw new Error(`Transaction failed: ${JSON.stringify(result.err)}`);
  }

  // Validate that the transaction matches the expected payment
  await merchant.pay.validateTransfer(result.signature, { recipient, amount });

  return { signature: result.signature };
}

Maksujen kysely (HTTP-varareitti)

Jos WebSocket-tilaukset eivät ole käytettävissä (esim. jotkin RPC-palveluntarjoajat), käytä varasuunnitelmana kyselyä findReference-komennolla:

async function pollForPayment(reference, recipient, amount) {
  const merchant = createMerchantClient({
    rpcUrl: "https://api.mainnet-beta.solana.com"
  });

  const checkPayment = async () => {
    try {
      const found = await merchant.pay.findReference(reference);
      await merchant.pay.validateTransfer(found.signature, {
        recipient,
        amount
      });
      return { success: true, signature: found.signature };
    } catch {
      return { success: false };
    }
  };

  // Check every 2 seconds
  return new Promise((resolve) => {
    const interval = setInterval(async () => {
      const result = await checkPayment();
      if (result.success) {
        clearInterval(interval);
        resolve(result);
      }
    }, 2000);
  });
}

Täydellinen esimerkki

Tässä on täydellinen esimerkki QR-koodin luomisesta ja maksun seurannasta:

import { address, generateKeyPair, getAddressFromPublicKey } from "@solana/kit";
import { encodeURL, createQR, createMerchantClient } from "@solana/pay";

const recipient = address("FvJ8k8HhXp4a3zQyFMZd4FvEqcYdYE7gSZWxrEBRfBsB");
const amount = 0.1;

// Generate unique reference for this payment
const keypair = await generateKeyPair();
const reference = await getAddressFromPublicKey(keypair.publicKey);

// Create payment URL and QR code
const url = encodeURL({
  recipient,
  amount,
  reference,
  label: "Demo Store",
  message: "Test Purchase"
});
const qr = createQR(url);
qr.append(document.getElementById("qr-code"));

// Monitor for payment
const merchant = createMerchantClient({
  rpcUrl: "https://api.mainnet-beta.solana.com"
});

const interval = setInterval(async () => {
  try {
    const found = await merchant.pay.findReference(reference);
    await merchant.pay.validateTransfer(found.signature, {
      recipient,
      amount,
      reference
    });
    clearInterval(interval);
    console.log("Payment confirmed!", found.signature);
  } catch {
    // Payment not found yet, keep polling
  }
}, 2000);

Parhaat käytännöt

Turvallisuus

Vahvista maksut aina palvelinpuolella
Käytä yksilöllisiä viitteitä jokaiselle maksulle
Tarkista tapahtumien summat ja vastaanottajat
Tarkista tapahtuman onnistumistila

Käyttäjäkokemus

Näytä selkeät maksusummat ja kuvaukset
Tarjoa maksun tilapäivitykset
Käsittele lompakon yhdistäminen sujuvasti
Tue sekä QR-koodeja että suoria linkkejä

Virheiden käsittely

Käsittele lompakon yhdistämisvirheet
Tarjoa varasuunnitelma tukemattomille lompakoille
Näytä selkeät virheilmoitukset
Toteuta maksujen aikakatkaisut

Yleiset käyttötapaukset

Myyntipiste

const posPayment = encodeURL({
  recipient: merchantWallet,
  amount: 15.99,
  label: "Local Coffee Shop",
  message: `Receipt #${receiptNumber}`,
  memo: `POS-${terminalId}-${Date.now()}`
});

Lahjoitukset

// Flexible donation amount (user enters amount in wallet)
const donationUrl = encodeURL({
  recipient: charityWallet,
  label: "Save the Ocean",
  message: "Support marine conservation"
});

Verkkokaupan kassa

const checkoutUrl = encodeURL({
  recipient: storeWallet,
  amount: cartTotal,
  reference: orderReference,
  label: storeName,
  message: `Order ${orderId}`,
  memo: `ORDER:${orderId}`
});

Sisällysluettelo