Booking API – Prenotare con Stripe

← Booking API

In questo flusso il cliente finale paga la prenotazione con carta (o con un altro metodo accettato da Stripe) sulla pagina di pagamento ospitata da Stripe per conto di BcOk.

Alla vostra applicazione non servono un account né chiavi Stripe. BcOk crea la sessione di pagamento, riceve la conferma da Stripe e conferma la prenotazione. L'app esterna deve:

  1. raccogliere i dati della prenotazione e di fatturazione;
  2. creare la prenotazione su BcOk;
  3. reindirizzare l'utente alla pagina di pagamento;
  4. quando l'utente torna, verificare l'esito e mostrarlo.

Il flusso in sintesi

Browser utente          App esterna (server)                   BcOk                        Stripe
     |                         |                                 |                            |
     |-- sceglie spazio ------>|                                 |                            |
     |                         |-- POST /prenota/{risorsa_id} -->|                            |
     |                         |                                 |-- crea Checkout Session -->|
     |                         |<-- in_attesa + checkout_url ----|                            |
     |<-- redirect a checkout_url                                |                            |
     |------------------------------- paga ------------------------------------------------->|
     |                         |                                 |<----- webhook: pagato -----|
     |                         |                                 |  prenotazione confermata   |
     |                         |                                 |  + email al cliente        |
     |<-- redirect a success_url?...&session_id=cs_... --------------------------------------|
     |-- GET success_url ----->|                                 |                            |
     |                         |-- POST /stripe-verify-payment ->|                            |
     |                         |<-------- confirmed -------------|                            |
     |<-- "Prenotazione confermata"                              |                            |

Passo 1 – Scelta di sede e spazio

  1. Sedi: GET /sedi e proponete solo quelle con booking_con_stripe: true (dettagli).
  2. Informazioni sede: GET /info_sede?sede_id=... per tipologie (tipi_risorse), orari (meta.orari_prenotabili) e preavviso (dettagli).
  3. Ricerca: GET /risorse/cerca senza codice_carnet (dettagli). Per ogni spazio mostrate il prezzo addebito_proposto.quanto: è il totale IVA inclusa che l'utente pagherà su Stripe (importo_netto + iva_importo). Escludete gli spazi con orario_preavviso_limite già passato.

Passo 2 – Raccolta dei dati

Oltre ai dati della prenotazione (spazio, giorno, orari, numero di persone) servono:

  • il referente: nome, cognome, email (obbligatori) e telefono. L'email riceverà la conferma;
  • i dati di fatturazione del cliente che paga, descritti qui sotto.

Dati di fatturazione

BcOk identifica il cliente da fatturare tramite la coppia cliente_partita_iva_country + cliente_partita_iva. Se il cliente esiste già in BcOk la prenotazione viene associata a lui; altrimenti BcOk crea il nuovo cliente con i dati inviati quando il pagamento è confermato.

Caso cliente_partita_iva_country cliente_partita_iva Altri campi
Azienda italiana IT P.IVA, 11 cifre, senza IT cliente_azienda_privato=azienda, cliente_ragione_sociale, cliente_sdi e/o cliente_pec
Azienda UE codice paese: AT, BE, BG, CY, CZ, DE, DK, EE, EL (Grecia), ES, FI, FR, HR, HU, IE, LT, LU, LV, MT, NL, PL, PT, RO, SE, SI, SK Numero di partita IVA senza prefisso paese cliente_azienda_privato=azienda, cliente_ragione_sociale
Regno Unito / San Marino GB / SM Numero di partita IVA senza prefisso come sopra
Privato italiano CF: (con i due punti) Codice fiscale (16 caratteri) cliente_azienda_privato=privato, cliente_codice_fiscale (lo stesso CF)
Cliente extra UE (azienda o privato) Non EU non necessario cliente_paese, ed eventualmente cliente_ragione_sociale

In tutti i casi inviate anche l'indirizzo: cliente_indirizzo, cliente_cap, cliente_citta, cliente_provincia, cliente_paese (nome del paese, es. "Italia").

