Integrazione pagamenti Polygon: guida per sviluppatori

Un’integrazione dei pagamenti Polygon è l’insieme dei componenti che permette alla Sua applicazione di accettare e inviare token sulla rete Polygon PoS: wallet, trasferimenti, verifica e notifiche. Ogni componente si può costruire direttamente sui nodi, oppure chiamando una REST API che fornisce wallet, trasferimenti e webhook. Questa guida tratta entrambe le strade.

TL;DR

• Polygon PoS ha chain ID 137 e usa POL per il gas. Il testnet Amoy ha chain ID 80002.
• Un pagamento è completato solo quando si sono verificati stato della transazione, destinatario, importo e contratto del token. Il solo hash non è una prova.
• Usi i webhook, non il polling, per seguire i pagamenti. Verifichi la firma e renda il gestore idempotente.
• I webhook di Chaingateway non vengono ripetuti automaticamente, quindi riconcili con l’elenco delle notifiche.
• Pianifichi l’ambito legale, la custodia delle chiavi, i conflitti di nonce e le oscillazioni del gas prima del lancio, non dopo.

Indice

• Che cosa comprende un’integrazione di pagamento Polygon?
• Quale rete e quale token scegliere?
• Come configuro i wallet e proteggo le chiavi?
• Come invio un pagamento in token su Polygon?
• Come verifico che un pagamento sia arrivato?
• Come ricevo notifiche con i webhook?
• Come progetto il backend?
• Che cosa controllo prima del lancio?
• FAQ
• Fonti

Che cosa comprende un’integrazione di pagamento Polygon?

Un’integrazione di pagamento è più che l’invio di token. Un gateway funzionante gestisce i wallet degli utenti, segue lo stato di ogni transazione tramite webhook e riconcilia i saldi in un database. La chain indica soltanto che cosa è successo. Il Suo backend decide che cosa significa per un ordine, una fattura o un saldo.

In pratica si costruiscono cinque componenti:

1. Livello wallet: indirizzi per ricevere fondi e chiavi per inviarli.
2. Livello di trasferimento: codice che costruisce, firma e trasmette i trasferimenti di token.
3. Livello di verifica: controlli che un trasferimento sia avvenuto davvero come previsto.
4. Livello di notifica: webhook che informano la Sua app dei cambi di stato.
5. Registro contabile: la Sua registrazione nel database di ciò che è dovuto, pagato e saldato.

I primi quattro sono infrastruttura di chain. Il quinto è il Suo prodotto. Più tempo si spende sull’infrastruttura, più tardi arriva la parte che vedono i clienti.

Serve una licenza?

Prima di scrivere codice, stabilisca dove opera e quali norme si applicano. Nell’UE il Regolamento sui mercati delle cripto-attività (MiCA) disciplina i fornitori di servizi per cripto-attività, come descritto nella pagina ESMA su MiCA. Negli Stati Uniti, le linee guida di FinCEN sulle valute virtuali descrivono quando amministrare o scambiare valute virtuali rende un soggetto un money transmitter.

Se il Suo modello fa scattare una norma dipende dal fatto che Lei detenga o muova fondi per conto di terzi. Questa domanda spetta a un avvocato che conosca i pagamenti, non a una revisione del codice. La ponga prima del lancio, perché la risposta può cambiare se Lei custodisce fondi.

Quale rete e quale token scegliere?

Per la maggior parte dei prodotti di pagamento conviene Polygon PoS con uno stablecoin come USDC o USDT. La documentazione di Polygon indica chain ID 137 e POL come token del gas per la mainnet, e chain ID 80002 per il testnet Amoy. Inserisca il chain ID nel codice di firma, così che una transazione non possa mai essere trasmessa alla rete sbagliata.

Le commissioni sono il motivo per cui i team scelgono Polygon, ma variano con la congestione e con il prezzo di POL. Costruisca la gestione delle commissioni su intervalli e legga il prezzo attuale del gas al momento dell’invio. Con Chaingateway, GET /api/v2/polygon/gasprice lo restituisce.

Ethereum è l’alternativa per i clienti che preferiscono la sua liquidità e il suo regolamento. Se servono entrambe, un’unica API su più chain significa scrivere il flusso di pagamento una sola volta. Per l’altro lato di questa configurazione, consulti l’API Ethereum.

I wallet di invio hanno bisogno di POL per il gas, anche quando l’asset inviato è uno stablecoin. Quando finanzia un wallet da una piattaforma di trading, scelga Polygon come rete di prelievo e controlli l’etichetta della rete prima di confermare. Un prelievo sulla rete sbagliata è un modo comune di perdere fondi durante la configurazione.

Come configuro i wallet e proteggo le chiavi?

Esistono due schemi comuni:

