转账请求

转账请求是 Solana Pay 集成中最简单的形式。它们创建非交互式支付 URL，钱包可以直接使用这些 URL 来组合和发送交易，无需服务器。

概述

转账请求 URL 遵循以下格式:

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

基础 SOL 转账

创建一个简单的 SOL 支付请求:

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 代币转账

创建一个 USDC 支付请求:

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

必需参数

接收方

接收方的 Solana 钱包地址(base58 编码):

const recipient = address("FvJ8k8HhXp4a3zQyFMZd4FvEqcYdYE7gSZWxrEBRfBsB");

可选参数

金额

以用户友好单位(SOL 或代币单位)表示的支付金额:

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

如果省略,钱包将提示用户输入金额。

SPL 代币

对于代币转账,指定铸币地址:

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

引用

用于跟踪支付的唯一标识符。生成一个地址作为引用键：

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

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

消息

支付描述：

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

备注

链上备注（公开可见）：

const memo = "OrderId:12345";

二维码集成

使用内置的 createQR 函数生成二维码：

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

支付验证

使用商户客户端

查找和验证支付的最简单方法：

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

使用独立函数

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

监听支付（WebSocket）

推荐的方法 —— watchReference 通过 WebSocket 订阅，一旦匹配的交易到达即刻解析。无需轮询。

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

轮询支付（HTTP 后备）

如果 WebSocket 订阅不可用（例如某些 RPC 提供商），请使用 findReference 作为轮询方式：

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

完整示例

以下是包含二维码生成和支付监控的完整示例：

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

最佳实践

安全性

始终在服务器端验证支付
为每笔支付使用唯一的参考标识
验证交易金额和收款人
检查交易成功状态

用户体验

清晰显示支付金额和说明
提供支付状态更新
妥善处理钱包连接
同时支持二维码和直接链接

错误处理

处理钱包连接失败
为不支持的钱包提供备选方案
显示有用的错误消息
实现支付超时机制

常见用例

销售点

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

捐赠

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

电子商务结账

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

概述