Dubbele betalingen vanaf de ECR voorkomen

Een dubbele betaling begint bijna altijd op dezelfde manier: de ECR verliest het antwoord op een betaling die hij al heeft verzonden en verzendt die vervolgens opnieuw of laat de klant op een andere manier betalen. Dit artikel bevat de regels die uw ECR moet implementeren en de herstelprocedure die moet worden uitgevoerd met de Local API (Nexo Retailer 3.1, JSON over HTTP, poort 8080).

Waarom dubbele betalingen gebeuren

De betaalterminal en de acquirer weten alleen welke aanvragen ze hebben ontvangen. Ze kunnen niet bepalen of een tweede betaling voor hetzelfde winkelmandje een vergissing of een nieuwe aankoop is. Alleen de ECR weet dat, dus het voorkomen van dubbele betalingen is de verantwoordelijkheid van de ECR. Typische oorzaken:

• De kaartbetaling wordt goedgekeurd, het antwoord gaat verloren (netwerkonderbreking, time-out of crash van de ECR) en de kassier drukt opnieuw op Kaartbetaling, of de klant betaalt contant. Niemand weet dat de kaart werd belast, dus niemand draait de betaling terug.
• De kassier klikt tweemaal, of de HTTP-bibliotheek probeert na een verbindingsfout stilzwijgend opnieuw een POST uit te voeren: dezelfde aanvraag bereikt de terminal tweemaal.
• De ECR wordt tijdens een betaling opnieuw opgestart en begint de volgende verkoop zonder de uitkomst van de onderbroken betaling te lezen.

Wat de betaalterminal wel en niet voor u doet

Twee componenten beantwoorden uw aanvragen: de HTTP-server van de terminal, die één uitwisseling per endpoint beheert (een POST opent deze, de laatste 200 op GET sluit deze), en de betaaltoepassing, die de transactie uitvoert. Ze kunnen zich in verschillende toestanden bevinden en de herstelprocedure controleert beide.

Regels die op de ECR moeten worden geïmplementeerd

1. Schrijf een transactiedagboek voordat u verzendt

Schrijf vóór elke POST van een betaling, kaartverwerving of terugdraaiing één item naar persistente opslag: ServiceID, SaleTransactionID (TransactionID en TimeStamp), endpoint, bedrag, valuta en status IN_FLIGHT. Sla bij de laatste 200 de POIData.POITransactionID en het resultaat op en sluit het item. Na een herstart is een item dat nog de status IN_FLIGHT heeft een betaling met onbekende uitkomst: los dit op voordat u iets anders op die kassa doet.

2. Gebruik voor elke aanvraag een nieuwe ServiceID

• Elke aanvraag krijgt een nieuwe ServiceID, inclusief /status, /diagnosis, /abort, /login en een nieuwe poging voor een betaling waarvan is bevestigd dat ze niet verwerkt is. Bewaar de teller; gebruik nooit een vaste waarde zoals "0".
• De SaleTransactionID identificeert de verkoop: uniek per winkelmandje, ongewijzigd bij pogingen voor hetzelfde winkelmandje en altijd samen met de bijbehorende TimeStamp verzonden.

3. Vergrendel de verkoop zolang de uitkomst onbekend is

Schakel de knop Kaartbetaling uit zodra erop wordt gedrukt. Zolang een item voor een winkelmandje de status IN_FLIGHT heeft: geen nieuwe betalingsaanvraag, geen andere betaalmethode (contant geld, voucher, tweede kaart) en geen nieuwe verkoop op die kassa. De vergrendeling eindigt altijd met een definitief resultaat, een gecontroleerde annulering of de onderstaande procedure voor onopgeloste gevallen.

4. Laat de HTTP-laag een POST nooit opnieuw proberen

Schakel automatische nieuwe pogingen uit in uw HTTP-client en in elke proxy tussen de ECR en de terminal. Een POST die op transportniveau mislukt, gaat naar de herstelprocedure en wordt niet opnieuw geprobeerd.

5. Blijf pollen tot 200, met timers die passen bij een echte betaling

POST /payment antwoordt met 202. Roep daarna GET /payment (zonder body) aan totdat dit met 200 antwoordt.

