Panoramica

Solana Pay è un protocollo standard e un insieme di implementazioni di riferimento che consentono agli sviluppatori di integrare pagamenti decentralizzati nelle loro app e servizi. Fornisce un approccio unificato ai pagamenti nell'intero ecosistema Solana, garantendo la compatibilità tra wallet, app e servizi.

Panoramica del Protocollo

Solana Pay definisce due tipi principali di richieste di pagamento:

Richieste di Trasferimento (Non Interattive)

Le richieste di trasferimento descrivono semplici trasferimenti di SOL o token SPL utilizzando parametri URL. Il wallet può comporre e firmare direttamente la transazione senza comunicazione aggiuntiva con il server.

solana:recipient?amount=1.5&spl-token=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

Casi d'Uso:

• Pagamenti semplici e donazioni
• Pagamenti tramite codice QR presso punti vendita
• Link di pagamento in email o messaggi
• Deep linking per app mobile

Richieste di Transazione (Interattive)

Le richieste di transazione abilitano interazioni complesse facendo comunicare il wallet con un server per comporre qualsiasi transazione Solana. Questo sblocca casi d'uso avanzati oltre i semplici trasferimenti.

solana:https://merchant.com/api/payment

Casi d'Uso:

• Conio di NFT presso punti vendita
• Prezzi dinamici e sconti
• Transazioni DeFi multi-step
• Integrazione di programmi fedeltà
• Logica di business personalizzata

Vantaggi Principali

Per gli Sviluppatori

• Protocollo Standard: Un'unica implementazione funziona con tutti i wallet Solana
• Framework Agnostico: Utilizzabile con qualsiasi framework web o piattaforma mobile
• Sicurezza dei Tipi: Supporto completo TypeScript nell'SDK JavaScript
• Flessibile: Dai trasferimenti semplici alle transazioni complesse multi-istruzione

Per gli Utenti

• Veloce: Le transazioni si confermano in meno di un secondo
• Economico: Costo medio di $0,0005 per transazione
• Sicuro: Nessun intermediario o processore di terze parti
• Universale: Funziona con qualsiasi wallet Solana

Per i Commercianti

• Nessuna Commissione: Pagamenti diretti senza costi di elaborazione
• Tempo Reale: Regolamento e conferma istantanei
• Globale: Accetta pagamenti da qualsiasi parte del mondo
• Componibile: Integrazione con protocolli DeFi e marketplace NFT

Architettura Tecnica

Schema URL

Solana Pay utilizza uno schema URL personalizzato solana: che funziona su browser web e sistemi operativi mobile:

• Web: Gli URL possono essere utilizzati come link o codificati in codici QR
• Mobile: Integrazione deep linking con app wallet
• Desktop: Gestori di protocollo per l'avvio seamless del wallet

SDK JavaScript

L'SDK @solana/pay (basato su @solana/kit) fornisce:

• Factory client: createMerchantClient, createWalletClient, createSolanaPayClient per flussi di pagamento componibili
• Codifica/analisi URL: encodeURL, parseURL per URL Solana Pay
• Creazione trasferimenti: createTransfer per istruzioni di pagamento SOL e token SPL
• Validazione pagamenti: findReference, validateTransfer, watchReference per rilevare e verificare i pagamenti
• Codici QR: createQR integrato per generare codici di pagamento scansionabili
• Plugin Kit: solanaPayMerchant(), solanaPayWallet() per la composizione con altri plugin @solana/kit

Integrazione Wallet

I wallet supportati implementano:

• Gestione e analisi dello schema URL
• Composizione e validazione delle transazioni
• Flussi di conferma utente
• Trasmissione e monitoraggio delle transazioni

Esempi di Flusso di Pagamento

App Web a Wallet Mobile

1. L'app web genera un codice QR con URL Solana Pay
2. L'utente scansiona il codice QR con l'app wallet
3. Il wallet analizza l'URL e mostra i dettagli del pagamento
4. L'utente conferma il pagamento nel wallet
5. Il wallet firma e trasmette la transazione
6. L'app web rileva la conferma del pagamento