BcOk controlla il formato della partita IVA o del codice fiscale per il paese indicato (non ne verifica l'esistenza). Se il formato è errato ricevete REST_check_VAT-NUM-ERROR o REST_check_VAT-CF-ERROR; se il codice paese non è tra quelli in tabella, REST_check_VAT-COUNTRY-ERROR. Conviene replicare lo stesso controllo nel vostro modulo, per segnalare l'errore prima dell'invio.

Passo 3 – Creazione della prenotazione

URL di ritorno

Preparate due pagine della vostra applicazione:

  • success_url: dove Stripe rimanda l'utente dopo il pagamento. Deve contenere già una query string, perché BcOk aggiunge in coda &session_id={CHECKOUT_SESSION_ID} (Stripe poi sostituisce il segnaposto con l'ID reale della sessione).
  • ✅ https://www.example.com/prenota/esito?stato=ok
  • ❌ https://www.example.com/prenota/esito → diventerebbe .../esito&session_id=..., un URL non valido
  • cancel_url: dove Stripe rimanda l'utente se annulla il pagamento, es. https://www.example.com/prenota/esito?stato=annullato.

Nel success_url potete aggiungere vostri parametri (es. un vostro ID di carrello) per ritrovare il contesto al ritorno.

Chiamata

curl -u "UTENTE:PASSWORD" -X POST "https://bcok.it/wp-json/booking/v2/prenota/1234" \
  -H "Content-Type: application/json" \
  -d '{
    "sede_id": 580,
    "prenotazione_inizio": "2026-11-20T09:00:00+01:00",
    "prenotazione_fine": "2026-11-20T13:00:00+01:00",
    "orario_opzione": "mezza_giornata_mattina",
    "n_persone": 4,
    "persona_nome": "Mario",
    "persona_cognome": "Rossi",
    "persona_email": "mario.rossi@example.com",
    "persona_telefono": "+39 333 0000000",
    "prenotazione_note": "Serve il proiettore",
    "cliente_azienda_privato": "azienda",
    "cliente_ragione_sociale": "Esempio S.r.l.",
    "cliente_partita_iva_country": "IT",
    "cliente_partita_iva": "01234567890",
    "cliente_sdi": "ABC1234",
    "cliente_indirizzo": "Via Esempio 1",
    "cliente_cap": "20100",
    "cliente_citta": "Milano",
    "cliente_provincia": "MI",
    "cliente_paese": "Italia",
    "success_url": "https://www.example.com/prenota/esito?stato=ok",
    "cancel_url": "https://www.example.com/prenota/esito?stato=annullato",
    "booking_source_domain": "www.example.com"
  }'

Risposta (dettagli in Endpoint):

{
  "addebito_eseguito": "80 Euro",
  "prenotazione": { "id": 9877, "status": "in_attesa", "...": "..." },
  "stripe": {
    "session_id": "cs_test_a1B2c3D4...",
    "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_a1B2c3D4...",
    "test_mode": true
  }
}

Salvate nella sessione dell'utente (o nel vostro database) almeno prenotazione.id, stripe.session_id e stripe.checkout_url.

Da questo momento la prenotazione è in attesa di pagamento (in_attesa) e lo spazio è bloccato: nessun altro può prenotarlo.

Passo 4 – Reindirizzamento al pagamento

Reindirizzate il browser dell'utente a stripe.checkout_url (HTTP 303 o window.location). La pagina è di Stripe: l'utente vede il nome dello spazio, la descrizione con il dettaglio IVA e il totale, e paga.

La sessione di pagamento scade dopo 30 minuti. Se l'utente non paga entro la scadenza, la prenotazione viene annullata automaticamente e lo spazio torna libero.

Passo 5 – Ritorno dell'utente e verifica dell'esito

Ritorno sul success_url

Stripe rimanda l'utente a success_url con il parametro session_id, es. https://www.example.com/prenota/esito?stato=ok&session_id=cs_test_a1B2c3D4....

Il ritorno sul success_url non garantisce che la prenotazione sia confermata: la conferma arriva a BcOk da Stripe in modo indipendente, di solito entro pochi secondi. Verificate sempre lo stato con /stripe-verify-payment, dal vostro server.

Leggete session_id dalla query string (o usate quello salvato al passo 3) e interrogate BcOk:

