Wen Open Lab · integrazione aperta

Fase 4: ponte pagamentilink verificato

English · Italiano · 中文 · 한국어

Tradotto dall’inglese da Wen insieme all’AI. Il riferimento è la pagina inglese; le correzioni sono benvenute.

Design del metodo di pagamento Wen
Un nuovo metodo di pagamento, aperto a tutti

L'acquiring con carta fa tre cose per un negozio: incassa il pagamento, lo conferma e lo comunica al sistema del negozio. Questo modello fa lo stesso su Solana con lo standard aperto Solana Pay: un link di pagamento o un QR per ordine, un osservatore che trova il pagamento tramite un riferimento unico, una convalida rigorosa e un webhook verso il negozio.

Il compito

Permettere a un negozio online di accettare pagamenti su Solana e segnare gli ordini come pagati automaticamente, con la stessa affidabilità che il negozio si aspetta da un acquirer di carte.

Il modello

  1. Crea. Per ogni ordine il negozio genera un link Solana Pay con destinatario, importo, token, un indirizzo reference casuale e unico, un'etichetta e un memo order:ID. Il link diventa un pulsante o un QR.
  2. Paga. Il cliente lo apre in qualsiasi portafoglio Solana Pay e conferma.
  3. Trova. Il server del negozio chiede alla catena la transazione che include l'indirizzo di riferimento.
  4. Convalida. Controlla destinatario, importo, token, riferimento e memo. Qualsiasi errore genera un'eccezione.
  5. Notifica. Invia {orderId, status: "paid", signature} al webhook del negozio. Il sistema ordini spedisce la merce.
Acquiring con cartaQuesto ponte
ConfermaAutorizzazione in secondi, denaro regolato in giorniConfermato in secondi, definitivo in circa 13 secondi
CommissionePercentuale più commissione fissa per pagamentoCommissione di rete, una frazione di centesimo, più eventuali costi di conversione
ChargebackSì: protegge l'acquirente, rischio per il negozioNo: i rimborsi sono un nuovo pagamento dal negozio
RegolamentazioneSe ne occupa l'acquirer autorizzatoDipende dal paese; può richiedere un partner autorizzato

Il codice

File: lab/code/src/04-solana-pay-bridge.ts · Apache-2.0

// Model 4: a payment bridge for e-commerce. The shop creates a Solana Pay link/QR for an order,
// watches the chain for the payment by its unique reference, validates amount and token,
// then notifies its own order system (the same role a card acquirer's callback plays).
// License: Apache-2.0. Example code, not audited. Devnet first. Built on @solana/pay + @solana/kit.
import { encodeURL, findReference, validateTransfer, FindReferenceError } from '@solana/pay';
import { address, createSolanaRpc, generateKeyPairSigner, type Address } from '@solana/kit';

/** Tokens a shop may accept. USDC for stable prices; $WEN as an optional community payment. */
export const ACCEPTED = {
  USDC_MAINNET: address('EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'),
  WEN_MAINNET: address('WENWENvqqNya429ubCdR81ZmD69brwQaaBYY6p3LCpk'),
} as const;

export interface PaymentRequest {
  orderId: string;
  recipient: Address;      // the shop's wallet
  amount: number;          // in token units, e.g. 24.99
  splToken?: Address;      // omit for SOL
  reference: Address;      // unique per order: how the shop finds the payment
  url: string;             // solana: URL to show as a link or QR
}

export async function createPaymentRequest(orderId: string, recipient: Address, amount: number, splToken?: Address): Promise<PaymentRequest> {
  const reference = (await generateKeyPairSigner()).address;   // random, never reused
  const url = encodeURL({
    recipient, amount, splToken, reference,
    label: 'Wen Open Lab demo shop',
    message: `Order ${orderId}`,
    memo: `order:${orderId}`,
  });
  return { orderId, recipient, amount, splToken, reference, url: url.toString() };
}

/** Poll until the payment appears, then validate it and call the shop's webhook. */
export async function waitForPayment(req: PaymentRequest, opts: { rpcUrl: string; webhook: string; timeoutMs?: number }) {
  const rpc = createSolanaRpc(opts.rpcUrl);
  const deadline = Date.now() + (opts.timeoutMs ?? 5 * 60_000);
  while (Date.now() < deadline) {
    try {
      const found = await findReference(rpc, req.reference, { commitment: 'confirmed' });
      // Throws if recipient, amount, token, reference or memo do not match the request.
      await validateTransfer(rpc, found.signature, {
        recipient: req.recipient, amount: req.amount, splToken: req.splToken, reference: req.reference, memo: `order:${req.orderId}`,
      }, { commitment: 'confirmed' });
      await fetch(opts.webhook, {
        method: 'POST',
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify({ orderId: req.orderId, status: 'paid', signature: found.signature }),
      });
      return found.signature;
    } catch (e) {
      if (!(e instanceof FindReferenceError)) throw e;   // not found yet: keep waiting
      await new Promise(r => setTimeout(r, 1500));
    }
  }
  throw new Error(`Order ${req.orderId}: payment not found before timeout`);
}

