WWooshPayment docs
Pagamenti

Refund flow (rimborsi)

Come gestire rimborsi su WooshPayment. Procedura step-by-step con sync automatica su Whop e Shopify/Woo.

2 min di lettura

TLDR: i refund partono SEMPRE dalla dashboard WooshPayment (mai direttamente dal pannello Whop). Oggi è disponibile il rimborso totale; rimborso parziale, dispute UI e reportistica avanzata sono in roadmap.

Regola d'oro

Non rimborsare mai direttamente da Whop dashboard. Se lo fai:

  • WooshPayment continua a vedere l'ordine come COMPLETED
  • Shopify/Woo non sa del refund → magazzino non si aggiorna
  • Pixel marketing inviano un evento Refund mancante → metriche sballate

Passa SEMPRE da: WooshPayment Dashboard → Ordini → seleziona ordine → "Rimborsa".

Rimborso totale (disponibile oggi)

  1. Dashboard → Ordini → cerca per email, ordine #, importo
  2. Apri detail dell'ordine
  3. Click sul bottone "Rimborsa" in alto
  4. Conferma il prompt (l'azione non è reversibile)

Cosa succede dietro le quinte:

  1. POST /api/checkout/merchant/orders/{token}/refund parte dal client autenticato
  2. Backend chiama Whop refundPayment (importo totale)
  3. Se Whop ritorna 200 → marca la session REFUNDED in DB
  4. Fire-and-forget: cancella l'ordine su Shopify se presente, con reason: customer, senza ulteriore refund (Whop ha già rimborsato)

I fondi tornano sulla carta del cliente in 3-5 giorni lavorativi gestiti da Whop. WooshPayment non manda un'email automatica al cliente: chi notifica è il tuo store backend (Shopify/Woo) dopo che lo stato passa a refunded.

Rimborso parziale

Roadmap Q3. L'UI per refund parziali (es. €29,99 su un ordine da €89,97 con scelta delle line items) non è ancora esposta. Il backend supporta importo parziale ma non c'è ancora il form. Se ti serve un parziale ora, fai un refund totale e ri-fattura il dovuto separato, oppure scrivici.

Chargeback

Quando il cliente apre dispute con la sua banca, Whop manda webhook a https://api.wooshpayment.com/webhooks/whop/payment-update. Oggi WooshPayment registra l'evento ma la gestione UI della disputa (upload evidenze, narrative, esito) è gestita lato Whop dashboard: non abbiamo ancora una sezione "Dispute" nella nostra dashboard.

Procedura attuale:

  1. Quando ricevi notifica disputa via mail Whop, vai sul tuo Whop dashboard → Disputes
  2. Carica evidenze: tracking, conferma consegna, screenshot chat
  3. Scrivi narrative
  4. Invia entro 7 giorni

WooshPayment registra dispute.created, dispute.won, dispute.lost ma non espone ancora la timeline nella tua dashboard.

Roadmap.

Gestione COD

Il Contrassegno non passa da Whop, quindi non c'è transazione da rimborsare:

  1. Rimborsa fisicamente il cliente (contanti, bonifico SEPA dal tuo conto, ecc.)
  2. Marca l'ordine come rimborsato lato Shopify/Woo
  3. Lato WooshPayment, oggi non c'è uno status "manual refund" specifico per COD: l'ordine resta in PENDING_PAYMENT o COMPLETED a seconda di come l'avevi marcato

Edge case

  • Refund > 60 giorni dall'ordine: Whop può rifiutarlo se troppo vecchio. In quel caso devi rimborsare il cliente con un metodo manuale fuori da Whop.
  • Cliente ha cancellato la carta: il refund Whop fallisce. Soluzione: bonifico SEPA dal tuo conto manuale e logga la cosa nei tuoi sistemi.
  • Whop fallisce ma Shopify era già cancellato: non succede perché ordine Whop è source of truth e Shopify viene tentato solo dopo che il DB ha già marcato REFUNDED.