curl -u "UTENTE:PASSWORD" -X POST "https://bcok.it/wp-json/booking/v2/stripe-verify-payment" \
  -H "Content-Type: application/json" \
  -d '{"session_id":"cs_test_a1B2c3D4..."}'

Comportamento consigliato (è quello del plugin WordPress ufficiale):

Risposta Significato Cosa fare
200, prenotazione.status = confirmed Pagamento ricevuto, prenotazione confermata Mostrate la conferma: codice prenotazione.id, orari inizio/fine, email a cui è stata inviata la conferma
200, prenotazione.status = pending Conferma non ancora arrivata Mostrate "Stiamo verificando il pagamento..." e riprovate ogni 3 secondi, fino a circa 30 secondi
404 Stripe_Prenotazione_Non_Trovata Pagamento fallito o sessione scaduta: la prenotazione è stata annullata Mostrate che il pagamento non è andato a buon fine e proponete una nuova ricerca
Ancora pending dopo 30 secondi Conferma in ritardo (succede con alcuni metodi di pagamento non istantanei) Mostrate "Pagamento in elaborazione: riceverai un'email di conferma". Non dite che la prenotazione è fallita

Il polling va fatto dal vostro server (eventualmente esposto al vostro frontend tramite un vostro endpoint), perché richiede le credenziali API.

Quando la prenotazione è confermata, BcOk invia l'email di conferma a persona_email.

Ritorno sul cancel_url

L'utente ha annullato il pagamento (pulsante "indietro" sulla pagina Stripe). La prenotazione resta in_attesa e lo spazio resta bloccato fino alla scadenza della sessione (30 minuti dalla creazione).

Proponete all'utente:

  • "Riprova il pagamento": reindirizzatelo di nuovo allo stesso checkout_url salvato al passo 3, che resta valido fino alla scadenza della sessione. Non chiamate di nuovo POST /prenota per lo stesso spazio e orario: la nuova richiesta verrebbe rifiutata con Prenotazione_Risorsa_prenotata, perché lo spazio è occupato dalla prenotazione in attesa;
  • "Annulla": non serve fare nulla, la prenotazione verrà annullata automaticamente alla scadenza della sessione.

Cosa succede dietro le quinte

Non serve implementarlo, ma aiuta a interpretare i casi limite:

Evento Stato della prenotazione
POST /prenota riuscito in_attesa: lo spazio è bloccato, nessuna email
Pagamento riuscito (notifica Stripe a BcOk) Confermata (confirmed in /stripe-verify-payment), email di conferma al cliente
Carta rifiutata Nessun cambiamento: l'utente resta sulla pagina Stripe e può riprovare con un'altra carta
Pagamento fallito dopo il checkout (metodi non istantanei) Annullata (404 in /stripe-verify-payment), spazio libero
Sessione scaduta senza pagamento (30 minuti) Annullata, spazio libero
Notifica Stripe persa Un controllo automatico ogni 15 minuti riallinea lo stato con Stripe

Ambiente di test

In ambiente di test (test_mode: true) usate le carte di test di Stripe, ad esempio:

Carta Risultato
4242 4242 4242 4242 Pagamento riuscito
4000 0000 0000 9995 Pagamento rifiutato (fondi insufficienti)

Data di scadenza futura qualsiasi, CVC qualsiasi.

Checklist per l'integrazione

  • [ ] Le chiamate a BcOk partono solo dal server, mai dal browser
  • [ ] Vengono proposte solo le sedi con booking_con_stripe: true
  • [ ] Il prezzo mostrato è addebito_proposto.quanto (IVA inclusa)
  • [ ] Gli spazi con preavviso scaduto non vengono proposti
  • [ ] success_url contiene già una query string (?)
  • [ ] prenotazione.id, stripe.session_id e stripe.checkout_url vengono salvati
  • [ ] Al ritorno lo stato viene verificato con /stripe-verify-payment, con polling sullo stato pending
  • [ ] "Riprova il pagamento" riusa il checkout_url e non crea una nuova prenotazione
  • [ ] All'utente vengono mostrati gli orari effettivi (prenotazione_inizio_effettiva / prenotazione_fine_effettiva)
  • [ ] Gli errori vengono gestiti in base al campo code (vedi Errori)