Tài liệu SolanaBắt Đầu Nhanh

Solana Pay

Gói @solana-commerce/solana-pay cung cấp đầy đủ chức năng Solana Pay để xây dựng trải nghiệm thanh toán, tương thích với thư viện gill và @solana/kit. Nó xử lý mã hóa/phân tích cú pháp URL, tạo mã QR với kiểu dáng tùy chỉnh, và xây dựng giao dịch cho cả chuyển khoản SOL và token SPL.

Cài đặt

pnpm add @solana-commerce/solana-pay

Mã hóa URL

encodeURL(fields)

Tạo một URL Solana Pay tuân thủ đặc tả Solana Pay. Hàm này tạo ra các URL giao thức solana: có thể được chia sẻ dưới dạng liên kết hoặc mã hóa thành mã QR để ví di động quét.

Tham số

  • fields (TransferRequestURLFields | TransactionRequestURLFields) - Cấu hình cho URL thanh toán

TransferRequestURLFields

Được sử dụng cho các yêu cầu thanh toán đơn giản (chuyển khoản trực tiếp):

  • recipient (Address, bắt buộc) - Địa chỉ ví của người bán (khóa công khai mã hóa base58) sẽ nhận thanh toán. Có thể là chuỗi hoặc kiểu Address từ gill.

  • amount (bigint, tùy chọn) - Số tiền thanh toán tính bằng lamport (đơn vị nguyên tử). Đối với SOL, 1 SOL = 1.000.000.000 lamport (9 chữ số thập phân). Đối với token SPL, sử dụng độ chính xác thập phân của token (ví dụ: USDC sử dụng 6 chữ số thập phân, vì vậy 1 USDC = 1.000.000).

  • splToken (Address, tùy chọn) - Địa chỉ mint của token SPL cho các khoản thanh toán bằng token. Nếu bỏ qua, thanh toán được coi là bằng SOL.

  • reference (Address | Address[], tùy chọn) - (Các) địa chỉ tham chiếu duy nhất được sử dụng để theo dõi thanh toán. Tạo bằng cách sử dụng generateKeyPairSigner().address. Tham chiếu được thêm vào dưới dạng tài khoản chỉ đọc vào giao dịch, cho phép bạn truy vấn các khoản thanh toán bằng cách sử dụng tham chiếu này.

  • label (string, tùy chọn) - Tên người bán hoặc ứng dụng dễ đọc hiển thị cho người dùng trong ví của họ (ví dụ: "Quán Cà phê", "Cửa hàng của tôi").

  • message (string, tùy chọn) - Thông báo hiển thị cho người dùng trước khi thanh toán (ví dụ: "Cảm ơn bạn đã mua hàng!", "Tiền boa cho dịch vụ tuyệt vời").

  • memo (string, tùy chọn) - Ghi chú trên chuỗi được đính kèm vào giao dịch. Lưu trữ vĩnh viễn trên Solana. Hữu ích cho ID đơn hàng, số hóa đơn hoặc siêu dữ liệu thanh toán khác.

TransactionRequestURLFields

Được sử dụng cho các yêu cầu thanh toán phức tạp (bao gồm hướng dẫn):

  • link (URL, bắt buộc) - Liên kết đến giao dịch (Link). Nếu URL chứa tham số truy vấn, nó phải được mã hóa URL.

  • label (string, tùy chọn) - Tên thương hiệu hoặc ứng dụng dễ đọc hiển thị cho người dùng trong ví của họ (ví dụ: "Quán Cà Phê", "Cửa Hàng Của Tôi").

  • message (string, tùy chọn) - Thông báo hiển thị cho người dùng trước khi thanh toán (ví dụ: "Cảm ơn bạn đã mua hàng!", "Tiền boa cho dịch vụ tuyệt vời").

Cách Hoạt Động

Hàm thực hiện một số thao tác để xây dựng URL Solana Pay hợp lệ:

  1. Tiền Tố Giao Thức - Tạo URL với lược đồ giao thức solana: (tương tự như mailto: hoặc bitcoin:)

  2. Người Nhận Làm Đường Dẫn - Sử dụng địa chỉ base58 của người nhận làm đường dẫn URL (ví dụ: solana:merchantWalletAddress123...)

  3. Chuyển Đổi Số Tiền - Chuyển đổi số tiền lamport bigint thành biểu diễn chuỗi thập phân mà không có vấn đề về độ chính xác dấu phẩy động.

  4. Tham Số Truy Vấn - Thêm tất cả các trường tùy chọn và tham chiếu dưới dạng tham số truy vấn được mã hóa URL

Giá Trị Trả Về

Đối tượng URL với giao thức solana: có thể được:

  • Chuyển đổi thành chuỗi bằng .toString() để chia sẻ
  • Truyền cho createQR() để tạo mã QR
  • Sử dụng trực tiếp trong thẻ anchor: <a href={url.toString()}>Pay with Solana</a>

Ví Dụ: Thanh Toán Cơ Bản

import { encodeURL } from "@solana-commerce/solana-pay";

import { address } from "gill";



