{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Transfer Payment"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"transfer-payment","__idx":0},"children":["Transfer Payment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Transfer payments are a two-step model: order creation returns a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentRequirement"]},", and the payment endpoint charges"," ","exactly that amount. Transfer orders are paid with the agency's credit limit."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"two-step-payment-model","__idx":1},"children":["Two-Step Payment Model"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /transfer/orders"]}," creates the order and returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentRequirement"]},", the exact amount to charge."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /transfer/orders/{orderId}/pay"]}," charges that amount. A successful payment triggers the reservation with the"," ","supplier ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["synchronously"]},", and the response is the order in its current state: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reserved"]}," once the reservation"," ","completed, or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed"]}," if the supplier refused it."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Paying an order that is already paid returns error ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["8009"]},". There is no double-charge risk: concurrent payment attempts"," ","on the same order are serialized, and the second attempt fails with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["8009"]}," (or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["8008"]}," if it lands while the first one"," ","is still processing)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"pay-for-an-order","__idx":2},"children":["Pay for an Order"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"endpoint","__idx":3},"children":["Endpoint"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"POST /transfer/orders/{orderId}/pay\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"authentication","__idx":4},"children":["Authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This endpoint requires authentication. Include your JWT access token in the Authorization header:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"Authorization: Bearer YOUR_ACCESS_TOKEN\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"end-user-ip-address","__idx":5},"children":["End User 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. This information is"," ","required for audit and security purposes."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"path-parameters","__idx":6},"children":["Path Parameters"]},{"$$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":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$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":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transfer order identifier"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"request-body","__idx":7},"children":["Request Body"]},{"$$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":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$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":["paymentType"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payment method, always ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["limit"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-request","__idx":8},"children":["Example Request"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST https://api.pro.yolcu360.com/api/v1/transfer/orders/YLPB_0503/pay \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\" \\\n  -H \"X-Forwarded-For: 203.0.113.195\" \\\n  -d '{\n    \"paymentType\": \"limit\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"response","__idx":9},"children":["Response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product"]}," is abbreviated below, see"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/endpoints/transfer-orders"},"children":["Transfer Orders"]}," for the full structure."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"payment-completed-200-ok","__idx":10},"children":["Payment Completed (200 OK)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The reservation is already confirmed and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vendorReservationId"]}," is available:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"orderId\": \"YLPB_0503\",\n  \"status\": \"reserved\",\n  \"vendorReservationId\": \"227699\",\n  \"flightNumber\": \"TK2021\",\n  \"product\": {\n    \"code\": \"9972a93a-707e-403e-928e-cbb68a65584f\",\n    \"appointment\": {\n      \"pickup\": {\"lat\": 41.276146, \"lon\": 28.728735, \"name\": \"Istanbul Airport (IST)\"},\n      \"dropoff\": {\"lat\": 41.037003, \"lon\": 28.985092, \"name\": \"Taksim Square\"},\n      \"pickupTime\": \"2027-06-15T10:00:00+03:00\",\n      \"passengerCount\": 2\n    },\n    \"vehicle\": {\"name\": \"Minivan\", \"seatCount\": 6, \"baggageCount\": 6},\n    \"pricing\": {\"currency\": \"TRY\", \"total\": {\"amount\": 145200, \"currency\": \"TRY\"}},\n    \"cancellationPolicies\": [\n      {\"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.\"}\n    ]\n  },\n  \"passengers\": [\n    {\"primary\": true, \"firstName\": \"John\", \"lastName\": \"Doe\", \"gender\": \"M\", \"birthDate\": \"1990-01-15\", \"nationality\": \"US\", \"passportNo\": \"AB1234567\", \"email\": \"john.doe@example.com\", \"phone\": \"+905551234567\"},\n    {\"primary\": false, \"firstName\": \"Jane\", \"lastName\": \"Doe\", \"identityNumber\": \"11111111110\"}\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the supplier refused the reservation after the charge went through, the same response comes back with"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status: \"failed\""]}," (see the edge cases below)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"response-fields","__idx":11},"children":["Response Fields"]},{"$$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":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$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":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transfer order identifier"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Order lifecycle status: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reserved"]}," when the payment completed, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed"]}," if the supplier refused the reservation"]}]},{"$$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":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Supplier booking reference. Present once the order is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reserved"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["flightNumber"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Flight number supplied at order creation"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["returnFlightNumber"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Return flight number supplied at order creation (round trips)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The booked offer, same structure as the search response product"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["passengers"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["array"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The passenger data supplied at order creation"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"edge-cases","__idx":12},"children":["Edge Cases"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"order-already-paid-8009","__idx":13},"children":["Order already paid (8009)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Paying an order that is already paid fails without charging anything:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"code\": 8009,\n  \"description\": \"Transfer order is already paid\",\n  \"details\": {\n    \"orderId\": \"YLPB_0503\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Treat ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["8009"]}," as \"check the order status\": the order is most likely ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reserved"]}," already."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"concurrent-payment-attempts-8008","__idx":14},"children":["Concurrent payment attempts (8008)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If a second payment attempt lands while the first one is still processing, it can fail with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["8008"]}," (payment failed)"," ","instead of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["8009"]},". No double charge happens in either case. Retry policy: check the order status first; retry the"," ","payment only when the order is still ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pendingPayment"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"payment-succeeded-but-reservation-failed-8010","__idx":15},"children":["Payment succeeded but reservation failed (8010)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In rare cases the charge succeeds but the supplier reservation fails. The payment returns error ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["8010"]}," ","(",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Payment succeeded but the reservation could not be completed"]},") or a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}," response whose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed"]},". In"," ","both cases check the order detail and contact support; the payment is not lost."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"expired-order","__idx":16},"children":["Expired order"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Orders expire roughly one hour after creation when unpaid. Paying an expired order fails; create a new order from a"," ","fresh search."]}]},"headings":[{"value":"Transfer Payment","id":"transfer-payment","depth":1},{"value":"Two-Step Payment Model","id":"two-step-payment-model","depth":2},{"value":"Pay for an Order","id":"pay-for-an-order","depth":2},{"value":"Endpoint","id":"endpoint","depth":3},{"value":"Authentication","id":"authentication","depth":3},{"value":"End User IP Address","id":"end-user-ip-address","depth":3},{"value":"Path Parameters","id":"path-parameters","depth":3},{"value":"Request Body","id":"request-body","depth":3},{"value":"Example Request","id":"example-request","depth":3},{"value":"Response","id":"response","depth":3},{"value":"Payment Completed (200 OK)","id":"payment-completed-200-ok","depth":4},{"value":"Response Fields","id":"response-fields","depth":3},{"value":"Edge Cases","id":"edge-cases","depth":2},{"value":"Order already paid (8009)","id":"order-already-paid-8009","depth":3},{"value":"Concurrent payment attempts (8008)","id":"concurrent-payment-attempts-8008","depth":3},{"value":"Payment succeeded but reservation failed (8010)","id":"payment-succeeded-but-reservation-failed-8010","depth":3},{"value":"Expired order","id":"expired-order","depth":3}],"frontmatter":{"seo":{"title":"Transfer Payment"}},"lastModified":"2026-10-01T06:30:51.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/endpoints/transfer-payment","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}