Booking details & vouchers

POST /v1/transfer/booking-details returns one normalised view of a booking, the same shape for every provider. Use it to:

• render the customer's voucher and confirmation e-mail;
• refresh the status (a provider may confirm, change or cancel a booking after book);
• get driver details closer to pickup, when the provider supplies them;
• read the cancellation outcome after a cancel.

POST /v1/transfer/voucher is a deprecated alias with the same request and response.

Request

Request

{
  "provider_context": {"provider": "provider_a"},
  "supplier_reference": {
    "booking_id": "01aa00bb11cc22dd33ee44ff55667781",
    "confirmation_number": "PRV0000001",
    "provider": "provider_a",
    "booking_status": "completed",
    "booking_token": "bt1.gAAAAAB..."
  }
}

Optional field	Effect
book_response	The full book response you stored. The details are built from it without calling the provider: fast, but later changes are not visible.
cancel_response	The full cancel response. Fills cancelled_at and the refund when the provider's lookup does not report them. Optional if you cancelled through this API with the same key.

Response structure

status is the outcome of the lookup (ok or failed), not the booking status. The booking status is booking_details.booking.status. Every key is always present; a value the provider does not supply is null (or []). details_version is "3".

Section	Contents
booking	tp_booking_ref (your internal_reference), provider, supplier_booking_id, supplier_confirmation_number, status, status_source, booked_at
trip	transfer_type, direction, pickup and dropoff locations, pickup_datetime (local, with offset when known), timezone, flight, return_datetime, hours
passengers	lead (name, email, phone), adults, children, infants, total
vehicle	category, model (always "or similar"), max_passengers, max_bags, count, image_url
service	meeting_point, pickup_instructions, meet_and_greet, free_waiting_minutes, package, extra_charges, driver, supplier_contact
price	total, currency (the search currency), paid
cancellation	free_cancellation_until, policy_text, rules, cancelled, cancelled_at, refund_amount, refund_currency, refund_source
supplier_voucher_url	The provider's own voucher page, when offered

Every field is documented in the booking details reference.

Booking status

booking.status	Meaning	Issue a voucher?
confirmed	The provider confirmed the transfer	Yes
pending	Not confirmed yet	As "awaiting confirmation"; check again later
cancellation_pending	A cancellation is being processed	No
cancelled	Cancelled	No (show as cancelled)
failed	The booking did not go through	No
unknown	The provider's status could not be mapped	Contact support with the booking reference

What providers supply

The structure is identical for every provider, but how much is filled in differs:

Data	Typical coverage
Live status	Yes (status_source: supplier)
pickup_datetime with UTC offset	Usually
Pickup and drop-off addresses	Usually; otherwise taken from what you booked (trip.locations_source)
Meeting point and instructions	Usually
Driver details	Only once a driver is assigned, typically close to pickup
supplier_voucher_url	Some providers only

Always handle null for any field.

Building the voucher

Section	Fields
References	booking.supplier_confirmation_number (the reference the driver knows) and your own reference
When	trip.pickup_datetime in the pickup's local time; trip.flight for airport transfers
Where	trip.pickup and trip.dropoff: name, address, terminal
Who	passengers.lead.name, passengers.total
Vehicle	vehicle.category, vehicle.model + "or similar", seats and bags
Meeting the driver	service.meeting_point, service.meet_and_greet, service.free_waiting_minutes, service.pickup_instructions (print as is)
Driver	service.driver.*, when present
Help on the day	service.supplier_contact, plus your own support number
Hourly hire	trip.hours, service.package, service.extra_charges
Cancellation	cancellation.free_cancellation_until, cancellation.policy_text

Refresh booking details after book, again 24 to 48 hours before pickup (driver details, last changes) and after a cancel. Re-issue the voucher when something changed.