const url = encodeURL({

  recipient: address("merchantWalletAddress123..."),

  amount: 100000000n, // 0.1 SOL (100 million lamports)

  label: "Coffee Shop",

  message: "Thanks for your order!"

});



console.log(url.toString());

// solana:merchantWalletAddress123...?amount=0.1&label=Coffee%20Shop&message=Thanks%20for%20your%20order!

Ví Dụ: Thanh Toán Token SPL

import { encodeURL } from "@solana-commerce/solana-pay";

import { address } from "gill";



const usdcMint = address("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");



const url = encodeURL({

  recipient: address("merchantWallet..."),

  amount: 25000000n, // 25 USDC (6 decimals)

  splToken: usdcMint,

  label: "USDC Payment",

  message: "Pay with USDC stablecoin"

});

Ví Dụ: Thanh Toán Có Theo Dõi

Sử dụng tham chiếu để xác định các khoản thanh toán cụ thể:

import { encodeURL } from "@solana-commerce/solana-pay";

import { address } from "gill";

import { Keypair } from "@solana/web3.js";



// Generate unique reference for this order

const orderReference = (await generateKeyPairSigner()).address;



const url = encodeURL({

  recipient: address("merchantWallet..."),

  amount: 500000000n, // 0.5 SOL

  reference: orderReference,

  memo: `Order-${Date.now()}`, // On-chain memo

  label: "E-commerce Store",

  message: "Complete your purchase"

});



// Later, query the blockchain for transactions containing this reference

// to verify payment was made

Phân Tích URL

parseURL(url)

Giải mã và xác thực URL Solana Pay, trích xuất tất cả các tham số thanh toán. Hàm này thực hiện xác thực và chuyển đổi số tiền từ chuỗi số thập phân trở lại thành bigint lamport.

Tham Số

  • url (string | URL) - URL Solana Pay cần phân tích. Có thể là chuỗi hoặc đối tượng URL.

Giá Trị Trả Về

Một đối tượng TransferRequestURLFields hoặc TransactionRequestURLFields đã được phân tích.

Ví Dụ: Phân Tích và Xác Thực

import { parseURL, ParseURLError } from "@solana-commerce/solana-pay";



try {

  const parsed = parseURL(

    "solana:merchant123...?amount=1.5&label=Store&reference=ref123..."

  );



  console.log(parsed.recipient); // Address object

  console.log(parsed.amount); // 1500000000n (1.5 SOL in lamports)

  console.log(parsed.label); // "Store"

  console.log(parsed.reference); // [Address]



  // Convert back to human-readable format

  const solAmount = Number(parsed.amount) / 1e9;

  console.log(`Payment of ${solAmount} SOL`);

} catch (error) {

  if (error instanceof ParseURLError) {

    console.error("Invalid Solana Pay URL:", error.message);

  }

}

Ví Dụ: Hàm Xác Thực URL

import { parseURL, ParseURLError } from "@solana-commerce/solana-pay";



function validateSolanaPayURL(urlString: string): {

  valid: boolean;

  error?: string;

  data?: any;

} {

  try {

    const parsed = parseURL(urlString);

    // Additional business logic validation

    if (parsed.splToken) {

      return {

        valid: false,

        error: "Only SOL payments are supported"

      };

    }

    if (parsed.amount && parsed.amount < 1000000n) {

      return {

        valid: false,

        error: "Amount too small (minimum 0.001 SOL)"

      };

    }

    // etc.



    return {

      valid: true,

      data: {

        recipient: parsed.recipient.toString(),

        amount: parsed.amount ? Number(parsed.amount) / 1e9 : undefined,

        token: parsed.splToken?.toString()

      }

    };

  } catch (error) {

    return {

      valid: false,

      error: error instanceof ParseURLError ? error.message : "Unknown error"

    };

  }

}

Tạo Mã QR

createQR(url, size, background, color)

Tạo mã QR dạng SVG được tối ưu hóa cho URL Solana Pay. Hàm này tạo ra các mã QR chất lượng cao, có kiểu dáng với các góc bo tròn và màu sắc có thể tùy chỉnh.

Tham Số

  • url (string | URL) - URL Solana Pay để mã hóa trong mã QR
  • size (number, mặc định: 512) - Chiều rộng và chiều cao tính bằng pixel
  • background (string, mặc định: 'white') - Màu nền (hex hoặc tên màu). Nên chọn màu sáng để tương thích với ví.
  • color (string, mặc định: 'black') - Màu nền trước/dấu chấm (hex hoặc tên màu). Nên chọn màu tối để tạo độ tương phản.

createStyledQRCode(url, options)

Giá Trị Trả Về

Promise<string> - Mã SVG dưới dạng chuỗi có thể được:

  • Đặt làm src cho phần tử img: <img src={qrCode} />
  • Lưu vào tệp

Ví Dụ

import { createQR, encodeURL } from "@solana-commerce/solana-pay";

import { address } from "gill";



