Noções Básicas de Solana Pay

7 exemplos para requisições de pagamento e fluxos de QR - 4 básicos e 3 intermediários.

Pré-requisitos

npm install @solana/pay @solana/kit@7.0.0

Exemplos Básicos

1. URL de Requisição de Transferência

URLs do Solana Pay codificam destinatário, valor e rótulo.

import { encodeURL } from "@solana/pay";
import { address } from "@solana/kit";
 
const url = encodeURL({
  recipient: address("MERCHANT_PUBKEY"),
  amount: 1_000_000n,
  label: "Coffee",
});

• Carteiras analisam URLs para pré-preencher transferências.
• Valores em lamports como bigint.
• Esquema HTTPS ou solana: dependendo do contexto.

2. QR Code para PDV

Renderize a URL como QR para checkout presencial.

import QRCode from "react-qr-code";
// <QRCode value={url.toString()} />

• Teste a distância de escaneamento e a iluminação para eventos.
• Inclua um rótulo legível sob o QR.
• Exclua ou rotacione URLs para faturas de uso único quando necessário.

3. Rastreamento com Chave Pública de Referência

Anexe uma conta de referência para correlacionar pagamentos.

// encodeURL({ ..., reference: [referencePubkey] })

• Monitore a referência via RPC ou websocket.
• Referência única por sessão de checkout.
• Veja Requisições de Transação.

4. Metadados de Exibição do Comerciante

Os campos de rótulo e mensagem melhoram a experiência do usuário da carteira.

encodeURL({ label: "Shop", message: "Order #1234", ... });

• Mantenha a mensagem curta - a interface do usuário da carteira a trunca.
• Localize o rótulo para clientes internacionais.

Exemplos Intermediários

5. Fluxo de Requisição de Transação

O servidor retorna uma transação parcialmente construída em vez de uma transferência simples.

// GET https://merchant.com/api/solana-pay?account=...

• Permite swap ou mint em uma única aprovação da carteira.
• Requer um endpoint HTTPS que você controla.
• A especificação se sobrepõe ao Solana Actions.

6. Verificar Pagamento Liquidado

import { createSolanaRpc } from "@solana/kit";
const rpc = createSolanaRpc(process.env.RPC_URL!);
// encontre tx mencionando referência + valor

• Não marque o pedido como pago com base em uma suposição do lado do cliente.
• Espere no mínimo um compromisso confirmado.
• Trate pagamentos parciais explicitamente.

7. Link para Actions / Blinks

URLs de ação compartilháveis são incorporadas em posts sociais.

https://actions.example.com/swap?...

• Blinks se expandem em aplicativos compatíveis.
• Veja Blinks e Actions (a spec).

Versões da stack: Esta página foi escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0 e LiteSVM 0.6.x. 49454e4f4d5f434e4f5904434556494d4345191c1a56181a181c1a1d