Payment

Lists the payment types the hotel accepts for online bookings and starts the payment step for the selected type. What to do for each type is described in the Payment flow guide.

GET/external/online/payment/typeList payment types GET/external/payment/companyVirtual POS details POST/external/online/payment/type/{paymentType}Start the payment step

List payment types#

GET/external/online/payment/type

Authentication: Authorization: Bearer

Returns the payment types the hotel enabled for online sales. Fixed type IDs: 1 pay at hotel, 3 bank transfer, 9 credit card (card details sent with the booking), 10 online payment (virtual POS).

Query parameters

hotelIDintegerrequired

Hotel ID.

Response

200 Success.

Request

curl "https://test.hms.gen.tr/external/online/payment/type?hotelID=1000" \
  -H "Authorization: Bearer $HMS_TOKEN"

const res = await fetch("https://test.hms.gen.tr/external/online/payment/type?hotelID=1000", {
  headers: {
    "Authorization": `Bearer ${process.env.HMS_TOKEN}`
  }
});
const data = await res.json();

$ch = curl_init('https://test.hms.gen.tr/external/online/payment/type?hotelID=1000');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('HMS_TOKEN'),
    ],
]);
$data = json_decode(curl_exec($ch), true);

Response · 200

{
    "success": true,
    "count": 3,
    "items": [
        {
            "title": "Pay at Hotel",
            "title_translate": "odeme.otelde_odeme",
            "typeID": 1
        },
        {
            "title": "Bank Transfer",
            "title_translate": "odeme.havale",
            "typeID": 3
        },
        {
            "title": "Online Card Payment",
            "title_translate": "odeme.online_odeme",
            "typeID": 10
        }
    ]
}

Virtual POS details#

GET/external/payment/company

Authentication: Authorization: Bearer

Returns the hotel’s virtual POS provider and merchant details. Only needed if you integrate the provider directly on your side; the standard flow uses POST …/payment/type/10. The response contains secrets; keep it server-side.

Query parameters

hotelIDintegerrequired

Hotel ID.

Response

200 Success.

Error responses

200 hotel_company_info_could_not_found — no virtual POS configured for the hotel.

Request

curl "https://test.hms.gen.tr/external/payment/company?hotelID=1000" \
  -H "Authorization: Bearer $HMS_TOKEN"

const res = await fetch("https://test.hms.gen.tr/external/payment/company?hotelID=1000", {
  headers: {
    "Authorization": `Bearer ${process.env.HMS_TOKEN}`
  }
});
const data = await res.json();

$ch = curl_init('https://test.hms.gen.tr/external/payment/company?hotelID=1000');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('HMS_TOKEN'),
    ],
]);
$data = json_decode(curl_exec($ch), true);

Response · 200

{
    "success": true,
    "paymentCompany": {
        "merchant_id": "4000****",
        "store_key": "********",
        "terminal_no": "VP00****",
        "user": "demo_api",
        "password": "********",
        "max_installment": 6,
        "company_id": 3,
        "company_code": "iyzico",
        "company_name": "iyzico"
    }
}

Start the payment step#

POST/external/online/payment/type/{paymentType}

Authentication: Authorization: Bearer · Body: application/json

Returns what to do for the selected payment type. Types 1 and 9 need only hotelID; type 3 lists bank accounts; for type 10 the payment is started with guest and basket details and the returned code (HTML) is rendered on the guest’s page to hand over to the provider’s payment screen.

Path parameters

paymentTypeintegerrequired

Payment type ID.

13910

Request body

hotelIDintegerrequired

Hotel ID.

totalPricedecimal

Required for type 10. Total amount to charge.

orderIDstring

Required for type 10. Your order/booking number.

returnUrlstring

Required for type 10. URL the guest returns to after payment.

name / surname / email / phonestring

Required for type 10. Payer details.

city / addressstring

Required for type 10. Billing address.

countryIDinteger

Required for type 10. id from the country list.

baskets[]object[]

