Transfer İstekleri

Transfer istekleri, Solana Pay entegrasyonunun en basit şeklidir. Cüzdanların sunucu gerektirmeden doğrudan işlemleri oluşturup göndermek için kullanabileceği etkileşimsiz ödeme URL'leri oluştururlar.

Genel Bakış

Bir transfer isteği URL'si şu formatta olur:

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

Temel SOL Transferi

Basit bir SOL ödeme isteği oluşturun:

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 Transferi

Bir USDC ödeme isteği oluşturun:

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 Parametreleri

Zorunlu Parametreler

Alıcı

Alıcının Solana cüzdan adresi (base58 kodlu):

const recipient = address("FvJ8k8HhXp4a3zQyFMZd4FvEqcYdYE7gSZWxrEBRfBsB");

İsteğe Bağlı Parametreler

Miktar

Kullanıcı dostu birimlerde ödeme miktarı (SOL veya token birimleri):

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

Belirtilmezse, cüzdan kullanıcıdan miktarı girmesini isteyecektir.

SPL Token

Token transferleri için mint adresini belirtin:

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

Referans

Ödemeleri takip etmek için benzersiz tanımlayıcılar. Referans anahtarı olarak kullanmak üzere bir adres oluşturun:

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

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

Etiket

Kullanıcılara görüntülenen işletme veya uygulama adı:

const label = "Acme Coffee Shop";

Mesaj

Ödeme açıklaması:

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

Not

Zincir üstü not (herkese açık olarak görülebilir):

const memo = "OrderId:12345";

QR Kod Entegrasyonu

Yerleşik createQR fonksiyonunu kullanarak QR kodları oluşturun:

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

Ödeme Doğrulama

Merchant İstemcisini Kullanma

Ödemeleri bulmanın ve doğrulamanın en basit yolu:

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

Bağımsız Fonksiyonları Kullanma

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

Ödemeleri İzleme (WebSocket)

Önerilen yaklaşım — watchReference WebSocket üzerinden abone olur ve eşleşen bir işlem gerçekleşir gerçekleşmez çözümlenir. Yoklama gerekmez.

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

Ödemeleri Yoklama (HTTP yedekleme)

WebSocket abonelikleri mevcut değilse (örn. bazı RPC sağlayıcıları), findReference ile yoklamaya geri dönün:

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

Eksiksiz Örnek

QR kod oluşturma ve ödeme izleme içeren eksiksiz bir örnek:

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

En İyi Uygulamalar

Güvenlik

Ödemeleri her zaman sunucu tarafında doğrulayın
Her ödeme için benzersiz referanslar kullanın
İşlem tutarlarını ve alıcıları doğrulayın
İşlem başarı durumunu kontrol edin

Kullanıcı Deneyimi

Net ödeme tutarları ve açıklamaları gösterin
Ödeme durumu güncellemeleri sağlayın
Cüzdan bağlantısını zarif bir şekilde yönetin
Hem QR kodlarını hem de doğrudan bağlantıları destekleyin

Hata Yönetimi

Cüzdan bağlantı hatalarını yönetin
Desteklenmeyen cüzdanlar için yedek seçenek sağlayın
Yararlı hata mesajları gösterin
Ödeme zaman aşımlarını uygulayın

Yaygın Kullanım Senaryoları

Satış Noktası

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

Bağışlar

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

E-ticaret Ödeme Sayfası

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

İçindekiler