# Collegare i pagamenti Revolut (sandbox e carte di prova incluse)

Gli ospiti pagano la tassa di soggiorno, il deposito cauzionale e gli extra tramite il **tuo conto merchant Revolut Business**. Il denaro arriva direttamente a te; noi non lo deteniamo mai. Ti serve un conto Revolut Business con il prodotto **Merchant** (accettazione delle carte) attivo.

Ti consigliamo vivamente di collegare prima la **sandbox**. La sandbox è una copia di prova separata di Revolut Business: non si muove denaro reale e puoi provare ogni esito con le carte di prova.

## 1. Crea un account sandbox Revolut

1. Vai su `https://sandbox-business.revolut.com/signup` e registrati.
2. Se non sai quale forma giuridica scegliere, seleziona **Public Limited Company** (gli account da libero professionista non sono supportati nella sandbox).
3. Quando ti viene chiesto di verificare l'email, clicca su **Skip email verification**. Per il codice di conferma clicca su **Autofill code**. Nella sandbox le approvazioni sono automatiche.

> **Importante:** le chiavi sandbox funzionano solo in modalità sandbox e le chiavi live solo in modalità live. Non puoi mischiarle.

## 2. Copia le chiavi API della sandbox

1. Accedi su `https://sandbox-business.revolut.com/signin`.
2. Apri **Merchant**, clicca sul menu **⋯** e scegli **Merchant API** (link diretto: `https://sandbox-business.revolut.com/settings/apis?tab=merchant-api`).
3. Clicca su **Generate** accanto a **Secret key** se non ne esiste ancora una, poi copiala (inizia con `sk_`).
4. Copia anche la **Public key** (inizia con `pk_`). Serve per i pulsanti Apple Pay e Google Pay.

## 3. Inserisci le chiavi nella tua dashboard

1. Apri **Settings → Payments**.
2. Incolla la **Secret API key** e la **Public API key**.
3. Spunta **Sandbox mode (test payments with Revolut test cards)**.
4. Clicca su **Save**, poi su **Test connection**. Dovresti vedere *Connected to Revolut (sandbox)*.
5. Clicca su **Register webhook**. Da questo momento Revolut comunica subito al tuo portale quando un pagamento va a buon fine, non riesce o quando una preautorizzazione del deposito viene incassata o sbloccata. Lo stato passa a *Registered*.

La chiave segreta viene salvata cifrata. Quando torni in seguito viene mostrata mascherata: lasciala così per mantenere la chiave salvata.

![Settings → Payments](/site/img/docs/d-settings-payments.webp "Settings → Payments")

## 4. Prova con le carte di prova Revolut

Crea una prenotazione di prova con il tuo indirizzo email, apri il link ospite e paga. Nella sandbox usa una qualsiasi **data di scadenza futura** e **un CVV qualsiasi di 3 cifre**.

| Numero di carta | Circuito | Risultato |
|---|---|---|
| `4929 4205 7359 5709` | Visa | Pagamento riuscito |
| `5281 4388 0180 4148` | Mastercard | Pagamento riuscito |
| `4929 5736 3812 5985` | — | Rifiutato: fondi insufficienti |
| `4532 3367 4387 4205` | — | Rifiutato: carta scaduta |
| `2720 9988 3777 9594` | — | Rifiutato: do not honour (emittente) |
| `4242 4242 4242 4242` | — | La verifica 3-D Secure non riesce (solo per importi da €30.00 in su) |
| `5215 6741 1512 7070` | — | Non riuscito: l'emittente richiede una verifica aggiuntiva |
| `2223 0000 1047 9399` | — | Resta in elaborazione (autorizzazione avviata) |

Gli importi inferiori a €30.00 (o £25.00) sono esenti da 3-D Secure nella sandbox e vanno a buon fine senza verifica. Per vedere un errore 3-D Secure, usa una prenotazione di prova con un deposito di almeno €30.

Controlla nella dashboard che:

- la tassa di soggiorno risulti **Paid** e il deposito **Held** (preautorizzazione) o **Paid** (modalità addebito),
- il portale ospiti si sblocchi una volta completati tutti i passaggi,
- arrivi un'email con la ricevuta,
- **Release deposit** nella prenotazione rimborsi l'addebito o sblocchi la preautorizzazione.

### Test da Settings → Payments

Non ti serve una prenotazione per provare l'intera catena. In **Settings → Payments → Test payments** inserisci un importo (1–50) e premi:

- **Test charge & refund** — paga l'ordine di prova nella nuova scheda, poi premi **Refund**. È così che funzionano tasse, extra e depositi in modalità *charge & refund* (addebito e rimborso).
- **Test deposit hold & release** — paga l'ordine di prova (l'importo viene solo bloccato sulla carta), poi premi **Release hold**, oppure **Keep half, release rest** e successivamente **Refund the kept part**. È la modalità di deposito *hold* (preautorizzazione).

