I client che oggi parlano direttamente con IGFS (N&TS/Nexi PGW REST) passano su PayGlobe senza modificare una riga del loro codice. Cambiano tre valori di configurazione. Nient'altro.
L'adapter è l'equivalente IGFS di Mandala, il nostro adapter Stripe-compatibile: parla il protocollo di rete di IGFS sul lato in ingresso e instrada tutto verso PayGlobe. Per il client migrato, PayGlobe è IGFS.
| Valore | Prima (IGFS reale) | Dopo (adapter) |
|---|---|---|
| Base URL | https://…netsgroup.com/MONEYNET_CG_SERVICES |
https://api.payglobe.it/MONEYNET_CG_SERVICES |
merId (= keyId) |
assegnato da N&TS | emesso da PayGlobe |
| secret HMAC | assegnato da N&TS | emesso da PayGlobe |
/MONEYNET_CG_SERVICES
Non è un vezzo estetico: la firma HTTP-Signature copre (request-target),
cioè metodo + path completo. Se cambiasse il path cambierebbe la stringa firmata e il
client dovrebbe toccare il codice. L'adapter espone quindi lo stesso context-path
(SERVER_CONTEXT_PATH), così il client cambia solo l'host.
IGFS è un marchio e un prodotto di N&TS Group. PayGlobe non è affiliata a N&TS Group e non è autorizzata a distribuire la documentazione di integrazione IGFS. Questa pagina non è, e non sostituisce, quella documentazione: non spiega come integrarsi con IGFS.
È rivolta esclusivamente a chi ha già un'integrazione IGFS attiva e la relativa documentazione ricevuta da N&TS, e descrive soltanto cosa cambia nella sua configurazione per far parlare quella stessa integrazione con PayGlobe. Le specifiche del protocollo restano da chiedere a N&TS Group.
Non è solo una sostituzione alla pari: restando fermo, il client eredita tutto ciò che PayGlobe sa fare e che IGFS da solo non fa.
Stessi path, stesso JSON txHead/txReq/txRes, stessa
HTTP-Signature, stesso IGFS_000. Cambiano tre valori di configurazione.
Bizum, PayPal, Satispay, crypto, buoni pasto: il compratore sceglie sul checkout PayGlobe e il client riceve una normale transazione IGFS riuscita. Già successo in collaudo, non è una promessa.
Rimettendo i tre valori di prima il client riparla con IGFS. Nessuna migrazione di dati, nessuno stato da riportare indietro.
Un fallimento torna col suo codice — IGFS_20090 per l'annullamento
del compratore — e la descrizione originale, così la logica di retry del client
continua a funzionare.
Modalità full-routing: l'IGFS reale non viene mai chiamato. L'adapter verifica la firma, traduce e instrada al backend PayGlobe — esattamente come fa Mandala per i client Stripe.
POST /pgw/payment/init/api/payment/initiate/pgw/payment/init.
L'adapter risponde con txHead + paymentId + redirectURL e
resultCode = IGFS_000, la forma che il client già si aspetta.redirectURL.
È la pagina di checkout PayGlobe, che nasconde il gateway sottostante.{merId, txId, paymentId}, come farebbe IGFS.GET /pgw/payment/verify
firmato e ottiene l'esito autorevole OK | PENDING | KO.
È il modello pull di IGFS: la notifica non trasporta dati sensibili, quindi non serve firmarla in uscita.Contratto di riferimento: lo swagger ufficiale N&TS "E-Commerce Payments Services API". Sotto, la copertura reale — senza arrotondamenti.
| Operazione IGFS | Instradata su | Stato | Note |
|---|---|---|---|
POST /pgw/payment/init | POST /api/payment/initiate | fatto | accetta sia la forma top-level sia poiInfo annidato |
GET /pgw/payment/verify | GET /api/payment/status/{id} | fatto | alias /verification |
POST /pgw/payment/capture | POST /api/payment/finalize/no-voucher | fatto | via origTranId |
POST /pgw/payment/reversal | POST /api/payment/cancel/{id} | fatto | via origTranId |
POST /pgw/payment/refund | POST /api/payment/refund/{id} | fatto | su IGFS il parziale non è disponibile |
| notify / callback server→client | webhook PayGlobe → relay | fatto | outbox transazionale, retry con backoff |
POST /pgw/paybymail/initGET /pgw/paybymail/verify | /api/payment-links/* | da fare | il motore esiste già lato PayGlobe: è cablaggio |
DELETE /pgw/paybymail/delete | cancel payment link | da fare Ver. 20 | nuovo nella spec |
POST /pgw/payment/selector | — | da fare | |
GET /pgw/tokenizer/checkDELETE /pgw/tokenizer/delete | — | coming soon | PayGlobe ha già la tokenizzazione IGFS: manca solo l'esposizione in protocollo nativo |
POST /pgw/checkout/completeGET /pgw/checkout/info | — | da fare Ver. 19 | servizi checkout, mai analizzati |
5 operazioni su 14, più il ritorno asincrono. Sono le cinque che compongono il flusso e-commerce completo (autorizza → incassa → storna → rimborsa), cioè quelle che servono a un merchant per operare dal primo giorno.
È il punto che rende la migrazione a costo zero: l'adapter verifica in ingresso la stessa HTTP-Signature (draft-cavage-10) che il client già calcola oggi. Nessuna libreria da cambiare, nessun algoritmo nuovo. Qui sotto non c'è la specifica della firma — quella è nella documentazione N&TS che il client già possiede — ma solo l'unica riga che cambia: l'host.
digest = "SHA-256=" + Base64(SHA256(body)) — solo su POSTheaders(request-target) include la query string — la verify porta merId, paymentId, txId come parametrikeyId deve valere quanto il merId nel corpo: l'adapter lo verifica e rifiuta il mismatchX-signature-salt), verificata contro il vettore ufficiale N&TSQuello che serve fare, e da chi.
PayGlobe emette merId + secret e li mappa sull'API key
del merchant. Una riga per client. Il merchant non deve aprire alcun rapporto nuovo con N&TS.
Il client cambia host, merId e secret nella propria
configurazione. Prerequisito: che li legga da config e non li abbia
cablati nel codice — l'hostname soprattutto.
Init + verify su un merchant di test. Se la firma torna, torna tutto:
è la parte che rompe per prima quando un proxy altera Host o path.
Verifica che notifyURL e callbackURL del client vengano
raggiunti e che il suo verify di conseguenza risponda come prima.
Capture, reversal e refund usano origTranId: vanno provate su una
transazione reale, perché dipendono dalla mappa tranId ↔ transazione.
Il rollback è simmetrico e immediato: si rimettono i tre valori originali e il client torna su IGFS. Nessuna migrazione di dati, nessuno stato da riportare indietro.
Qualsiasi proxy davanti all'adapter deve preservare l'header Host e il
path della richiesta: entrambi entrano nella stringa firmata. Un proxy che
riscrive l'uno o l'altro produce un 401 sistematico — e sembrerà un problema
di credenziali quando invece è di rete.
L'adapter è in pre-produzione: gira sull'infrastruttura di produzione e il flusso completo è stato percorso da un client reale che non ha modificato il proprio codice, ma su merchant di collaudo e non ancora aperto a traffico vivo. Sotto c'è la linea esatta fra ciò che è verificato sul campo e ciò che non c'è ancora — nessuna delle due colonne è una previsione.
verify con status: OKIGFS_20090 con la
descrizione originale, non come un KO mutoverify, che è il modello IGFS corretto, ma non riceve la chiamatapaymentId fuori formato: restituiamo l'identificativo
PayGlobe (36 caratteri) mentre la specifica ne ammette 32 e IGFS ne manda 18 numericiorder (indirizzi, prodotti, IVA, fattura) e i dati anagrafici del
compratore non vengono inoltratinotifyURL vs callbackURL.
Lo swagger descrive callbackURL come POST server-to-server
{merId, txId, paymentId} e notifyURL come pagina di atterraggio
del browser (in coppia con errorURL). Oggi l'adapter fa POST su
entrambi e non passa la notifyURL a PayGlobe come URL di ritorno.
piType ammessi
(rimossi UCPO/UCSC, SMSG→SAMP,
nuovi SAPP, CLCK, CCPT, PCIP).
Quasi tutti i 401 al primo collaudo sono configurazione vecchia sopravvissuta:
keyId del vecchio merchant, oppure l'header Host del vecchio host IGFS
mentre la firma ne contiene un altro. Regola che elimina la classe intera:
l'host non va configurato a parte, va derivato dalla Base URL, e deve comparire
identico nell'header Host e nella prima riga della stringa firmata.
Sul filo, no: stessi path, stesse forme JSON, stesso IGFS_000, stessa firma.
L'unica differenza osservabile è il redirectURL, che punta al checkout
PayGlobe invece che all'host N&TS — per scelta, così il gateway sottostante resta nascosto.
Entra in PayGlobe come qualsiasi altro merchant: dashboard, rimborsi, dispute, report, webhook, e l'accesso agli altri metodi di pagamento — che dal suo codice IGFS, da solo, non avrebbe mai potuto raggiungere.
Il raggio d'azione sul core PayGlobe è nullo: l'adapter è solo un altro client
di /api/payment/*, come Mandala. Il rischio è tutto sul lato client,
ed è mitigato dal fatto che il rollback sono tre valori di configurazione.
Sarebbe un proxy, non una migrazione: il merchant resterebbe legato al contratto N&TS e non guadagnerebbe nulla. In full-routing invece il traffico entra nel nostro instradamento multi-PSP e il merchant diventa a tutti gli effetti nostro.