Запити на переказ

Запити на переказ — це найпростіша форма інтеграції Solana Pay. Вони створюють неінтерактивні 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-токен

Для переказів токенів вкажіть адресу mint:

// 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 label = "Acme Coffee Shop";

Повідомлення

Опис платежу:

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

Мемо

Он-чейн мемо (публічно доступне):

const memo = "OrderId:12345";

Інтеграція QR-коду

Генеруйте QR-коди за допомогою вбудованої функції 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);
  });
}

Повний приклад

Ось повний приклад з генерацією QR-коду та моніторингом платежів:

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

Найкращі практики

Безпека

Завжди перевіряйте платежі на стороні сервера
Використовуйте унікальні посилання для кожного платежу
Перевіряйте суми транзакцій та одержувачів
Перевіряйте статус успішності транзакції

Користувацький досвід

Показуйте чіткі суми платежів та описи
Надавайте оновлення статусу платежу
Коректно обробляйте підключення гаманця
Підтримуйте як QR-коди, так і прямі посилання

Обробка помилок

Обробляйте збої підключення гаманця
Забезпечте резервний варіант для непідтримуваних гаманців
Показуйте зрозумілі повідомлення про помилки
Реалізуйте тайм-аути платежів

Поширені випадки використання

Точка продажу

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

Зміст