Esito e gestione errori
Ogni transazione processata tramite Numia restituisce un esito strutturato che consente al merchant di determinare lo stato effettivo del pagamento.
La corretta interpretazione dei codici di risposta è fondamentale per:
- aggiornare in modo consistente lo stato ordine;
- distinguere tra rifiuti autorizzativi ed errori tecnici;
- identificare eventuali problemi di integrazione;
- gestire correttamente i casi pending o 3D Secure.
Questa sezione descrive la struttura degli esiti, la classificazione dei codici di risposta e le linee guida operative per una gestione corretta lato merchant.
1. Struttura dell’esito transazione
Ogni transazione processata tramite IGFS® Payment Gateway restituisce un codice di risposta.
L’esito positivo è identificato da un unico codice: IGFS_000.
Tutti gli altri codici identificano:
- rifiuti autorizzativi
- errori tecnici
- errori di integrazione
- errori di configurazione
- stati pending
Gli esiti sono visibili:
- nella risposta tecnica restituita al merchant
- nel Merchant Back Office
2. Classificazione degli esiti
Ogni codice riporta un campo Origine Esito, che identifica il soggetto che ha generato il risultato della transazione.
| Origine | Significato |
|---|---|
| PAYMENT GATEWAY | Errore tecnico o di integrazione lato gateway |
| ACQUIRER | Problema lato convenzionamento o instradamento |
| ISSUER | Rifiuto o blocco da parte della banca emittente |
| ACQUIRER o ISSUER | Rifiuto generico autorizzativo |
Questa distinzione è fondamentale per stabilire chi deve intervenire:
- Merchant (errore integrazione)
- Supporto tecnico
- Cliente finale (Issuer)
- Acquirer
3. Esito positivo
IGFS_000 – TRANSACTION OK
La transazione è stata autorizzata correttamente.
Il merchant può:
- aggiornare lo stato ordine a “pagato”
- procedere con fulfillment o consegna
4. Esiti negativi autorizzativi
Sono rifiuti legati alla carta, al plafond o a controlli antifrode.
Esempi comuni:
| Codice | Descrizione |
|---|---|
| IGFS_002 | EXPIRED CARD |
| IGFS_004 | CARD IN BLACK LIST |
| IGFS_008 | AUTHORIZATION DENIED |
| IGFS_020 | INVALID CARD |
| IGFS_030 | INSUFFICIENT FUNDS |
| IGFS_102 | SUSPECTED FRAUD |
| IGFS_121 | AMOUNT LIMIT EXCEEDED |
| IGFS_815 | BLOCKED CARD |
| IGFS_208 | LOST CARD |
| IGFS_209 | STOLEN CARD |
In questi casi:
- il merchant non deve modificare l’integrazione
- il cliente deve contattare l’emittitore della carta
Il rifiuto deriva dalla catena autorizzativa (Acquirer / Circuito / Issuer).
5. Errori di integrazione (Payment Gateway)
Questi errori indicano problemi tecnici nella richiesta inviata dal merchant.
Esempi:
| Codice | Descrizione |
|---|---|
| IGFS_032 | INVALID AMOUNT |
| IGFS_085 | WRONG CURRENCY |
| IGFS_20000 | MISSING DATA |
| IGFS_20022 | INVALID SIGNATURE |
| IGFS_20023 | INVALID PAYMENTID |
| IGFS_20026 | DUPLICATED SHOPID |
| IGFS_20027 | INVALID REQUEST FORMAT |
| IGFS_20035 | INVALID ORDERID |
| IGFS_20036 | INVALID PAN |
| IGFS_20037 | INVALID CVV2 |
Questi errori indicano tipicamente:
- parametri mancanti
- importo non valido
- valuta non ammessa
- firma digitale errata
- ShopID duplicato
- identificativi non coerenti
In questi casi il merchant deve:
- verificare la correttezza dei parametri inviati
- controllare il calcolo della firma
- verificare la configurazione del terminale
- assicurarsi che gli ID transazione siano univoci
6. Stati Pending
Alcuni codici indicano che la transazione non è ancora conclusa.
| Codice | Descrizione |
|---|---|
| IGFS_814 | TRANSACTION IN PROGRESS |
| IGFS_890 | PENDING PAYMENT |
Significato:
- la transazione è ancora in corso
- l’autorizzazione non è ancora definitiva
- il pagamento è in attesa di completamento su sistema terzo
Il merchant deve:
- attendere alcuni minuti
- ripetere la chiamata di verifica (
Verify) - non generare un nuovo ordine
7. Stato Transazione 3DS
Per le transazioni con autenticazione 3D Secure, il campo tranStatusReason fornisce il dettaglio del motivo di esito.
Alcuni codici rilevanti:
| Code | Descrizione |
|---|---|
| 01 | Card authentication failed |
| 05 | Expired card |
| 09 | Security failure |
| 11 | Suspected fraud |
| 14 | Transaction timed out at the ACS |
| 22 | ACS technical issue |
| 26 | Authentication attempted but not performed |
Questi codici indicano problematiche specifiche in fase di autenticazione SCA / 3DS.
8. Linee guida per la gestione lato Merchant
1. Non basarsi esclusivamente sul redirect browser
Il redirect finale non garantisce la conclusione della transazione.
È sempre raccomandato utilizzare il servizio di verifica lato server (Verify).
2. Distinguere correttamente le tipologie di errore
- Errori Payment Gateway → verificare integrazione
- Errori Acquirer / Issuer → il cliente deve contattare la banca
- Errori sistemici → coinvolgere supporto tecnico
3. Gestire correttamente i casi pending
- non creare nuovi ordini
- ripetere verifica stato
- aggiornare l’ordine solo a esito definitivo
4. Non forzare retry automatici su rifiuti Issuer
In caso di:
- sospetta frode
- carta bloccata
- fondi insufficienti
è necessario un intervento lato cliente (emittente / banca), non un semplice retry automatico.