• Un indirizzo per cliente o per fattura. Ogni pagamento riceve un proprio indirizzo di deposito. Abbinare un trasferimento in entrata a un ordine diventa così banale, perché l’indirizzo destinatario lo identifica. Il costo è dover gestire più indirizzi e, in seguito, trasferire i fondi verso un wallet di tesoreria.
• Un indirizzo condiviso con riferimenti. È più semplice da gestire, ma un semplice trasferimento di token non ha un campo di riferimento. Si finisce per abbinare in base a importo e tempi, e questo si rompe quando due clienti pagano lo stesso importo.

Per la maggior parte dei flussi commerciali, gli indirizzi per ordine sono il disegno più pulito. Qualunque scelta faccia, mantenga queste abitudini:

• Non conservi mai le chiavi private nel controllo di versione, nei log o nel codice lato client.
• Separi i wallet di ricezione dalla tesoreria che detiene il saldo, così che la compromissione di uno non esponga l’altro.
• Limiti chi e che cosa può avviare un trasferimento in uscita, e registri ogni richiesta.
• Conservi il materiale delle chiavi in un modo che sopravviva alla perdita di una persona o di un server.

Chaingateway è non-custodial. POST /api/v2/polygon/addresses crea un wallet. Se invia una password, la chiave privata viene memorizzata cifrata con essa, e per inviare una transazione usa la password al posto della chiave. Chaingateway non memorizza la password e non può ripristinare un wallet se la perdete. Per il flusso di chiamate, consulti come creare un wallet crypto con un’API.

Come invio un pagamento in token su Polygon?

Polygon PoS è compatibile con EVM, quindi i trasferimenti di token seguono lo standard ERC-20. La specifica ERC-20 definisce due schemi di pagamento:

• Pagamento diretto: chi paga chiama transfer(recipient, amount), che emette un evento Transfer.
• Pagamento tramite contratto con prelievo: chi paga chiama prima approve(spender, amount), poi il contratto autorizzato chiama transferFrom(sender, recipient, amount).

Per un checkout semplice basta un trasferimento diretto. Le approvazioni contano quando uno smart contract incassa il denaro, come negli abbonamenti o nell’escrow. Mantenga le approvazioni strette: approvi l’importo necessario, non un’allowance illimitata.

Come invio con il codice del nodo grezzo?

Inviare direttamente significa costruire la transazione, stimare il gas, impostare il nonce, firmare, trasmettere e controllare l’inclusione. Per un prototipo è gestibile. In produzione servono anche un provider RPC affidabile, una logica di nuovo tentativo e un modo per sostituire le transazioni bloccate. La nostra guida su come inviare token ERC-20 confronta i metodi con wallet, codice e API.

Come invio con una sola chiamata REST?

Con Chaingateway, un trasferimento di token è una sola richiesta autenticata. Indica il mittente, il contratto del token, il destinatario e l’importo. I campi del gas sono facoltativi. La definizione OpenAPI indica come obbligatori from, contractaddress, to e amount.

curl -X POST https://app.chaingateway.io/api/v2/polygon/transactions/erc20 \
  -H "Authorization: Bearer $CHAINGATEWAY_TOKEN" \
  -H "X-Network: testnet" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "0xSenderAddress",
    "contractaddress": "0xTokenContract",
    "to": "0xRecipientAddress",
    "amount": 25.5,
    "password": "wallet-password"
  }'

X-Network: testnet esegue la richiesta su Amoy. Per la mainnet, ometta l’header. Lo stesso schema funziona sulle altre chain EVM, quindi aggiungere una seconda chain in seguito cambia il percorso, non il flusso. Per l’elenco completo degli endpoint, consulti la pagina dell’API Polygon e il file OpenAPI.

Come verifico che un pagamento sia arrivato?

Un hash di transazione dimostra solo che la transazione è stata inviata. Prima di segnare un ordine come pagato, controlli lo stato della transazione, il destinatario, l’importo del trasferimento di token e il contratto del token. I trasferimenti ERC-20 sono registrati nei log dell’evento Transfer, come definito nella specifica ERC-20, quindi è lì che si legge il trasferimento reale.

Il controllo sul contratto è quello che i team dimenticano più spesso. Chiunque può pubblicare un token chiamato «USDC» senza alcun valore. Confronti l’indirizzo del contratto nel log con quello inserito nella whitelist. La Sua routine di verifica dovrebbe confermare tutti questi punti:

1. La transazione è riuscita, non soltanto minata.
2. L’evento Transfer proviene dal contratto del token atteso.
3. Il destinatario corrisponde all’indirizzo emesso per questo ordine.
4. L’importo è almeno quello fatturato, nell’unità più piccola del token.
5. Sono passati abbastanza blocchi per la Sua tolleranza al rischio prima di rilasciare la merce.