async function generatePaymentQR() {

  const url = encodeURL({

    recipient: address("merchant..."),

    amount: 100000000n, // 0.1 SOL

    label: "Coffee Shop"

  });



  const qrCode = await createQR(

    url.toString(),

    400, // 400x400 pixels

    "white", // White background

    "black" // Black foreground

  );



  // Display in browser

  document.getElementById("qr-container").innerHTML = qrCode;



  // Or use as image source

  document.getElementById("qr-image").src = qrCode;

}

Ví dụ: Mã QR Có Thương Hiệu

import { createStyledQRCode, encodeURL } from "@solana-commerce/solana-pay";

import { address } from "gill";



async function createBrandedQR() {

  const url = encodeURL({

    recipient: address("merchant..."),

    amount: 25000000n, // 25 USDC (6 decimals)

    splToken: address("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"),

    label: "Coffee Shop",

    message: "Scan to pay with USDC"

  });



  const qr = await createStyledQRCode(url.toString(), {

    width: 600,

    margin: 3,

    color: {

      dark: "#9945FF", // Solana purple

      light: "#F5F5DC" // Beige

    },

    errorCorrectionLevel: "H", // Higher correction for logo

    dotStyle: "dots", // Circular dots

    cornerStyle: "extra-rounded",

    logo: "/coffee-logo.png", // Your logo

    logoSize: 120,

    logoBackgroundColor: "#FFFFFF", // White padding behind logo

    logoMargin: 10

  });



  return qr; // SVG string

}

Xây Dựng Giao Dịch

createTransfer(rpc, sender, fields)

Xây dựng một thông điệp giao dịch Solana hoàn chỉnh cho việc chuyển khoản thanh toán. Hàm này tự động phát hiện xem có cần tạo giao dịch chuyển SOL hay token SPL dựa trên tham số splToken, và xây dựng tất cả các lệnh cần thiết. Hàm này đặt thời gian sống blockhash cho giao dịch bằng cách sử dụng blockhash mới nhất từ RPC client và trả về một giao dịch hoàn chỉnh, chưa ký sẵn sàng để ký và gửi đến RPC (kiểu TransactionMessageWithBlockhashLifetime, tương thích với Solana Kit/Gill).

Tham Số

  • rpc (Rpc<SolanaRpcApi>) - Solana RPC client từ gill. Tạo bằng createSolanaClient(rpcUrl).rpc.

  • sender (Address) - Địa chỉ ví của người trả phí. Phải là tài khoản đã có tiền và sẽ ký giao dịch.

  • fields (CreateTransferFields) - Cấu hình chuyển khoản:

    • recipient (Address, bắt buộc) - Địa chỉ ví đích
    • amount (bigint, bắt buộc) - Số lượng tính bằng lamport (SOL) hoặc đơn vị nguyên tử của token (SPL)
    • splToken (Address, tùy chọn) - Địa chỉ mint của token SPL. Nếu bỏ qua, sẽ tạo giao dịch chuyển SOL.
    • reference (Address | Address[], tùy chọn) - (Các) địa chỉ tham chiếu để theo dõi
    • memo (string, tùy chọn) - Văn bản memo trên chuỗi

Kết Quả Trả Về

Promise<TransactionMessageWithBlockhashLifetime> - Thông điệp giao dịch hoàn chỉnh với:

  • Định dạng phiên bản 0 (hỗ trợ bảng tra cứu địa chỉ)

  • Thời gian sống blockhash (giao dịch hết hạn sau ~60 giây)

  • Tất cả các lệnh cần thiết (chuyển khoản + memo tùy chọn)

  • Sẵn sàng để được ký bằng ví và gửi đến RPC

  • Định dạng phiên bản 0 (hỗ trợ bảng tra cứu địa chỉ)

  • Thời gian sống blockhash (giao dịch hết hạn sau ~60 giây)

  • Tất cả các lệnh cần thiết (chuyển khoản + memo tùy chọn)

  • Sẵn sàng để được ký bằng ví và gửi đến RPC

Xử Lý Lỗi

Ném ra CreateTransferError với các thông báo cụ thể:

  • "sender not found" - Tài khoản người gửi không tồn tại
  • "recipient not found" - Tài khoản người nhận không tồn tại

Ví dụ: Thanh Toán SOL

import { createTransfer } from "@solana-commerce/solana-pay";

import { createSolanaClient } from "gill";

import { address } from "gill";



const rpc = createSolanaClient("https://api.mainnet-beta.solana.com").rpc;



// Build SOL transfer transaction

const txMessage = await createTransfer(rpc, address("sender-wallet-address"), {

  recipient: address("merchant-wallet-address"),

  amount: 100000000n, // 0.1 SOL

  memo: "Coffee purchase"

});



// Transaction is ready to sign and send

// (wallet signing is handled separately)

console.log("Transaction ready:", txMessage);

Ví dụ: Thanh Toán USDC

Is this page helpful?

Trước

Luồng Thanh Toán Headless

Tiếp theo

React Hooks

Mục lục

Chỉnh sửa trang

Quản lý bởi

© 2026 Solana Foundation.
Đã đăng ký bản quyền.
Solana
Kết nối