Passa al contenuto principale

Flusso di pagamento con Hosted Payment Page

Il flusso di pagamento tramite Hosted Payment Page è basato su un modello redirect + verifica tramite chiamata. In questa sezione è spiegata la sequenza end‑to‑end tra Buyer, Merchant, Numia (IGFS), ACS (3DS) e Acquirer.

Il flusso di pagamento tramite Hosted Payment Page è basato su un modello redirect + verifica tramite chiamata.
In questa sezione è spiegata la sequenza end-to-end tra Buyer, Merchant, Numia (IGFS), ACS (3DS) e Acquirer.

E-com payment

1. Attori coinvolti​

Nel flusso di pagamento sono coinvolti i seguenti attori:

  • Merchant: sistema eCommerce o backend applicativo che inizializza la transazione e gestisce l’ordine.
  • Cliente (Buyer): utente finale che effettua il pagamento.
  • Numia (IGFS): piattaforma di pagamento che espone la Hosted Payment Page e gestisce le fasi di pagamento.
  • ACS / Circuiti: sistemi coinvolti nell’autenticazione 3D Secure (quando prevista).
  • Acquirer: gestisce l’instradamento della richiesta autorizzativa verso circuito/issuer e restituisce l’esito autorizzativo.

2. Sequenza end‑to‑end​

Il flusso di pagamento tramite Hosted Payment Page si articola nei seguenti passaggi:

  1. Checkout ordine Il cliente conferma l’ordine sul sito del merchant.

  2. Inizializzazione transazione Il merchant invia a Numia la chiamata di inizializzazione della transazione (01_Init) per creare il pagamento e impostare i parametri necessari (importo, valuta, orderId, URL di ritorno, ecc.).

  3. Ricezione redirectURL Numia risponde restituendo un redirectURL, che identifica la sessione di pagamento e la pagina da mostrare al cliente.

  4. Redirect del browser verso Numia Il merchant reindirizza il browser del cliente verso la Hosted Payment Page utilizzando il redirectURL.

  5. Compilazione dati di pagamento Il cliente visualizza la pagina di pagamento Numia e inserisce i dati richiesti (es. dati carta o selezione metodo di pagamento alternativo, se disponibile).

  6. Autenticazione 3D Secure (se necessaria) Se previsto dalla configurazione e/o richiesto per SCA, viene avviato il flusso di autenticazione 3D Secure tramite ACS. Al termine, l’ACS restituisce l’esito dell’autenticazione.

  7. Autorizzazione Numia richiede l’autorizzazione della transazione all’acquirer, che gestisce la catena autorizzativa verso circuito/issuer.

  8. Redirect verso il merchant (notifyURL / errorURL) Al termine del pagamento, Numia reindirizza il cliente verso uno degli URL configurati dal merchant:

    • notifyURL: utilizzato a valle di un percorso completato correttamente.
    • errorURL: utilizzato in caso di errore, rifiuto o annullamento.
    • callbackURL: se avvalorato, il gateway restituirà i dati per recuperare le informazioni della transazione tramite metodo Verify server‑to‑server.

  9. Verifica esito (Verify) – server‑to‑server Dopo il redirect, il merchant verifica l’esito della transazione tramite chiamata server‑to‑server (Verify).

  10. Dettagli transazione Numia restituisce i dettagli completi della transazione (esito, identificativi, importo, ecc.), che il merchant utilizza per aggiornare lo stato dell’ordine.

3. notifyURL, errorURL, callbackURL e Verify: cosa fanno e perché sono importanti​

notifyURL​

È l’URL di ritorno verso il merchant a seguito di un flusso completato. Serve a riportare l’utente sul sito merchant e consentire la visualizzazione della pagina di esito.

Nota importante: il redirect browser non è un canale affidabile per determinare lo stato finale della transazione.

errorURL​

È l’URL di ritorno verso il merchant in caso di errore o esito negativo. Serve a riportare l’utente sul sito merchant e mostrare una pagina di pagamento non riuscito.

callbackURL​

Il gateway di pagamento restituisce i dati identificativi dell'operazione, da utilizzare successivamente nella chiamata di Verify non appena l'operazione ha un esito definitivo.

Verify (server‑to‑server)​

La chiamata Verify consente al merchant di ottenere lo stato effettivo della transazione lato Numia.

È fondamentale perché:

  • il cliente può non completare il redirect
  • il redirect può essere interrotto
  • alcuni esiti possono essere temporaneamente pending
  • solo una verifica server‑to‑server garantisce un aggiornamento consistente dello stato ordine

Best practice: aggiornare lo stato ordine esclusivamente in base all’esito restituito da Verify.