{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Transfer Overview"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"transfer-overview","__idx":0},"children":["Transfer Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"integration-flow","__idx":1},"children":["Integration Flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A complete transfer booking consists of the following steps:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Search"]}," — Send pickup/dropoff coordinates, time, and passenger count to get available vehicles with pricing."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Offer Detail"]}," (optional) — Retrieve a single offer again by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["searchId"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create Order"]}," — Submit passengers and billing to create a reservation in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pendingPayment"]}," status."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Pay"]}," — Pay the exact ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentRequirement"]}," returned at creation with your credit limit."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Track"]}," — The payment response already returns the order as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reserved"]}," with its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vendorReservationId"]},"; retrieve"," ","the order detail to re-check the order before pickup."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Cancel"]}," (when needed) — Check eligibility and refund amount first, then cancel."]}]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"graph TD\n A[POST /transfer/search] --> B[Select offer]\n B --> C[POST /transfer/orders]\n C --> D[POST /transfer/orders/orderId/pay]\n D --> E[reserved]\n E --> F[GET /transfer/orders/orderId]\n F --> G{Cancel needed?}\n G -->|Yes| H[POST cancel_eligibility]\n H --> I[POST cancel]\n","diagramHtml":"

Yes

POST /transfer/search

Select offer

POST /transfer/orders

POST /transfer/orders/orderId/pay

reserved

GET /transfer/orders/orderId

Cancel needed?

POST cancel_eligibility

POST cancel

","diagramHtmlDark":"

Yes

POST /transfer/search

Select offer

POST /transfer/orders

POST /transfer/orders/orderId/pay

reserved

GET /transfer/orders/orderId

Cancel needed?

POST cancel_eligibility

POST cancel

"},"children":["graph TD\n A[POST /transfer/search] --> B[Select offer]\n B --> C[POST /transfer/orders]\n C --> D[POST /transfer/orders/orderId/pay]\n D --> E[reserved]\n E --> F[GET /transfer/orders/orderId]\n F --> G{Cancel needed?}\n G -->|Yes| H[POST cancel_eligibility]\n H --> I[POST cancel]\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See the dedicated pages for each step:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/endpoints/transfer-search"},"children":["Transfer Search"]}," — search and offer detail endpoints"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/endpoints/transfer-orders"},"children":["Transfer Orders"]}," — order creation, detail, and cancellation"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/endpoints/transfer-payment"},"children":["Transfer Payment"]}," — two-step payment"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"identifiers","__idx":2},"children":["Identifiers"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Identifier"},"children":["Identifier"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Example"},"children":["Example"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["orderId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["YLPB_0503"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The transfer order identifier, returned at order creation. Use it in every transfer endpoint."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vendorReservationId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["227699"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The supplier's booking reference, assigned when the reservation completes. Use it when matching the booking with the supplier or driver."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vendorReservationId"]}," is absent while the order is in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"order-lifecycle","__idx":3},"children":["Order Lifecycle"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pendingPayment"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The order is created but not paid yet. It expires automatically if no payment arrives."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reserved"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payment completed and the transfer is confirmed with the supplier."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["canceled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The order was canceled by the agency or the supplier."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expired"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The order was not paid in time and expired automatically."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The reservation could not be completed (for example the supplier rejected it after payment)."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"expiration-windows","__idx":4},"children":["Expiration Windows"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Search offers"]}," are valid for roughly ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["30 minutes"]},". Creating an order from an expired offer returns error ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["8003"]},";"," ","run a new search in that case."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Unpaid orders"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pendingPayment"]},") expire roughly ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["one hour"]}," after creation and move to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expired"]}," status."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"key-recommendations","__idx":5},"children":["Key Recommendations"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"use-locations-coordinates-strongly-recommended","__idx":6},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/locations"]}," coordinates (strongly recommended)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Take pickup and dropoff coordinates from the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/endpoints/locations"},"children":["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 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["silently dropped"]}," from the results, so the same search can return fewer or"," ","zero vehicles. Coordinates coming from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/locations"]}," points of interest (airports, hotels, districts) match the supplier"," ","regions reliably."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"provide-the-flight-number-for-airport-pickups-strongly-recommended","__idx":7},"children":["Provide the flight number for airport pickups (strongly recommended)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Pass ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["flightNumber"]}," (and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"confirm-the-final-status-via-order-detail","__idx":8},"children":["Confirm the final status via order detail"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"forward-the-end-users-ip-address","__idx":9},"children":["Forward the end user's IP address"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Integrated agency systems must forward the end user's IP address via the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Forwarded-For"]}," header on order and payment"," ","requests. This information is required for audit and security purposes."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"amounts","__idx":10},"children":["Amounts"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All monetary amounts in transfer responses are expressed in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["minor units"]}," (kuruş for TRY): ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{\"amount\": 145200, \"currency\": \"TRY\"}"]}," means 1,452.00 TRY."]}]},"headings":[{"value":"Transfer Overview","id":"transfer-overview","depth":1},{"value":"Integration Flow","id":"integration-flow","depth":2},{"value":"Identifiers","id":"identifiers","depth":2},{"value":"Order Lifecycle","id":"order-lifecycle","depth":2},{"value":"Expiration Windows","id":"expiration-windows","depth":2},{"value":"Key Recommendations","id":"key-recommendations","depth":2},{"value":"Use /locations coordinates (strongly recommended)","id":"use-locations-coordinates-strongly-recommended","depth":3},{"value":"Provide the flight number for airport pickups (strongly recommended)","id":"provide-the-flight-number-for-airport-pickups-strongly-recommended","depth":3},{"value":"Confirm the final status via order detail","id":"confirm-the-final-status-via-order-detail","depth":3},{"value":"Forward the end user's IP address","id":"forward-the-end-users-ip-address","depth":3},{"value":"Amounts","id":"amounts","depth":2}],"frontmatter":{"seo":{"title":"Transfer Overview"}},"lastModified":"2026-10-01T06:30:51.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/endpoints/transfer-overview","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}