Prevenire i pagamenti duplicati dall’ECR

Un pagamento duplicato inizia quasi sempre nello stesso modo: l’ECR perde la risposta a un pagamento già inviato, quindi lo invia nuovamente oppure consente al cliente di pagare in un altro modo. Questo articolo descrive le regole che l’ECR deve implementare e la logica di recupero da eseguire con la Local API (Nexo Retailer 3.1, JSON su HTTP, porta 8080).

Perché si verificano i duplicati

Il terminale di pagamento e l’acquirer conoscono solo le richieste che hanno ricevuto. Non possono sapere se un secondo pagamento per lo stesso carrello è un errore o un nuovo acquisto. Solo l’ECR lo sa, quindi la prevenzione dei duplicati è responsabilità dell’ECR. Cause tipiche:

• Il pagamento con carta viene approvato, la risposta viene persa (interruzione della rete, timeout o arresto anomalo dell’ECR) e l’operatore preme nuovamente Pagamento con carta, oppure il cliente paga in contanti. Nessuno sa che la carta è stata addebitata, quindi nessuno annulla il pagamento.
• L’operatore fa doppio clic oppure la libreria HTTP riprova automaticamente un POST dopo un errore di connessione: la stessa richiesta raggiunge due volte il terminale.
• L’ECR si riavvia durante un pagamento e avvia la vendita successiva senza leggere l’esito di quella interrotta.

Cosa fa e cosa non fa per voi il terminale di pagamento

Due componenti rispondono alle vostre richieste: il server HTTP del terminale, che mantiene uno scambio per endpoint (un POST lo apre, il 200 finale su GET lo chiude), e l’applicazione di pagamento, che esegue la transazione. Possono trovarsi in stati diversi e la logica di recupero controlla entrambi.

Regole da implementare sull’ECR

1. Scrivere un registro della transazione prima dell’invio

Prima di ogni POST di un pagamento, di un’acquisizione della carta o di un annullamento, scrivete una voce in uno storage persistente: ServiceID, SaleTransactionID (TransactionID e TimeStamp), endpoint, importo, valuta e stato IN_FLIGHT. Sul 200 finale, memorizzate POIData.POITransactionID e il risultato, quindi chiudete la voce. Dopo un riavvio, una voce ancora nello stato IN_FLIGHT rappresenta un pagamento dall’esito sconosciuto: risolvetelo prima di qualsiasi altra operazione su quella postazione.

2. Usare un nuovo ServiceID per ogni richiesta

• Ogni richiesta riceve un nuovo ServiceID, inclusi /status, /diagnosis, /abort, /login e un nuovo tentativo di pagamento confermato come non elaborato. Salvate il contatore; non usate mai una costante come "0".
• Il SaleTransactionID identifica la vendita: è univoco per ogni carrello, non cambia tra i tentativi relativi allo stesso carrello ed è sempre inviato insieme al relativo TimeStamp.

3. Bloccare la vendita quando l’esito è sconosciuto

Disabilitate il pulsante Pagamento con carta non appena viene premuto. Quando una voce è nello stato IN_FLIGHT per un carrello: nessuna nuova richiesta di pagamento, nessun altro metodo di pagamento (contanti, buono, seconda carta), nessuna nuova vendita su quella postazione. Il blocco termina sempre con un risultato finale, un annullamento controllato o la procedura per i casi irrisolti descritta di seguito.

4. Non consentire al livello HTTP di riprovare un POST

Disattivate i tentativi automatici nel client HTTP e in qualsiasi proxy tra l’ECR e il terminale. Un POST che fallisce a livello di trasporto deve passare alla logica di recupero, non a un nuovo tentativo.

5. Eseguire il polling fino a 200, con timer adeguati a un pagamento reale

POST /payment restituisce 202. Quindi chiamate GET /payment (senza corpo) finché non restituisce 200.

Il terminale applica un proprio timeout per endpoint, impostato nella configurazione del server HTTP: 180 s su /payment, uguale su ogni terminale. È il tempo durante il quale il terminale attende la risposta finale dell’applicazione di pagamento; superato tale tempo, GET restituisce 408 invece della risposta. Mantenete la finestra del pagamento al di sotto di questo valore. Quando la finestra del pagamento scade, non rilasciate la schermata e non inviate nuovamente la richiesta: passate alla logica di recupero.

6. Eseguire l’annullamento con il POITransactionID se sono stati utilizzati due metodi di pagamento

Se un pagamento con carta risulta approvato dopo che il cliente ha già pagato in un altro modo, inviate una ReversalRequest indicando OriginalPOITransaction.POITransactionID dal registro o da /status. Non eseguite mai l’annullamento utilizzando il SaleTransactionID.

