get_booking_status
Check the current status of a booking.
If the booking is not yet marked paid, this call may poll the operator's
payment processor and finalize and record a payment that has already
settled. It never initiates a payment or cancellation.
Returns the raw persisted `status` value (`pending`, `awaiting_payment`,
`paid`, `cancelled`, `expired`), `payment_status`, and a convenience
`paid` boolean. Legacy compatibility rows may still report
`awaiting_payment`; present that to end users as traveler payment pending
rather than as a new canonical state name.
Polling cadence after presenting a payment link:
1. **First poll** — call with ``wait_seconds=60``. The server returns
sub-second once payment lands, or after 60s if still pending.
2. **Active-wait loop** — if still ``paid: false``, loop with another
``wait_seconds=60`` call. Realistic payment latency is p95 ~3 min,
p99 ~8 min; **cap the loop at ~10 iterations (10 min)** of active
waiting.
3. **Pivot at 10 min** — tell the tourist "I'll let you know the
moment payment confirms, feel free to ask me anything else in the
meantime" and stop the active-wait loop. The payment window remains
open for 30 minutes from link creation.
4. **On resumption** — if the tourist replies later, do a single
non-blocking peek (``wait_seconds=0``) before continuing. That
surfaces a payment that landed while you weren't watching.
5. **Absolute ceiling** — at 30 minutes the payment window closes. A
later status check reports expiry and tells the guest to book again.
Do not require the user to say "I paid" — check proactively. Requires
OAuth2 authentication.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"booking_reference": "<booking_reference>"
},
"name": "get_booking_status"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| wait_seconds | No | How long the server should long-poll for the booking to reach a terminal state (``paid``, ``cancelled``, ``expired``) before returning. Returns immediately if the booking is already terminal. Default 0 — single-shot read, model picks its own cadence. Set ``wait_seconds=60`` after presenting a payment link so the tool returns the moment the tourist completes payment, instead of forcing a sleep + re-call. Cap 90 to stay safely under the ~300s client timeout. | |
| booking_reference | Yes | Booking reference code returned by create_booking. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||