Leggere i log grezzi significa decodificare a mano topic e dati. Il nostro approfondimento sull’evento Transfer di ERC-20 mostra la struttura. Chaingateway restituisce anche le transazioni decodificate con GET /api/v2/polygon/transactions/{txid}/decoded.

Come ricevo notifiche con i webhook?

Interrogare un indirizzo ogni pochi secondi spreca richieste e resta comunque indietro. Con un webhook, il servizio chiama il Suo endpoint quando viene rilevata una transazione corrispondente. Lo crea con POST /api/v2/polygon/webhooks. Il campo url è obbligatorio, e si filtra per to, from o contractaddress. Per il funzionamento, consulti i webhook Polygon.

Come costruisco il ricevitore in modo sicuro?

Queste regole valgono per qualsiasi fornitore:

• Verifichi la firma. Chaingateway aggiunge un header X-Signature dopo che Lei ha impostato un segreto personale. È un HMAC-SHA256 dell’ID della transazione, codificato in Base64 e calcolato con il Suo segreto. Consulti Verificare le firme dei webhook.
• Confronti in tempo costante. Usi la funzione di confronto sicuro del Suo linguaggio, non ==.
• Risponda subito. Restituisca subito uno stato 2xx e svolga il lavoro pesante in una coda.
• Preveda i duplicati. Lo stesso evento può arrivare due volte, per esempio dopo un nuovo invio di una notifica. Memorizzi un ID di transazione e ignori le ripetizioni.
• Preveda gli eventi mancati. Chaingateway non ripete automaticamente le notifiche fallite. Le elenchi con GET /api/v2/polygon/webhooks/notifications/failed e reinvii ciascuna con POST /api/v2/polygon/webhooks/notifications/{id}/retry.

Quali stati di pagamento conviene memorizzare?

Mantenga gli stati dei pagamenti piccoli ed espliciti: awaiting_payment, pending, confirmed, failed, expired. Ogni webhook corrisponde al massimo a una transizione. Se arriva un evento di errore per un pagamento già confermato, lo registri e avvisi una persona invece di sovrascrivere lo stato.

Come progetto il backend?

Tenga il codice specifico della chain ai margini. Metta un’interfaccia interna davanti alla chain, con metodi come createDepositAddress, sendPayment e getPaymentStatus, e tenga la logica degli ordini dall’altro lato. Aggiungere una chain significa allora aggiungere un’implementazione di quell’interfaccia, senza riscrivere il nucleo.

Il registro contabile deve essere Suo. Non consideri mai la chain o la dashboard di un fornitore come libro contabile. Memorizzi ogni pagamento atteso, ogni trasferimento osservato e il collegamento tra i due, così da poter riconciliare a fine giornata e spiegare qualsiasi differenza.

Che cosa controllo prima del lancio?

Verifichi in particolare tre cose: transazioni fallite, conflitti di nonce e variazioni del prezzo del gas.

Prima del lancio

• Esegua l’intero flusso sul testnet Amoy: crei un indirizzo, lo paghi, riceva il webhook, segni l’ordine come pagato.
• Riproduca due volte ogni webhook e verifichi che la seconda consegna non cambi nulla.
• Invii un pagamento con il token sbagliato, con un importo sbagliato (inferiore e superiore) e verso un ordine scaduto. Decida e verifichi che cosa succede in ciascun caso.
• Faccia fallire di proposito il Suo endpoint con un errore 500 e con un timeout, poi elenchi le notifiche fallite e le reinvii.
• Lanci due trasferimenti contemporanei dallo stesso wallet per far emergere eventuali conflitti di nonce.

Al lancio

• Parta con limiti bassi e un solo token.
• Segnali ogni trasferimento che resta in attesa oltre la soglia scelta.
• Controlli il saldo del wallet del gas, perché un saldo POL esaurito blocca ogni pagamento in uscita.
• Ruoti il segreto personale secondo una pianificazione e aggiorni insieme il ricevitore.

Errori comuni

• Fidarsi dell’hash invece del log dell’evento.
• Fidarsi di un webhook prima di averne verificato la firma.
• Fissare nel codice un prezzo del gas.
• Saltare il controllo del contratto del token.
• Tenere insieme le chiavi del wallet caldo e quelle della tesoreria.

I piani partono da 49 € al mese (490 € all’anno), con una prova gratuita di 7 giorni che non richiede carta. Consulti la pagina dei prezzi.

Fonti

• Documentazione Polygon: endpoint RPC e chain ID
• ERC-20: Token Standard
• ESMA: Regolamento sui mercati delle cripto-attività (MiCA)
• FinCEN: linee guida su soggetti che amministrano, scambiano o utilizzano valute virtuali

Consigliati

• API Blockchain Polygon – Pagamenti USDC e USDT via REST
• API Blockchain – Un’unica API REST per Bitcoin, Ethereum e 5 Altre