The Transfer API allows agencies to search, book, pay for, and manage private transfer services (airport pickups, point-to-point rides) through the same Yolcu360 Agency API used for car rentals. Authentication, error format, and conventions are shared with the rest of the API.
A complete transfer booking consists of the following steps:
- Search — Send pickup/dropoff coordinates, time, and passenger count to get available vehicles with pricing.
- Offer Detail (optional) — Retrieve a single offer again by
searchIdandcode. - Create Order — Submit passengers and billing to create a reservation in
pendingPaymentstatus. - Pay — Pay the exact
paymentRequirementreturned at creation with your credit limit. - Track — The payment response already returns the order as
reservedwith itsvendorReservationId; retrieve the order detail to re-check the order before pickup. - Cancel (when needed) — Check eligibility and refund amount first, then cancel.
See the dedicated pages for each step:
- Transfer Search — search and offer detail endpoints
- Transfer Orders — order creation, detail, and cancellation
- Transfer Payment — two-step payment
| Identifier | Example | Description |
|---|---|---|
orderId | YLPB_0503 | The transfer order identifier, returned at order creation. Use it in every transfer endpoint. |
vendorReservationId | 227699 | The supplier's booking reference, assigned when the reservation completes. Use it when matching the booking with the supplier or driver. |
vendorReservationId is absent while the order is in pendingPayment status; it appears in the payment response and the order detail after a successful payment and reservation and stays on the order afterwards, including after cancellation.
| Status | Description |
|---|---|
pendingPayment | The order is created but not paid yet. It expires automatically if no payment arrives. |
reserved | Payment completed and the transfer is confirmed with the supplier. |
canceled | The order was canceled by the agency or the supplier. |
expired | The order was not paid in time and expired automatically. |
failed | The reservation could not be completed (for example the supplier rejected it after payment). |
- Search offers are valid for roughly 30 minutes. Creating an order from an expired offer returns error
8003; run a new search in that case. - Unpaid orders (
pendingPayment) expire roughly one hour after creation and move toexpiredstatus.
Take pickup and dropoff coordinates from the Locations endpoints (place search + place detail) instead of your own geocoding. Transfer suppliers map coordinates onto their own service regions; raw coordinates that fall slightly outside a supplier's region are silently dropped from the results, so the same search can return fewer or zero vehicles. Coordinates coming from /locations points of interest (airports, hotels, districts) match the supplier regions reliably.
Pass flightNumber (and returnFlightNumber for round trips) when creating the order. Suppliers use it to track the actual arrival time and adjust the pickup when a flight is delayed. Without it, the driver waits at the scheduled time only.
The payment response is the order read back after the charge, so it already reports the real reservation outcome. A reservation can also drop after being confirmed (for example a supplier-side cancellation), so re-checking the order status before the pickup time is recommended.
Integrated agency systems must forward the end user's IP address via the X-Forwarded-For header on order and payment requests. This information is required for audit and security purposes.
All monetary amounts in transfer responses are expressed in minor units (kuruş for TRY): {"amount": 145200, "currency": "TRY"} means 1,452.00 TRY.