Ogni test elenca la risposta di Revolut a ogni passaggio e spunta **Webhook received** quando la notifica firmata di Revolut ha raggiunto Guestbud: è questo che conferma da solo i pagamenti degli ospiti. Se il webhook non arriva mai, premi **Register webhook**. In modalità live il test usa una carta reale e viene rimborsato subito; Revolut potrebbe trattenere la sua commissione.

## 5. Passa alla modalità live

1. Nel tuo conto Revolut Business live (`https://business.revolut.com`) apri **Merchant → ⋯ → Merchant API** e copia le chiavi live segreta e pubblica.
2. In **Settings → Payments** incollale, togli la spunta a **Sandbox mode**, clicca su **Save** e su **Test connection** (*live*).
3. Clicca di nuovo su **Register webhook**: il conto live ha bisogno di un proprio webhook.
4. Fai un piccolo pagamento reale con la tua carta e rimborsalo in Revolut.

## Metodi di pagamento

In **Payment methods** scegli cosa proporre agli ospiti:

- **Card payment** — checkout ospitato da Revolut (tutte le principali carte, 3-D Secure).
- **Apple Pay** e **Google Pay** — vedi [Apple Pay e Google Pay](/docs/apple-pay-google-pay).
- **Manual payment** — disattivato per impostazione predefinita. Attivalo per permettere agli ospiti di scegliere contanti o bonifico; lo confermi con **Mark as paid** nella prenotazione. Aggiungi istruzioni come il tuo IBAN.

![Cosa vede l'ospite al momento del pagamento](/site/img/docs/m-payment-sheet.webp "Cosa vede l'ospite al momento del pagamento")

## Depositi: preautorizzazione o addebito

Un deposito può essere una **preautorizzazione sulla carta** (il denaro viene bloccato ma non prelevato; viene sbloccato dopo il check-out) oppure un **addebito** che rimborsi in seguito. Per impostazione predefinita le preautorizzazioni scadono dopo 7 giorni; spunta **Deposits as card pre-authorisation for up to 30 days** se il tuo conto Revolut dispone delle autorizzazioni estese. Dettagli: [Depositi ed esenzioni](/docs/deposits-and-waivers).

## Risoluzione dei problemi

### Test connection dice che Revolut ha rifiutato la chiave (401)?

Probabilmente hai incollato una chiave live in modalità sandbox o viceversa, oppure hai copiato la chiave pubblica nel campo della chiave segreta. La chiave segreta inizia con `sk_`.

### L'ospite ha pagato ma la prenotazione indica ancora in attesa della banca?

Il webhook manca o punta a un indirizzo vecchio. Clicca di nuovo su **Register webhook**. Il portale ricontrolla inoltre i pagamenti aperti ogni volta che l'ospite apre la pagina.

### Posso usare un solo conto Revolut per più aziende?

Ogni tenant collega il proprio conto merchant. Se gestisci strutture di più proprietari sotto un'unica azienda, va bene un solo conto.

### Il portale ospiti memorizza i dati delle carte?

No. I dati delle carte vengono inseriti nelle pagine di Revolut o nel modulo di pagamento di Revolut e non raggiungono mai i nostri server.

## Modalità del deposito, tempi di sblocco e sicurezza della sandbox

![Modalità del deposito, tempi di sblocco ed email di prova della sandbox](/site/img/docs/d-payments-deposit.webp "Modalità del deposito, tempi di sblocco ed email di prova della sandbox")

In **Settings → Payments → Revolut Merchant**:

- **Deposit mode** — *Charge & refund* (predefinita): il deposito viene addebitato in anticipo e rimborsato dopo il check-out, in tutto o in parte, adatto a soggiorni di qualsiasi durata. *Hold (pre-authorisation)*: l'importo viene solo bloccato sulla carta e sbloccato automaticamente, ma una preautorizzazione dura al massimo 7 giorni (30 con preautorizzazione estesa), quindi è adatta solo ai soggiorni brevi. Ogni struttura segue questa impostazione predefinita, a meno che il suo **Guide editor → Payments → How it is taken** non indichi diversamente; spunta **Use this deposit mode for all properties** per riportarle tutte all'impostazione predefinita.
- **Release the hold this many days after check-out** (predefinito 2) — il tempo a tua disposizione per ispezionare la struttura e trattenere denaro per eventuali danni prima che Revolut sblocchi da solo la preautorizzazione. 0 = sblocco al check-out.
- **Sandbox test email** — finché la **Sandbox mode** è attiva, gli ospiti reali non vengono mai contattati: le email agli ospiti vanno a questo indirizzo (vuoto = l'email dell'host) e i messaggi tramite il canale di prenotazione vengono trattenuti. Disattiva la sandbox solo quando sei pronto ad accettare pagamenti reali con una chiave live.