Required for type 10, at least one item. Each item: id, name, piece, price.

Response

200 Type 10: code contains an HTML fragment that hands over to the payment provider (an auto-submitting form, a window.location script or an embedded checkout form, depending on the provider). Render it as-is in the guest’s browser. For other types the message field says what to do.

Error responses

200 required_input_info_not_submitted (+ errors[]) — missing field for type 10; country_info_sent_incorrectly — invalid countryID; there_is_missing_info_in_the_shopping_cart — missing field in a basket item; bank_info_is_not_found — no bank account configured for type 3.
404 Unknown paymentType.

Request

curl -X POST "https://test.hms.gen.tr/external/online/payment/type/10" \
  -H "Authorization: Bearer $HMS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "hotelID": 1000,
    "totalPrice": 2330,
    "orderID": "4811174883",
    "returnUrl": "https://booking.example.com/payment/result",
    "name": "Ayşe",
    "surname": "Demir",
    "email": "[email protected]",
    "phone": "05551112233",
    "city": "Denizli",
    "address": "Kumsal Cad. No: 12",
    "countryID": 1,
    "baskets": [
        {
            "id": 2,
            "name": "Standard Room · Bed & Breakfast",
            "piece": 1,
            "price": 1930
        },
        {
            "id": 12,
            "name": "Dinner",
            "piece": 1,
            "price": 400
        }
    ]
}'

const res = await fetch("https://test.hms.gen.tr/external/online/payment/type/10", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.HMS_TOKEN}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
      "hotelID": 1000,
      "totalPrice": 2330,
      "orderID": "4811174883",
      "returnUrl": "https://booking.example.com/payment/result",
      "name": "Ayşe",
      "surname": "Demir",
      "email": "[email protected]",
      "phone": "05551112233",
      "city": "Denizli",
      "address": "Kumsal Cad. No: 12",
      "countryID": 1,
      "baskets": [
          {
              "id": 2,
              "name": "Standard Room · Bed & Breakfast",
              "piece": 1,
              "price": 1930
          },
          {
              "id": 12,
              "name": "Dinner",
              "piece": 1,
              "price": 400
          }
      ]
  })
});
const data = await res.json();

$ch = curl_init('https://test.hms.gen.tr/external/online/payment/type/10');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('HMS_TOKEN'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        'hotelID' => 1000,
        'totalPrice' => 2330,
        'orderID' => '4811174883',
        'returnUrl' => 'https://booking.example.com/payment/result',
        'name' => 'Ayşe',
        'surname' => 'Demir',
        'email' => '[email protected]',
        'phone' => '05551112233',
        'city' => 'Denizli',
        'address' => 'Kumsal Cad. No: 12',
        'countryID' => 1,
        'baskets' => [
            [
                'id' => 2,
                'name' => 'Standard Room · Bed & Breakfast',
                'piece' => 1,
                'price' => 1930,
            ],
            [
                'id' => 12,
                'name' => 'Dinner',
                'piece' => 1,
                'price' => 400,
            ],
        ],
    ]),
]);
$data = json_decode(curl_exec($ch), true);

Response · 200

{
    "success": true,
    "message": "payment_order_code",
    "code": "<form method=\"post\" action=\"https://vpos.provider.example/3d\"><input type=\"hidden\" name=\"orderId\" value=\"4811174883\"> … </form><script>document.forms[0].submit()</script>"
}

Response · 200 (type 3, bank transfer)

{
    "success": true,
    "message": "payment_by_bank_transfer",
    "banks": [
        {
            "companyName": "Ziraat Bank",
            "holder": "Demo Turizm A.Ş.",
            "branchName": "Denizli",
            "branchNumber": "0123",
            "bankAccountNumber": "12345678-5001",
            "iban": "TR00 0001 0001 2345 6789 5001 01"
        }
    ]
}

Response · 200 (type 1 / type 9)

{
    "success": true,
    "message": "credit_card_info_should_be_requested"
}

Last updated: 8 September 2026Found a mistake? Let us know