## id
doc_tpv_virtual_cobrament

## nom
Cobrament amb TPV Virtual — mecanisme detallat

## descripcio
Consulta aquest document quan calgui explicar amb precisió el procés intern d'un cobrament per TPV
Virtual (per què és asíncron, què passa si la notificació del banc no arriba, com funciona
"Retornar"), o per què aquest tipus de cobrament té regles d'eliminació diferents dels manuals. No
és l'explicació general, que cobreix `flux_tpv_virtual_cobrament`.

## contingut
### El procés, pas a pas

1. L'usuari prem el botó de cobrament amb TPV Virtual des de la factura. S'obre una finestra nova
   (buida, per evitar bloquejadors d'emergents) que de seguida es redirigeix a la pàgina de
   pagament del proveïdor configurat (Redsys o Global Payments).
2. En aquest moment, FiskAppCloud **no** crea cap cobrament — només registra una operació de TPV en
   curs, amb una caducitat de **10 minuts**; passat aquest temps sense resposta, la reserva
   s'allibera sola. Mentre la reserva és vigent, evita que es puguin iniciar dos cobraments alhora
   per a la mateixa factura.
3. El client introdueix les dades de la targeta a la pàgina del proveïdor (fora de FiskAppCloud).
4. El proveïdor envia el resultat pels canals previstos per la seva integració:
   - Un redirect del navegador cap a una pàgina d'èxit o error de FiskAppCloud — **purament
     informativa**, només mostra un missatge i avisa la finestra original perquè mostri un avís.
     No crea ni modifica cap dada.
   - Una notificació independent, de servidor a servidor, que és l'única font de veritat sobre si
     el pagament ha anat bé de debò.
5. Aquesta notificació es processa en segon pla (una cua/worker, no en el mateix instant que arriba
   la petició) i és **aquí** on es crea el cobrament real, només si Redsys confirma l'autorització.

**Conseqüència pràctica**: el missatge d'èxit que veu l'usuari a la pantalla i el cobrament
apareixent a la factura no són el mateix esdeveniment — normalment van quasi seguits, però no cal
alarmar-se si el cobrament triga uns segons a aparèixer després de tancar la finestra de pagament.

### Per què no es pot eliminar

Un cobrament creat per aquesta via representa diners que un processador de pagaments extern ja ha
carregat de debò a la targeta del client. Esborrar només el registre de FiskAppCloud no "desfaria"
el càrrec real — deixaria l'aplicació desincronitzada del que ha passat de veritat al banc. Per
això aquests cobraments queden exclosos de l'eliminació normal (vegeu `doc_registrar_cobrament_factura`).

### "Retornar" (devolució)

Contra el que podria semblar per algun comentari intern del codi, la devolució **sí està
implementada i funciona**:

- Es pot fer una devolució total o parcial (es pot repetir fins a esgotar l'import disponible).
- Genera una crida real a Redsys per desfer el càrrec.
- Un cop confirmada, es crea un **cobrament nou, negatiu i independent** — l'original mai
  s'esborra ni es modifica.
- Si Redsys no respon a temps, l'operació queda marcada com a "incerta" en lloc de donar-la per
  fallida — evita que l'aplicació assumeixi que la devolució no ha funcionat quan en realitat
  només s'ha alentit la resposta.

## comprovacions
Si un usuari diu que ha pagat però la factura encara no mostra el cobrament: recorda que la
confirmació és asíncrona — pot trigar uns segons. Si passa massa temps, cal revisar si la
notificació de Redsys ha arribat.

Si un usuari pregunta per què no pot eliminar un cobrament fet amb targeta: explica que els
cobraments confirmats per una via externa mai es poden eliminar — l'acció correcta és "Retornar".

Si un usuari fa una devolució i no veu el resultat immediatament: comprova si l'operació ha quedat
en estat "incert" per manca de resposta de Redsys, no assumeixis que ha fallat.

Si un usuari diu que ha intentat pagar dos cops seguits i el segon no li deixava: mentre hi ha una
reserva de pagament vigent (fins a 10 minuts) per a la mateixa factura, no es pot iniciar-ne una
altra — cal esperar que expiri o que es resolgui la primera.

Si a un client no li apareix un mitjà de pagament que hauria d'estar disponible: comprova que
l'activitat té un TPV assignat per a aquell mitjà concret (targeta o Bizum) i que la capacitat
corresponent (puntual/recurrent) està activa al TPV — vegeu `doc_alta_tpv`.