Cosa è stato verificato

Il link di pagamento fa andata e ritorno attraverso il parser ufficiale di Solana Pay con gli stessi destinatario, importo, token, riferimento e memo, e ogni ordine riceve un riferimento unico. L'osservatore e la convalida usano le funzioni ufficiali findReference e validateTransfer e sono controllati nei tipi; eseguirli su una catena reale fa parte della fase devnet.

Dove è utile

  • Negozi online che vendono a clienti cripto-nativi in tutto il mondo.
  • Beni digitali, biglietti e abbonamenti dove conta il regolamento istantaneo.
  • Fornitori di pagamento e banche che esplorano l'accettazione di stablecoin accanto alle carte.

Limiti e rischi

  • Volatilità del prezzo: indica i prezzi in una stablecoin o converti alla cassa.
  • La conversione in valuta fiat (off-ramp) ha le sue commissioni e regole.
  • Niente chargeback significa che il negozio deve offrire una politica di rimborso chiara.
  • In produzione usa un tuo endpoint RPC; gli endpoint pubblici hanno limiti di frequenza.

Vuoi i numeri per il tuo negozio? Prova il simulatore.

Wen in immagini

Wen su Jupiter Mobile
Paga dal telefono
Solana Seeker con la moneta Wen
Il portafoglio in tasca
Pagamento con portafoglio cripto Wen
Pagamento in pochi secondi
Pagamento con portafoglio Jupiter
Qualsiasi token, un unico standard
Pagamenti mobili nell'ecosistema Wen
Dal QR all'ordine confermato

Dove si colloca Wen in questo modello

Il negozio sceglie quali token accettare. USDC mantiene stabili i prezzi; WEN può essere offerto come opzione di pagamento della comunità, con il suo contratto scritto nel codice come ACCEPTED.WEN_MAINNET. Prima di accettare qualsiasi token, controlla quale programma di token possiede il suo mint (lo fa l'helper detectTokenProgram in common.ts) e prova l'intero flusso sulla devnet.

Il filo di Wen: un contratto, ovunque

Ogni modello del Lab è gratuito e aperto, e ognuno porta la stessa firma: il contratto del token $WEN. Copialo, ripetilo nei tuoi documenti e verificalo sempre su un explorer prima di usarlo.

WENWENvqqNya429ubCdR81ZmD69brwQaaBYY6p3LCpk

Verifica: Solana Explorer · come trovare l'ID del contratto

Politica di uso aperto

  • Gratuito e aperto. Tutto il codice del Lab è rilasciato con licenza Apache 2.0, la stessa della Wen Program Library. Usalo, modificalo, distribuiscilo, a fini commerciali o no; mantieni l'avviso di licenza.
  • Solo strumenti aperti. Costruito su strumenti pubblici e documentati: Solana SPL Token-2022 (Token Extensions), il layout dei token del Wen New Standard (WNS), Solana Pay e LiteSVM per i test locali.
  • La regola: verifica sempre il tuo modello. Esegui i test, inizia sulla devnet, leggi la documentazione ufficiale, rivedi ogni account e importo e ottieni un audit indipendente prima di qualsiasi uso su mainnet. Un modello non verificato non è un modello, è un'ipotesi.
  • Non sottoposto ad audit, non è una consulenza. Questi sono esempi didattici. Non costituiscono consulenza finanziaria, legale o fiscale, né un prodotto di pagamento o bancario autorizzato. Pagamenti, stablecoin e acquiring sono attività regolamentate nella maggior parte dei paesi.
  • Sicurezza. Non incollare mai una chiave privata in un sito web. Non installare il pacchetto npm @wen-community/wen-new-standard: npm lo ha rimosso perché malevolo. Costruisci da fonti ufficiali.

Parla Wen, per la comunità. Altro nella nostra politica editoriale e sui dati.

Wen Open Lab · roadmap · tutto il codice · Wen Program Library su GitHub

Wen pilota un'astronave tra scie di luce nello spazio profondo
Pagamenti alla velocità di un blocco: un riferimento per ordine, così il negozio trova ogni pagamento senza indovinare.