Transfer order endpoints create reservations from search offers and manage them afterwards: retrieving the current state, checking cancellation eligibility, and canceling.
Creates a transfer reservation from a search offer. The order starts in pendingPayment status; the response contains the exact amount to pay in the payment step.
POST /transfer/ordersThis endpoint requires authentication. Include your JWT access token in the Authorization header:
Authorization: Bearer YOUR_ACCESS_TOKENIntegrated agency systems must forward the end user's IP address via the X-Forwarded-For header. This information is required for audit and security purposes.
| Field | Type | Required | Description |
|---|---|---|---|
searchId | string | Yes | Search identifier from the transfer search |
code | string | Yes | Selected offer code from the search results |
passengers | array | Yes | Passenger list; exactly one passenger must have primary: true |
billing | object | No | Custom billing information (see Billing below) |
flightNumber | string | No | Flight number for the outbound pickup (strongly recommended for airport pickups) |
returnFlightNumber | string | No | Flight number for the return pickup (round trips) |
Provide flightNumber whenever the pickup is at an airport. Suppliers use it to track the actual arrival time and adjust the pickup when the flight is delayed; without it the driver only waits at the scheduled time.
Exactly one passenger must be marked primary: true; this is the contact passenger for the trip. Every passenger needs a name and exactly one identity document (identityNumber or passportNo). The remaining fields are required only for the primary passenger.
| Field | Type | Required | Description |
|---|---|---|---|
primary | boolean | Yes | Contact passenger flag. Exactly one must be true |
firstName | string | Yes | Passenger first name |
lastName | string | Yes | Passenger last name |
gender | string | Primary only | M or F |
birthDate | string | Primary only | Birth date (YYYY-MM-DD format) |
nationality | string | Primary only | ISO country code (2 characters) |
email | string | Primary only | Valid email address |
phone | string | Primary only | Phone number in E.164 format |
identityNumber | string | One of the two | 11-digit identity number (for Turkish citizens) |
passportNo | string | One of the two | Passport number (for international travelers) |
billing is optional. When it is omitted, the invoice is issued to your organization's registered billing address; if no billing address is registered for the organization, the request fails with error 5003.
Sending billing requires custom billing to be enabled for your agency. Without that permission the request is rejected with error 5004 even when the billing object is valid. Contact Yolcu360 to enable custom billing.
When sent, transfer billing is stricter than car rental billing: taxIdentifier and zipCode are always required (use the identity number for individuals), and line must be at least 5 characters.
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | Address type: individual, privateCompany, or corporateCompany |
firstName | string | Yes | Billing first name (or company name for corporateCompany) |
lastName | string | Conditional | Billing last name. Required unless type is corporateCompany |
email | string | Yes | Billing email address |
phone | string | Yes | Billing phone number in E.164 format |
countryCode | string | Yes | ISO country code (2 characters) |
countryName | string | Yes | Full country name |
adm1 | string | Yes | Administrative division level 1 (state/province) |
adm2 | string | No | Administrative division level 2 (city/district) |
line | string | Yes | Address line (minimum 5 characters) |
zipCode | string | Yes | Postal/ZIP code |
taxIdentifier | string | Yes | Tax ID number (identity number for individuals) |
taxDivision | string | Company types | Tax office/division. Required for privateCompany and corporateCompany |
curl -X POST https://api.pro.yolcu360.com/api/v1/transfer/orders \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "X-Forwarded-For: 203.0.113.195" \
-d '{
"searchId": "0ba0fea9-1e98-43ce-a69b-e895e2bc68a6",
"code": "9972a93a-707e-403e-928e-cbb68a65584f",
"flightNumber": "TK2021",
"passengers": [
{
"primary": true,
"firstName": "John",
"lastName": "Doe",
"gender": "M",
"birthDate": "1990-01-15",
"nationality": "US",
"passportNo": "AB1234567",
"email": "john.doe@example.com",
"phone": "+905551234567"
},
{
"primary": false,
"firstName": "Jane",
"lastName": "Doe",
"identityNumber": "11111111110"
}
],
"billing": {
"type": "individual",
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@example.com",
"phone": "+905551234567",
"countryCode": "TR",
"countryName": "Turkey",
"adm1": "Istanbul",
"adm2": "Beyoglu",
"line": "Kocatepe Mah. Taksim Square No:1",
"zipCode": "34437",
"taxIdentifier": "11111111110"
}
}'Success Response (201 Created):
The response is the order itself, in the same shape as the order detail and the payment response. product is abbreviated here; it has the same structure as in the order detail below.
{
"orderId": "YLPB_0503",
"status": "pendingPayment",
"paymentRequirement": {
"amount": 145200,
"currency": "TRY"
},
"flightNumber": "TK2021",
"product": {
"code": "9972a93a-707e-403e-928e-cbb68a65584f",
"appointment": {
"pickup": {"lat": 41.276146, "lon": 28.728735, "name": "Istanbul Airport (IST)"},
"dropoff": {"lat": 41.037003, "lon": 28.985092, "name": "Taksim Square"},
"pickupTime": "2027-06-15T10:00:00+03:00",
"passengerCount": 2
},
"vehicle": {"name": "Minivan", "seatCount": 6, "baggageCount": 6},
"pricing": {"currency": "TRY", "total": {"amount": 145200, "currency": "TRY"}},
"cancellationPolicies": [
{"type": "freeCancel", "until": "2027-06-15T09:00:00+03:00", "description": "You can cancel your transfer free of charge up to 1 hour before departure."}
]
},
"passengers": [
{"primary": true, "firstName": "John", "lastName": "Doe", "gender": "M", "birthDate": "1990-01-15", "nationality": "US", "passportNo": "AB1234567", "email": "john.doe@example.com", "phone": "+905551234567"},
{"primary": false, "firstName": "Jane", "lastName": "Doe", "identityNumber": "11111111110"}
]
}| Field | Type | Description |
|---|---|---|
orderId | string | Transfer order identifier (YLPB_xxxx). Use it in every subsequent transfer call |
status | string | Order lifecycle status, always pendingPayment right after creation |
paymentRequirement | object | The exact amount to pay in the payment step, in minor units. Returned only on create |
flightNumber | string | Flight number supplied in the request |
returnFlightNumber | string | Return flight number supplied in the request (round trips) |
product | object | The booked offer, same structure as the search response product |
passengers | array | The passenger data supplied in the request |
The order is now in pendingPayment status and expires roughly one hour after creation if no payment arrives. Continue with Transfer Payment.
Retrieve the current state of a transfer order: lifecycle status, the booked product, and the passengers.
GET /transfer/orders/{orderId}This endpoint requires authentication. Include your JWT access token in the Authorization header.
| Parameter | Type | Required | Description |
|---|---|---|---|
orderId | string | Yes | Transfer order identifier |
curl -X GET https://api.pro.yolcu360.com/api/v1/transfer/orders/YLPB_0503 \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"Success Response (200 OK):
{
"orderId": "YLPB_0503",
"status": "reserved",
"vendorReservationId": "227699",
"flightNumber": "TK2021",
"product": {
"code": "9972a93a-707e-403e-928e-cbb68a65584f",
"appointment": {
"pickup": {
"lat": 41.276146,
"lon": 28.728735,
"name": "Istanbul Airport (IST)"
},
"dropoff": {
"lat": 41.037003,
"lon": 28.985092,
"name": "Taksim Square"
},
"pickupTime": "2027-06-15T10:00:00+03:00",
"passengerCount": 2
},
"onewayDistance": 41662,
"onewayDuration": 2727,
"vehicle": {
"name": "Minivan",
"seatCount": 6,
"baggageCount": 6,
"image": "https://cdn.example.com/assets/images/van.png"
},
"pricing": {
"currency": "TRY",
"fees": [
{
"amount": 132000,
"currency": "TRY",
"type": "oneway",
"charge": "advance",
"description": "Outbound Trip Amount"
},
{
"amount": 13200,
"currency": "TRY",
"type": "commission",
"charge": "advance",
"description": "commission"
}
],
"vendorTotal": {
"amount": 0,
"currency": "TRY"
},
"paymentTotal": {
"amount": 145200,
"currency": "TRY"
},
"discountTotal": {
"amount": 0,
"currency": "TRY"
},
"total": {
"amount": 145200,
"currency": "TRY"
}
},
"rules": [
{
"type": "freeCancellation",
"description": "Free Cancellation"
},
{
"type": "waitForFree",
"description": "First 15 minutes of waiting free"
},
{
"type": "safeTripWithInvoice",
"description": "Safe trip with invoice"
}
],
"cancellationPolicies": [
{
"type": "freeCancel",
"until": "2027-06-15T09:00:00+03:00",
"description": "You can cancel your transfer free of charge up to 1 hour before departure."
}
]
},
"passengers": [
{
"primary": true,
"firstName": "John",
"lastName": "Doe",
"gender": "M",
"birthDate": "1990-01-15",
"nationality": "US",
"passportNo": "AB1234567",
"email": "john.doe@example.com",
"phone": "+905551234567"
},
{
"primary": false,
"firstName": "Jane",
"lastName": "Doe",
"identityNumber": "11111111110"
}
]
}| Field | Type | Description |
|---|---|---|
orderId | string | Transfer order identifier |
status | string | Order lifecycle status (see the table below) |
vendorReservationId | string | Supplier booking reference. Present once the order is reserved; absent in pendingPayment |
flightNumber | string | Flight number supplied at order creation |
returnFlightNumber | string | Return flight number supplied at order creation (round trips) |
product | object | The booked offer, same structure as the search response product |
passengers | array | The passenger data supplied at order creation |
| Status | Description |
|---|---|
pendingPayment | Order created, awaiting payment. Expires roughly one hour after creation if unpaid |
reserved | Payment completed and the transfer confirmed with the supplier |
canceled | Order canceled by the agency or the supplier |
expired | Order was not paid in time and expired automatically |
failed | Reservation could not be completed |
The payment response already carries the order in its current state, read back after the charge, so the payment needs no follow-up detail call. Use this endpoint to re-check the order later: a reserved order can also drop (for example a supplier-side cancellation), so re-checking the status before the pickup time is recommended.
vendorReservationId is available from reserved onward and stays on the order after cancellation. On an order that later fails on the supplier side it may be missing.
Checks whether an order can be canceled and how much would be refunded. This endpoint does not modify the order.
POST /transfer/orders/{orderId}/cancel_eligibilityThis endpoint requires authentication. Include your JWT access token in the Authorization header.
| Parameter | Type | Required | Description |
|---|---|---|---|
orderId | string | Yes | Identifier of the order to check |
curl -X POST https://api.pro.yolcu360.com/api/v1/transfer/orders/YLPB_0503/cancel_eligibility \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"Success Response (200 OK):
{
"orderId": "YLPB_0503",
"cancellable": true,
"refundAmount": {
"amount": 145200,
"currency": "TRY"
}
}| Field | Type | Description |
|---|---|---|
orderId | string | Transfer order identifier |
cancellable | boolean | Whether the order can be canceled now |
refundAmount | object | Amount to be refunded if the order is canceled now, in minor units. Omitted when not applicable |
refundAmount already has any cancellation penalty applied (see the offer's cancellationPolicies) and is capped at the amount actually paid. Note that the transfer eligibility response is richer than the car rental one: it returns the concrete refund amount instead of a refundable flag.
Cancels a transfer order. The cancellation is forwarded to the supplier; a 200 response is returned only when the supplier accepts the cancellation. The refund is issued automatically back to your credit limit.
POST /transfer/orders/{orderId}/cancelThis endpoint requires authentication. Include your JWT access token in the Authorization header.
| Parameter | Type | Required | Description |
|---|---|---|---|
orderId | string | Yes | Identifier of the order to cancel |
curl -X POST https://api.pro.yolcu360.com/api/v1/transfer/orders/YLPB_0503/cancel \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"Success Response (200 OK):
{
"orderId": "YLPB_0503",
"status": "canceled"
}If the supplier refuses the cancellation, or the order is not in a cancellable state (for example it was already canceled), the endpoint returns error 8012:
{
"code": 8012,
"description": "Transfer order cannot be canceled",
"details": {
"orderId": "YLPB_0503",
"status": "canceled"
}
}Check cancel eligibility before canceling to avoid surprises, and treat 8012 as a non-retriable outcome: contact support if a cancellation is required but keeps failing.