Booking API – Prenotare con Stripe¶
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:
- raccogliere i dati della prenotazione e di fatturazione;
- creare la prenotazione su BcOk;
- reindirizzare l'utente alla pagina di pagamento;
- 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¶
- Sedi:
GET /sedie proponete solo quelle conbooking_con_stripe: true(dettagli). - Informazioni sede:
GET /info_sede?sede_id=...per tipologie (tipi_risorse), orari (meta.orari_prenotabili) e preavviso (dettagli). - Ricerca:
GET /risorse/cercasenzacodice_carnet(dettagli). Per ogni spazio mostrate il prezzoaddebito_proposto.quanto: è il totale IVA inclusa che l'utente pagherà su Stripe (importo_netto+iva_importo). Escludete gli spazi conorario_preavviso_limitegià 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": "[email protected]",
"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_urlnon 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_urlsalvato al passo 3, che resta valido fino alla scadenza della sessione. Non chiamate di nuovoPOST /prenotaper lo stesso spazio e orario: la nuova richiesta verrebbe rifiutata conPrenotazione_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_urlcontiene già una query string (?) - [ ]
prenotazione.id,stripe.session_idestripe.checkout_urlvengono salvati - [ ] Al ritorno lo stato viene verificato con
/stripe-verify-payment, con polling sullo statopending - [ ] "Riprova il pagamento" riusa il
checkout_urle 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)