Pagamento

Elenca i tipi di pagamento che l’hotel accetta per le prenotazioni online e avvia la fase di pagamento per il tipo selezionato. Cosa fare per ciascun tipo è descritto nella guida Flusso di pagamento.

GET/external/online/payment/typeElenca i tipi di pagamento GET/external/payment/companyDati del POS virtuale POST/external/online/payment/type/{paymentType}Avvia la fase di pagamento

Elenca i tipi di pagamento#

GET/external/online/payment/type

Autenticazione: Authorization: Bearer

Restituisce i tipi di pagamento che l’hotel ha abilitato per la vendita online. ID di tipo fissi: 1 pagamento in hotel, 3 bonifico bancario, 9 carta di credito (dati della carta inviati con la prenotazione), 10 pagamento online (POS virtuale).

Parametri di query

hotelIDintegerobbligatorio

ID dell’hotel.

Risposta

200 Operazione riuscita.

Richiesta

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);

Risposta · 200

{
    "success": true,
    "count": 3,
    "items": [
        {
            "title": "Pagamento in hotel",
            "title_translate": "odeme.otelde_odeme",
            "typeID": 1
        },
        {
            "title": "Bonifico bancario",
            "title_translate": "odeme.havale",
            "typeID": 3
        },
        {
            "title": "Pagamento online con carta",
            "title_translate": "odeme.online_odeme",
            "typeID": 10
        }
    ]
}

Dati del POS virtuale#

GET/external/payment/company

Autenticazione: Authorization: Bearer

Restituisce il provider del POS virtuale dell’hotel e i dati dell’esercente. Serve solo se integri il provider direttamente dal tuo lato; il flusso standard usa POST …/payment/type/10. La risposta contiene dati riservati: conservala lato server.

Parametri di query

hotelIDintegerobbligatorio

ID dell’hotel.

Risposta

200 Operazione riuscita.

Risposte di errore

200 hotel_company_info_could_not_found — nessun POS virtuale configurato per l’hotel.

Richiesta

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);

Risposta · 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"
    }
}

Avvia la fase di pagamento#

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

Autenticazione: Authorization: Bearer · Corpo: application/json

Restituisce le operazioni da eseguire per il tipo di pagamento selezionato. I tipi 1 e 9 richiedono solo hotelID; il tipo 3 elenca i conti bancari; per il tipo 10 il pagamento viene avviato con i dati dell’ospite e del carrello e il code (HTML) restituito viene inserito nella pagina dell’ospite per passare alla schermata di pagamento del provider.

Parametri di percorso

paymentTypeintegerobbligatorio

ID del tipo di pagamento.

13910

Corpo della richiesta

hotelIDintegerobbligatorio

ID dell’hotel.

totalPricedecimal

Obbligatorio per il tipo 10. Importo totale da addebitare.

orderIDstring

Obbligatorio per il tipo 10. Il tuo numero d’ordine o di prenotazione.

returnUrlstring

Obbligatorio per il tipo 10. URL a cui l’ospite torna dopo il pagamento.

name / surname / email / phonestring

Obbligatorio per il tipo 10. Dati del pagante.

city / addressstring

Obbligatorio per il tipo 10. Indirizzo di fatturazione.

countryIDinteger

Obbligatorio per il tipo 10. id dall’elenco dei paesi.

baskets[]object[]

Obbligatorio per il tipo 10, almeno un elemento. Ogni elemento: id, name, piece, price.

Risposta

200 Tipo 10: code contiene un frammento HTML che passa il controllo al provider di pagamento (un form con invio automatico, uno script window.location o un form di checkout incorporato, a seconda del provider). Mostralo così com’è nel browser dell’ospite. Per gli altri tipi il campo message indica cosa fare.

Risposte di errore

200 required_input_info_not_submitted (+ errors[]) — campo mancante per il tipo 10; country_info_sent_incorrectly — countryID non valido; there_is_missing_info_in_the_shopping_cart — campo mancante in un elemento del carrello; bank_info_is_not_found — nessun conto bancario configurato per il tipo 3.
404 paymentType sconosciuto.

Richiesta

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": "Camera Standard · Pernottamento e colazione",
            "piece": 1,
            "price": 1930
        },
        {
            "id": 12,
            "name": "Cena",
            "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": "Camera Standard · Pernottamento e colazione",
              "piece": 1,
              "price": 1930
          },
          {
              "id": 12,
              "name": "Cena",
              "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' => 'Camera Standard · Pernottamento e colazione',
                'piece' => 1,
                'price' => 1930,
            ],
            [
                'id' => 12,
                'name' => 'Cena',
                'piece' => 1,
                'price' => 400,
            ],
        ],
    ]),
]);
$data = json_decode(curl_exec($ch), true);

Risposta · 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>"
}

Risposta · 200 (tipo 3, bonifico bancario)

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

Risposta · 200 (tipo 1 / tipo 9)

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

Ultimo aggiornamento: 21 settembre 2026Hai trovato un errore? Segnalacelo