Solana Pay

O Commerce Kit está atualmente em beta. As APIs podem mudar antes do lançamento estável. Para detalhes adicionais, consulte a documentação do Commerce Kit.

Solana Pay é um protocolo padrão para codificar solicitações de pagamento como URLs. Esses URLs podem ser partilhados como links, codificados como códigos QR para carteiras móveis, ou usados para construir transações de pagamento programaticamente.

O pacote @solana-commerce/solana-pay fornece codificação/análise de URL, geração de código QR e construção de transações—compatível com @solana/kit.

Instalação

pnpm add @solana-commerce/solana-pay

Criar URLs de pagamento

Use encodeURL para criar um URL de protocolo solana: que as carteiras podem analisar:

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

const url = encodeURL({
  recipient: address("merchant-wallet-address"),
  amount: 100000000n, // 0.1 SOL in lamports
  label: "Coffee Shop",
  message: "Thanks for your order!"
});

console.log(url.toString());
// solana:merchant...?amount=0.1&label=Coffee%20Shop&message=...

Parâmetros de URL

Parâmetro	Tipo	Descrição
`recipient`	`Address`	Endereço da carteira do comerciante (obrigatório)
`amount`	`bigint`	Montante em lamports ou unidades menores de token
`splToken`	`Address`	Endereço de mint do token SPL (omitir para SOL)
`reference`	`Address[]`	Referência(s) única(s) para rastreamento de pagamentos
`label`	`string`	Nome do comerciante exibido na carteira
`message`	`string`	Mensagem exibida antes do pagamento
`memo`	`string`	Memorando on-chain anexado à transação

Pagamentos com token SPL

Para pagamentos com stablecoin, especifique o mint do token:

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

const url = encodeURL({
  recipient: address("merchant-wallet"),
  amount: 25000000n, // 25 USDC (6 decimals)
  splToken: USDC_MINT,
  label: "My Store"
});

Rastreamento de pagamentos com referências

Gere uma referência única para identificar pagamentos específicos:

import { encodeURL } from "@solana-commerce/solana-pay";
import { address, generateKeyPairSigner } from "@solana/kit";

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

const url = encodeURL({
  recipient: address(MERCHANT_WALLET_ADDRESS),
  amount: 500000000n, // 0.5 SOL
  reference: orderReference,
  memo: `Order-${Date.now()}`
});

// Query the blockchain later for transactions containing this reference

Gerando códigos QR

Use createQR para gerar códigos QR escaneáveis para carteiras móveis:

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

const url = encodeURL({
  recipient: address(MERCHANT_WALLET_ADDRESS),
  amount: 100000000n,
  label: "Coffee Shop"
});

const qrCode = await createQR(
  url.toString(),
  400, // size in pixels
  "white", // background
  "black" // foreground
);

// Use as image source
document.getElementById("qr").src = qrCode;

Códigos QR estilizados

Para códigos QR personalizados com logotipos e estilo customizado:

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

const qr = await createStyledQRCode(url.toString(), {
  width: 600,
  margin: 3,
  color: {
    dark: "#9945FF", // Solana purple
    light: "#FFFFFF"
  },
  errorCorrectionLevel: "H",
  dotStyle: "dots",
  cornerStyle: "extra-rounded",
  logo: "/your-logo.png",
  logoSize: 120
});

Construindo transações

Use createTransfer para construir uma transação completa para assinatura:

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

const transaction = await createTransfer(
  client.rpc,
  address(SENDER_WALLET_ADDRESS),
  {
    recipient: address(MERCHANT_WALLET_ADDRESS),
    amount: 100000000n, // 0.1 SOL
    memo: "Coffee purchase"
  }
);

Para tokens SPL, inclua o endereço mint:

const USDC_MINT = address("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");

const transaction = await createTransfer(
  client.rpc,
  address(SENDER_WALLET_ADDRESS),
  {
    recipient: address(MERCHANT_WALLET_ADDRESS),
    amount: 25000000n, // 25 USDC
    splToken: USDC_MINT,
    reference: [orderReference],
    memo: "Order #12345"
  }
);

Analisando URLs

Valide e extraia dados de URLs do Solana Pay:

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

try {
  const parsed = parseURL("solana:merchant...?amount=1.5&label=Store");

  console.log(parsed.recipient); // Address
  console.log(parsed.amount); // 1500000000n (lamports)
  console.log(parsed.label); // "Store"
} catch (error) {
  if (error instanceof ParseURLError) {
    console.error("Invalid URL:", error.message);
  }
}

Índice