De terminal gebruikt zijn eigen time-out per endpoint, ingesteld in de configuratie van de HTTP-server: 180 s op /payment, hetzelfde op elke terminal. Dit is de tijd die de terminal wacht op het laatste antwoord van de betaaltoepassing; daarna antwoordt GET met 408 in plaats van het antwoord. Houd uw betalingsperiode daaronder. Wanneer de betalingsperiode verstrijkt, mag u het scherm niet vrijgeven en mag u de betaling niet opnieuw verzenden: ga naar de herstelprocedure.

6. Draai terug met de POITransactionID als er twee betaalmethoden zijn gebruikt

Als een kaartbetaling achteraf goedgekeurd blijkt nadat de klant al op een andere manier heeft betaald, verzendt u een ReversalRequest met de OriginalPOITransaction.POITransactionID uit het dagboek of uit /status. Draai nooit terug met de SaleTransactionID.

De herstelprocedure

Voer deze uit wanneer de ECR start met een item met status IN_FLIGHT, wanneer een poll mislukt of de betalingsperiode verstrijkt, wanneer een POST antwoordt met 403 of op transportniveau mislukt, en wanneer GET /payment antwoordt met 408 of 423 terwijl er nog een item met status IN_FLIGHT bestaat. Gebruik voor elke aanroep een nieuwe ServiceID. De drie stappen beantwoorden drie verschillende vragen: is er nog een uitwisseling open, is de betaaltoepassing nog bezig en wat was het laatste resultaat.

Stap 1: is er nog een HTTP-uitwisseling open?

GET /blocked geeft elk endpoint met een open uitwisseling weer als gewone JSON:

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

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

• /payment wordt vermeld: hervat GET /payment totdat dit met 200 antwoordt. Dat antwoord is de uitkomst, ongeacht hoe lang geleden de betaling is beëindigd. Roep nu geen /status aan: dit zou de vorige verkoop retourneren. Als de leeglopende GET antwoordt met 408 of 423, ga dan naar stap 2.
• De lijst is leeg: het laatste antwoord is al gelezen (een 200 of een 408), of de betaling is nooit gestart. Stap 2 vertelt u of de betaaltoepassing nog aan iets werkt.

Stap 2: is de betaaltoepassing nog bezig?

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

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

Stap 3: lees de laatst voltooide transactie

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"}}, ... } } } }

De geretourneerde transactie komt alleen overeen met uw dagboekitem als RepeatedMessageResponse.MessageHeader.ServiceID, SaleTransactionID.TransactionID en SaleTransactionID.TimeStamp gelijk zijn, MessageCategory Payment is en het bedrag het aangevraagde bedrag is (of lager, bij een gedeeltelijke goedkeuring).

Procedure voor onopgeloste gevallen

• Bewaar het item in persistente opslag met de status UNRESOLVED, plus kassa, bedrag en tijd, en waarschuw de winkelverantwoordelijke of backoffice. Een andere betaalmethode is alleen via deze expliciete procedure toegestaan, nooit stilzwijgend.
• Wanneer de terminal opnieuw bereikbaar en niet actief is, voert u stap 1 tot en met 3 automatisch uit voor elk item met de status UNRESOLVED. Als de kaartbetaling goedgekeurd blijkt en een andere betaalmethode werd gebruikt, draait u de kaartbetaling terug (regel 6).
• Als het resultaat niet langer van de terminal kan worden gelezen, stemt u af met het transactierapport van de handelaar voordat u de klant terugbetaalt.

Annuleren wanneer de klant afhaakt

Als de betaling na de betalingsperiode nog loopt (bijvoorbeeld omdat de klant is weggegaan bij de vraag om de pincode), kan de kassier annuleren: verstuur een AbortRequest waarvan MessageReference de ServiceID van de betaling bevat en blijf daarna GET /payment pollen. De laatste 200 met ErrorCondition: Aborted is de uitkomst. Gebruik na een kaartverwerving (betaling in twee stappen) de Admin-variant (AdminRequest met DualTransactionAborted) die in de Local API-specificatie wordt beschreven.

Wat de kassier of klant ziet