Cài đặt

Bắt đầu với Solana Pay bằng cách cài đặt JavaScript SDK và thiết lập môi trường phát triển của bạn. SDK không phụ thuộc vào framework và hoạt động với bất kỳ môi trường JavaScript nào.

Yêu cầu Hệ thống

• Node.js: Phiên bản 20 trở lên (bắt buộc để hỗ trợ crypto.subtle)
• Trình quản lý Gói: pnpm, npm hoặc yarn
• TypeScript: Phiên bản 5+ (khuyến nghị nhưng không bắt buộc)

Cài đặt Solana Pay SDK

Chọn trình quản lý gói bạn ưa thích:

# Using pnpm (recommended)
pnpm add @solana/pay@beta @solana/kit

# Using npm
npm install @solana/pay@beta @solana/kit

# Using yarn
yarn add @solana/pay@beta @solana/kit

Peer Dependencies

Các gói sau là peer dependencies của @solana/pay và phải được cài đặt cùng với nó:

Optional Dependencies

Để tạo và xác thực giao dịch chuyển (chuyển SOL và SPL token), cũng cần cài đặt:

pnpm add @solana-program/system @solana-program/token @solana-program/token-2022 @solana-program/memo

Để sử dụng các client factory (createMerchantClient, createWalletClient), cũng cần cài đặt các kit plugin:

pnpm add @solana/kit-plugin-rpc @solana/kit-plugin-payer @solana/kit-plugin-instruction-plan

Cấu hình TypeScript

Nếu sử dụng TypeScript, hãy đảm bảo tsconfig.json của bạn bao gồm:

{
  "compilerOptions": {
    "module": "ESNext",
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

Thiết lập Môi trường

Môi trường Phát triển

Thiết lập các biến môi trường cho phát triển:

# .env.local
SOLANA_RPC_URL=https://api.devnet.solana.com
SOLANA_NETWORK=devnet

Môi trường Production

Đối với production, sử dụng các endpoint mainnet:

# .env.production
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
SOLANA_NETWORK=mainnet-beta

Xác Minh Cài Đặt

Tạo một bài kiểm tra đơn giản để xác minh mọi thứ đang hoạt động:

// test-installation.ts
import { address } from "@solana/kit";
import { encodeURL } from "@solana/pay";

// Test creating a payment URL
const recipient = address("FvJ8k8HhXp4a3zQyFMZd4FvEqcYdYE7gSZWxrEBRfBsB");

const url = encodeURL({
  recipient,
  amount: 0.01,
  label: "Test Store",
  message: "Test payment"
});

console.log("Solana Pay URL:", url.toString());
// Output: solana:FvJ8k8Hh...?amount=0.01&label=Test%20Store&message=Test%20payment

Chạy bài kiểm tra:

npx tsx test-installation.ts

Bạn sẽ thấy một URL Solana Pay hợp lệ trong console.

Các Vấn Đề Thường Gặp và Giải Pháp

Lỗi Phân Giải Module

Nếu bạn thấy lỗi như "Cannot resolve module '@solana/pay'":

1. Xóa bộ nhớ đệm của trình quản lý gói:

   # pnpm
   pnpm store prune
   
   # npm
   npm cache clean --force
   
   # yarn
   yarn cache clean

2. Xóa node_modules và cài đặt lại:

   rm -rf node_modules
   pnpm install

Lỗi TypeScript

Nếu bạn gặp lỗi TypeScript:

1. Cập nhật lên phiên bản TypeScript mới nhất (5+)
2. Đảm bảo moduleResolution được đặt thành "bundler" hoặc "nodenext" trong tsconfig.json của bạn

Các Bước Tiếp Theo

Bây giờ bạn đã cài đặt Solana Pay, hãy chọn hướng tích hợp của bạn:

• Yêu Cầu Chuyển Khoản - URL thanh toán đơn giản cho các giao dịch chuyển khoản cơ bản
• Yêu Cầu Giao Dịch - Quy trình thanh toán tương tác
• Tích Hợp Mã QR - Tạo mã QR cho thanh toán di động

Công Cụ Phát Triển

Cân nhắc cài đặt các công cụ phát triển hữu ích sau:

# Solana CLI (for testing and key generation)
sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"

# Local validator for testing
solana-test-validator

Tài Nguyên

• Kho GitHub - Mã nguồn và ví dụ
• Solana Cookbook - Công thức phát triển Solana