App Web a Wallet Browser

1. L'app web mostra il pulsante "Paga con Solana"
2. L'utente clicca il pulsante per avviare il wallet
3. L'estensione wallet mostra la conferma del pagamento
4. L'utente approva la transazione
5. La transazione viene firmata e inviata
6. L'app web riceve la conferma del pagamento

App Mobile a Portafoglio Mobile

1. L'app mobile crea un link profondo di pagamento
2. Il link profondo avvia l'app del portafoglio
3. Il portafoglio mostra la conferma del pagamento
4. L'utente approva o rifiuta il pagamento
5. Il portafoglio ritorna all'app originale
6. L'app riceve il risultato del pagamento

Considerazioni sulla Sicurezza

Per i Commercianti

• Convalida le Transazioni: Verifica sempre i dettagli delle transazioni on-chain
• Usa Riferimenti: Includi chiavi di riferimento univoche per identificare i pagamenti
• Convalida Lato Server: Calcola gli importi e convalida i pagamenti lato server
• Limitazione di Richieste: Implementa limiti di richieste appropriati sugli endpoint di pagamento

Per gli Sviluppatori di Portafogli

• Convalida URL: Convalida e sanifica tutti i componenti URL
• Conferma Utente: Mostra sempre dettagli di pagamento chiari agli utenti
• Convalida Transazioni: Verifica i contenuti delle transazioni prima della firma
• Solo HTTPS: Consenti solo URL HTTPS per le richieste di transazione

Modelli di Integrazione

Checkout E-commerce

1. Il cliente aggiunge articoli al carrello
2. Il commerciante genera una richiesta di pagamento con i dettagli dell'ordine
3. Il cliente scansiona il codice QR o clicca sul pulsante di pagamento
4. Il portafoglio mostra la ricevuta dettagliata e il totale
5. Il cliente conferma il pagamento
6. Il commerciante convalida la transazione ed evade l'ordine

Punto Vendita

1. Il cassiere inserisce l'importo della vendita
2. Il sistema POS visualizza il codice QR
3. Il cliente scansiona con il portafoglio mobile
4. Il pagamento viene elaborato istantaneamente
5. La ricevuta viene stampata automaticamente

Servizi in Abbonamento

1. L'utente si abbona al servizio
2. Il servizio crea un programma di pagamenti ricorrenti
3. Il sistema automatizzato genera richieste di pagamento
4. L'utente approva i pagamenti tramite il portafoglio
5. Il servizio traccia lo stato dei pagamenti

Migliori Pratiche

Generazione URL

• Usa HTTPS per tutti gli endpoint di richiesta transazioni
• Includi etichette e messaggi descrittivi
• Genera riferimenti univoci per il tracciamento dei pagamenti
• Convalida tutti i parametri prima della creazione dell'URL

Gestione delle Transazioni

• Convalida sempre le transazioni lato server
• Utilizza un numero appropriato di conferme per la sicurezza
• Implementa una corretta gestione degli errori e dei tentativi
• Registra gli eventi di pagamento per la riconciliazione

Esperienza Utente

• Fornisci conferme di pagamento chiare
• Mostra gli aggiornamenti sullo stato delle transazioni
• Gestisci la connessione del wallet in modo fluido
• Supporta più opzioni di wallet

Prossimi Passi

Pronto per integrare Solana Pay? Inizia con queste guide:

• Guida all'Installazione - Configura l'SDK e gli strumenti
• Richieste di Trasferimento - Crea semplici URL di pagamento
• Richieste di Transazione - Crea flussi interattivi
• Esempi di Integrazione - Scopri implementazioni reali

Risorse

• Specifiche Ufficiali - Specifiche complete del protocollo
• Repository GitHub - Codice sorgente ed esempi
• Linee Guida del Brand - Loghi e risorse del brand