Transfer Payment

Transfer payments are a two-step model: order creation returns a paymentRequirement, and the payment endpoint charges exactly that amount. Transfer orders are paid with the agency's credit limit.

1. POST /transfer/orders creates the order and returns paymentRequirement, the exact amount to charge.
2. POST /transfer/orders/{orderId}/pay charges that amount. A successful payment triggers the reservation with the supplier synchronously, and the response is the order in its current state: reserved once the reservation completed, or failed if the supplier refused it.

Paying an order that is already paid returns error 8009. There is no double-charge risk: concurrent payment attempts on the same order are serialized, and the second attempt fails with 8009 (or 8008 if it lands while the first one is still processing).

POST /transfer/orders/{orderId}/pay

This endpoint requires authentication. Include your JWT access token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Integrated 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.

curl -X POST https://api.pro.yolcu360.com/api/v1/transfer/orders/YLPB_0503/pay \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Forwarded-For: 203.0.113.195" \
  -d '{
    "paymentType": "limit"
  }'

The response is the order in its current state, read back after the charge. It has the same shape as the order creation and order detail responses; product is abbreviated below, see Transfer Orders for the full structure.

The reservation is already confirmed and vendorReservationId is available:

{
  "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
    },
    "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"}
  ]
}

If the supplier refused the reservation after the charge went through, the same response comes back with status: "failed" (see the edge cases below).

Paying an order that is already paid fails without charging anything:

{
  "code": 8009,
  "description": "Transfer order is already paid",
  "details": {
    "orderId": "YLPB_0503"
  }
}

Treat 8009 as "check the order status": the order is most likely reserved already.

If a second payment attempt lands while the first one is still processing, it can fail with 8008 (payment failed) instead of 8009. No double charge happens in either case. Retry policy: check the order status first; retry the payment only when the order is still pendingPayment.

In rare cases the charge succeeds but the supplier reservation fails. The payment returns error 8010 (Payment succeeded but the reservation could not be completed) or a 200 response whose status is failed. In both cases check the order detail and contact support; the payment is not lost.

Orders expire roughly one hour after creation when unpaid. Paying an expired order fails; create a new order from a fresh search.