Pagamento

Lista os tipos de pagamento que o hotel aceita em reservas online e inicia a etapa de pagamento para o tipo selecionado. O que fazer em cada tipo está descrito no guia Fluxo de pagamento.

GET/external/online/payment/typeListar tipos de pagamentoGET/external/payment/companyDados do POS virtualPOST/external/online/payment/type/{paymentType}Iniciar a etapa de pagamento

Listar tipos de pagamento#

GET/external/online/payment/type

Autenticação: Authorization: Bearer

Retorna os tipos de pagamento que o hotel habilitou para vendas online. IDs fixos dos tipos: 1 pagamento no hotel, 3 transferência bancária, 9 cartão de crédito (dados do cartão enviados com a reserva), 10 pagamento online (POS virtual).

Parâmetros de consulta

hotelIDintegerobrigatório
ID do hotel.

Resposta

200 Sucesso.

Requisição
curl "https://test.hms.gen.tr/external/online/payment/type?hotelID=1000" \
  -H "Authorization: Bearer $HMS_TOKEN"
Resposta · 200
{
    "success": true,
    "count": 3,
    "items": [
        {
            "title": "Pagamento no hotel",
            "title_translate": "odeme.otelde_odeme",
            "typeID": 1
        },
        {
            "title": "Transferência bancária",
            "title_translate": "odeme.havale",
            "typeID": 3
        },
        {
            "title": "Pagamento online com cartão",
            "title_translate": "odeme.online_odeme",
            "typeID": 10
        }
    ]
}

Dados do POS virtual#

GET/external/payment/company

Autenticação: Authorization: Bearer

Retorna o provedor de POS virtual do hotel e os dados do estabelecimento. Só é necessário se você integrar o provedor diretamente do seu lado; o fluxo padrão usa POST …/payment/type/10. A resposta contém dados sigilosos; mantenha-a no servidor.

Parâmetros de consulta

hotelIDintegerobrigatório
ID do hotel.

Resposta

200 Sucesso.

Respostas de erro

  • 200 hotel_company_info_could_not_found — nenhum POS virtual configurado para o hotel.
Requisição
curl "https://test.hms.gen.tr/external/payment/company?hotelID=1000" \
  -H "Authorization: Bearer $HMS_TOKEN"
Resposta · 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"
    }
}

Iniciar a etapa de pagamento#

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

Autenticação: Authorization: Bearer · Corpo: application/json

Retorna o que fazer para o tipo de pagamento selecionado. Os tipos 1 e 9 precisam apenas de hotelID; o tipo 3 lista as contas bancárias; no tipo 10, o pagamento é iniciado com os dados do hóspede e do carrinho, e o code (HTML) retornado é renderizado na página do hóspede para levá-lo à tela de pagamento do provedor.

Parâmetros de caminho

paymentTypeintegerobrigatório
ID do tipo de pagamento.
13910

Corpo da requisição

hotelIDintegerobrigatório
ID do hotel.
totalPricedecimal
Obrigatório para o tipo 10. Valor total a cobrar.
orderIDstring
Obrigatório para o tipo 10. Seu número de pedido/reserva.
returnUrlstring
Obrigatório para o tipo 10. URL para a qual o hóspede volta após o pagamento.
name / surname / email / phonestring
Obrigatório para o tipo 10. Dados do pagador.
city / addressstring
Obrigatório para o tipo 10. Endereço de cobrança.
countryIDinteger
Obrigatório para o tipo 10. id da lista de países.
baskets[]object[]
Obrigatório para o tipo 10, com pelo menos um item. Cada item: id, name, piece, price.

Resposta

200 Tipo 10: code contém um fragmento HTML que leva ao provedor de pagamento (um formulário com envio automático, um script window.location ou um formulário de checkout incorporado, conforme o provedor). Renderize-o sem alterações no navegador do hóspede. Nos demais tipos, o campo message informa o que fazer.

Respostas de erro

  • 200 required_input_info_not_submitted (+ errors[]) — campo ausente para o tipo 10; country_info_sent_incorrectly — countryID inválido; there_is_missing_info_in_the_shopping_cart — campo ausente em um item do carrinho; bank_info_is_not_found — nenhuma conta bancária configurada para o tipo 3.
  • 404 paymentType desconhecido.
Requisição
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": "Quarto Standard · Café da manhã incluído",
            "piece": 1,
            "price": 1930
        },
        {
            "id": 12,
            "name": "Jantar",
            "piece": 1,
            "price": 400
        }
    ]
}'
Resposta · 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>"
}
Resposta · 200 (tipo 3, transferência bancária)
{
    "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"
        }
    ]
}
Resposta · 200 (tipo 1 / tipo 9)
{
    "success": true,
    "message": "credit_card_info_should_be_requested"
}
Última atualização: 21 de setembro de 2026Encontrou um erro? Avise-nos