# DPass 61I6 — verifica Fabrick tramite paymentToken

## Perché
La prova dell'utente ha ricevuto HTTP 200, error.code=0 e transactionResult=APPROVED
usando il paymentToken corretto. La verifica DPass con API key restituiva invece
«Funzione non disponibile». La prova non ha scritto nel database e NON ha
certificato l'importo, che non era esposto nell'output diagnostico.

## Modifiche
- Il callback S2S/ritorno passa il paymentToken ricevuto alla lettura payment/detail.
  In questa richiesta viene inviato solo l'header paymentToken, non l'API key.
- Senza token resta la modalità API key. Per il solo codice 1170 (token non valido)
  si effettua al massimo un tentativo alternativo con la API key. Nessun ciclo di retry.
- payment/create resta con API key. Non sostituire l'API key configurata col token.
- Il paymentID deve coincidere con quello già registrato in DPass PRIMA della lettura.
- Prima dell'accredito: esito API, paymentID, ordine, valuta, risultato remoto e importo
  devono essere coerenti. Il solo Status=OK ricevuto non basta.
- payment/detail può esporre l'importo in events[].event.eventamount: si verifica
  il movimento MOV (o AUT per un'autorizzazione), senza sommare AUT e MOV.
  Catture multiple/ambigue e movimenti con rimborsi/annullamenti richiedono verifica
  amministrativa. Importo mancante o discordante => nessun accredito.
- Non si effettuano nuove catture, nuovi ordini o rimborsi sul gateway.
- Idempotenza e transazione locale con lock esistenti restano presenti. Verifica ripetuta
  anche sul record bloccato, per impedire accrediti usando dati locali diventati obsoleti.
- Un pagamento già paid e con movimento wallet associato non viene riletto/accreditato.
- Il flusso Fabrick qui corretto riguarda le ricariche wallet. Non abilita pagamenti
  Fabrick delle strutture, degli ospiti o degli abbonamenti. Finalità diverse sono bloccate.
- Token non persistito; errori del dettaglio riportano solo operazione, HTTP e codice API.

## Applicazione LOCALE
Salvare lo ZIP in C:\Users\massi\Downloads e utilizzare Ubuntu/WSL:

```bash
(
  set -e
  cd ~/progetti/dpass
  PATCH_DIR="$(mktemp -d /tmp/dpass_patch_61I6.XXXXXX)"
  unzip -q /mnt/c/Users/massi/Downloads/dpass_patch_61I6_fabrick_verifica_paymenttoken.zip -d "$PATCH_DIR"
  bash "$PATCH_DIR/apply_patch.sh" "$PWD"
)
```

Il controllo usa hash esatti dei file Fabrick ricevuti e dipendenze, non richiede di
installare moduli guest/API o importazione parcometri non correlati.
Il pacchetto include 3 file applicativi, 2 file test e questa nota di continuità.
Nessuna migration, SQL di aggiornamento, modifica .env o cron. Nessun Composer/NPM.
L'installer NON carica Laravel tramite artisan, NON legge il database applicativo,
NON chiama Fabrick. Legge APP_ENV soltanto per rifiutare un'installazione diretta
con .env di produzione; i test istanziano un'applicazione isolata senza bootstrap.
Preflight, backup, applicazione atomica per file, controlli e rollback automatico in caso
di test falliti. Se il preflight trova una modifica sconosciuta, fermarsi e non forzare.
Modalità facoltative: `apply_patch.sh /progetto --check`, oppure
`apply_patch.sh /progetto --rollback /percorso/backup` prima di modifiche successive.

## Produzione e recupero del test
Leggere PRODUZIONE_CPANEL.md. Non basta l'installazione locale per aggiornare il
pagamento Pisamo: occorre pubblicare i tre file e poi ricevere/ritentare la notifica.
Lo script ripeti_notifica_fabrick.py è separato dall'installer e NON È SOLA LETTURA:
può far completare dal server DPass la transazione esistente e l'accredito wallet.
Richiede conferma esplicita, non va eseguito finché la produzione non è aggiornata.
I riferimenti iniziali sono quelli del pagamento segnalato; non contiene token/segreti.

## Limiti
Non è stata effettuata alcuna chiamata reale al gateway/server Pisamo durante la
preparazione. Rimane da collaudare il percorso HTTP completo in PHP8.3/MySQL.
Il riepilogo diagnostico da solo non certifica importo o stato locale: questi controlli
avvengono nel servizio DPass. Eventuali dati mancanti/ambigui resteranno bloccati.
Il callback conserva l'architettura sincrona attuale e i timeout configurati: questa patch
non implementa una coda webhook né promette un tempo di risposta inferiore a 10 secondi.
Un timeout di rete va controllato nel gestionale prima di ripetere qualunque azione.
Rimborsi/catture parziali e recuperi fuori dai limiti del token non sono automatizzati.

## Riferimenti ufficiali consultati il 24/09/2026
- https://docs.fabrick.com/docs/en/paymentHubAndOrchestra/ecommerce/integrationMethods/pay_by_link/
- https://api.paymentorchestra.fabrick.com/ — payment/detail, paymentToken, Event Types.
- https://docs.paymentorchestra.fabrick.com/en/payments/management/payments-monitoring/check-payments-status/
Il paymentToken è documentato per payment/detail nelle 24h dall'autorizzazione,
con massimo 10 letture in produzione (5 sandbox). Evitare diagnostiche ripetute.