Generatore
Compila i campi e il codice si aggiorna mentre scrivi. Sotto trovi il payload riga per riga, con il conteggio dei byte: il limite dello standard è 331 byte, non 331 caratteri.
Da mostrare sempre accanto al codice
Non è una cortesia: lo standard prevede questo uso solo se i dati sono visibili anche in chiaro, e in Italia è probabile che sia questo il canale che funziona davvero.
Il payload, riga per riga
| # | Campo | Contenuto | Byte |
|---|
Ispettore
Incolla il contenuto di un QR letto da un'altra applicazione e vedi come viene interpretato, campo per campo. Serve quando un codice viene rifiutato e non è chiaro perché.
| # | Campo | Contenuto |
|---|---|---|
| Nessun payload analizzato. | ||
Funziona davvero con la tua banca?
Non lo sappiamo, e nemmeno chi dice di saperlo. Non esiste nessuna documentazione ufficiale di una banca italiana che dichiari di leggere l'EPC QR. Le liste che circolano online — quelle che nominano Intesa, UniCredit, Fineco e le altre — vengono da siti commerciali che non citano nessuna fonte bancaria.
L'unica app con supporto documentato e datato è N26 (2021). Le app italiane hanno uno scanner QR, ma è pensato per pagoPA, i bollettini e Bancomat Pay: sono standard diversi, e su un payload EPC di solito restituiscono un errore.
Quindi qui non trovi una tabella di compatibilità copiata da qualcun altro. Trovi uno strumento per misurarla tu, che è l'unico dato che vale.
Il codice di prova
Un bonifico da 1 centesimo verso l'IBAN che hai messo nel generatore. Inquadralo con l'app della tua banca e guarda cosa succede: se apre il modulo del bonifico già compilato, se lo apre a metà, o se dà errore. Non confermare il pagamento: quello che conta è se i campi arrivano.
Annota l'esito
Resta su questo dispositivo, nel browser. Serve a produrre un dato onesto, incluso quello negativo: sapere che un'app non legge il codice è informazione, non un fallimento.
| App | Esito |
|---|
Come si integra
La libreria che genera questa pagina è la stessa che puoi installare. Nessuna dipendenza nel nucleo, stesso codice nel browser e in Node.
Tre righe per il caso normale
import { buildEpcPayload, buildOrderReference, validatePayment } from 'epc-qr-kit'
import { renderEpcQrSvg } from 'epc-qr-kit/qr'
const pagamento = {
name: 'IGE Software S.r.l.', // esattamente l'intestatario del conto
iban: 'IT60X0542811101000000123456',
amount: 49.9,
structuredReference: buildOrderReference(1234, { prefix: 'IGE', padTo: 10 }),
}
if (validatePayment(pagamento).some((p) => p.severity === 'error')) { /* mostra l'errore */ }
document.querySelector('#qr').innerHTML = renderEpcQrSvg(pagamento, { border: 4 })Il giro completo di un ordine
Dove sta il lavoro vero: non nel generare il codice, ma nel sapere che il bonifico è arrivato.
1. ordine creato genera il riferimento RF e salvalo come chiave univoca
RF37IGE0000001234 → il checksum rileva qualunque corruzione
2. pagina di checkout mostra il QR E i dati in chiaro (IBAN, nome, importo, RF)
stato dell'ordine: in attesa
3. il cliente paga nessun callback: il tuo sistema non lo sa
4. estratto conto chiedi alla banca il CAMT.053, non l'MT940
un RF valido finisce in RmtInf/Strd/CdtrRefInf/Ref
un RF corrotto finisce in RmtInf/Ustrd → coda manuale
5. riconciliazione cerca per (riferimento RF, importo), non solo per riferimento
l'importo non è protetto: gestisci parziali ed eccedenzePerché il riferimento RF e non una causale libera
Con una causale libera il cliente riscrive, tronca o cancella il testo, l'app lo accorcia a lunghezze diverse, gli accenti si perdono. Il risultato è che non riesci a distinguere un errore di battitura da un ordine diverso: il confronto diventa approssimativo, quindi manuale. Il riferimento ISO 11649 ha una cifra di controllo MOD 97-10 — lo stesso algoritmo dell'IBAN — e sta in un campo che lo standard marca come non modificabile dall'utente.
Il boilerplate
Nel repository, sotto boilerplate/, ci sono tre punti di partenza da copiare:
un checkout in HTML e JavaScript senza dipendenze, un componente React, e uno script Node che
genera l'SVG lato server per email e PDF.
Cosa questo QR non fa
La parte che di solito si scopre in produzione. Meglio saperla adesso.
Non ti dice che il pagamento è avvenuto. Un bonifico non ha callback. Il QR trasporta dei dati, non apre un canale: la conferma arriva solo quando leggi l'estratto conto. Se ti serve la conferma in tempo reale, questo strumento non basta.
L'importo non è protetto. Lo standard marca come "fissi" il BIC, il nome, l'IBAN e il riferimento strutturato: l'app non dovrebbe permettere di modificarli. L'importo non è in quell'elenco. Chi paga può cambiare la cifra prima di confermare, quindi la riconciliazione va fatta sulla coppia riferimento + importo.
Il nome deve combaciare, dal 9 ottobre 2025. Il Regolamento (UE) 2024/886 impone la verifica del beneficiario su tutti i bonifici: la banca di chi paga confronta IBAN e nome e restituisce un esito. Se nel QR scrivi il nome commerciale invece della ragione sociale registrata, ogni cliente vede un avviso di mancata corrispondenza, e molti si fermano lì. È il singolo campo che fa fallire più integrazioni.
Il link che apre l'app della banca non esiste.
sepa:// e bank:// sono inventati. payto: è uno standard
vero (RFC 8905) ma nessuna app bancaria lo registra come gestore. Gli universal link delle
banche italiane esistono, ma sono privati, non documentati e cambiano senza preavviso.
Per curiosità, ecco il payto: del pagamento qui sopra — quasi certamente il tuo
telefono non saprà cosa farne:
—
Se ti serve di più, le strade sono queste
EPC QR
Costo zero, nessun intermediario, si integra in un pomeriggio. Chi paga fa comunque un passaggio manuale, e potrebbe non riuscire a leggere il codice.
Quello che trovi in questa pagina
PSD2 · avvio del pagamento
Si apre l'app della banca con il bonifico già compilato e non modificabile, e ricevi la conferma via webhook. Serve un provider licenziato — Fabrick, Nexi, Tink, TrueLayer — con contratto e commissione a transazione.
L'unica con precompilazione e conferma
Request-to-Pay
La richiesta di pagamento arriva dentro l'app del cliente, che approva con un tocco. In Italia è partita nel 2025 via CBI, EBA CLEARING e Nexi, per ora sulla PA e in estensione al corporate. Passa da un PSP aderente.
Promettente, non ancora self-service
pagoPA e CBILL
Riconciliazione automatica e notifica di esito, ma richiedono di essere Ente Creditore aderente o consorziato CBI.
Non disponibili a un e-commerce privato