La logica di recupero

Eseguitela quando l’ECR si avvia con una voce IN_FLIGHT, quando un polling non riesce o scade la finestra del pagamento, quando un POST restituisce 403 o fallisce a livello di trasporto e quando GET /payment restituisce 408 o 423 con una voce ancora nello stato IN_FLIGHT. Usate un nuovo ServiceID per ogni chiamata. I tre passaggi rispondono a tre domande diverse: è ancora aperto uno scambio, l’applicazione di pagamento è ancora occupata, qual è stato l’ultimo risultato.

Passaggio 1: è ancora aperto uno scambio HTTP?

GET /blocked elenca ogni endpoint con uno scambio aperto, come JSON semplice:

GET http://<terminal-ip>:8080/blocked

200 {"blocked":["/payment"]}     a result is waiting, or still being produced
200 {"blocked":[]}               no open exchange

• /payment è elencato: riprendete GET /payment fino a 200. Quella risposta è l’esito, indipendentemente da quanto tempo sia trascorso dalla fine del pagamento. Non chiamate ora /status: restituirebbe la vendita precedente. Se il GET di svuotamento restituisce 408 o 423, passate al punto 2.
• L’elenco è vuoto: la risposta finale è già stata letta (un 200 o un 408) oppure il pagamento non è mai iniziato. Il punto 2 indica se l’applicazione di pagamento sta ancora elaborando qualcosa.

Passaggio 2: l’applicazione di pagamento è ancora occupata?

POST http://<terminal-ip>:8080/diagnosis
{ "MessageHeader": { ..., "MessageCategory":"Diagnosis", "ServiceID":"1042" },
  "DiagnosisRequest": {"POIID":"POI_01"} }

200
{ "DiagnosisResponse": { "Response": {"Result":"Success"},
                         "POIStatus": {"GlobalStatus":"OK"}, ... } }

Passaggio 3: leggere l’ultima transazione completata

POST http://<terminal-ip>:8080/status
{ "MessageHeader": { ..., "MessageCategory":"TransactionStatus", "ServiceID":"1043" },
  "TransactionStatusRequest": {} }

200
{ "TransactionStatusResponse": {
    "Response": {"Result":"Success"},
    "RepeatedMessageResponse": {
      "MessageHeader": {"MessageCategory":"Payment","ServiceID":"1040", ...},
      "PaymentResponse": {
        "Response": {"Result":"Success"},
        "SaleData": {"SaleTransactionID":{"TransactionID":"SALE-1040","TimeStamp":"..."}},
        "POIData":  {"POITransactionID":{"TransactionID":"9991","TimeStamp":"..."}},
        "PaymentResult": {"AmountsResp":{"AuthorizedAmount":"11.99","Currency":"EUR"}}, ... } } } }

La transazione restituita corrisponde alla voce del registro solo se RepeatedMessageResponse.MessageHeader.ServiceID, SaleTransactionID.TransactionID e SaleTransactionID.TimeStamp sono uguali, MessageCategory è Payment e l’importo è quello richiesto (o inferiore, in caso di approvazione parziale).

Procedura per i casi irrisolti

• Mantenete la voce nello storage persistente con stato UNRESOLVED, oltre a postazione, importo e ora, e avvisate il responsabile del negozio o il back office. Un altro metodo di pagamento è consentito solo tramite questo percorso esplicito, mai in modo silenzioso.
• Quando il terminale è nuovamente raggiungibile e inattivo, eseguite automaticamente i passaggi da 1 a 3 per ogni voce UNRESOLVED. Se il pagamento con carta risulta approvato e nel frattempo è stato utilizzato un altro metodo di pagamento, annullatelo (regola 6).
• Se il risultato non può più essere letto dal terminale, eseguite la riconciliazione con il report delle transazioni dell’esercente prima di rimborsare il cliente.

Annullare quando il cliente rinuncia

Se il pagamento è ancora in corso oltre la finestra del pagamento (ad esempio, il cliente si è allontanato durante la richiesta del PIN), l’operatore può annullarlo: inviate un AbortRequest il cui MessageReference contiene il ServiceID del pagamento, quindi continuate a eseguire il polling di GET /payment. Il 200 finale con ErrorCondition: Aborted costituisce l’esito. Dopo un’acquisizione della carta (pagamento in due passaggi), usate la variante Admin (AdminRequest con DualTransactionAborted) descritta nelle specifiche della Local API.

Cosa vede l’operatore o il cliente