RateHawk API Integration 2027: Step-by-Step Developer Guideratehawk api integration

RateHawk API Integration 2027: Step-by-Step Developer Guide

Travora Hub · November 15, 2026

Reviewed by , Founder and CEO, Travora Hub

RateHawk API integration in 2027, step by step: ETG API v3 search, prebook, booking, status polling, certification tests and the mistakes to avoid.

A RateHawk API integration in 2027 means building against ETG API v3, the B2B API from Emerging Travel Group, the company behind RateHawk. Your site searches hotels through it, re-checks the chosen rate, creates the booking, and then polls until ETG gives a final answer. Before production keys are issued, ETG reviews your flow in a certification step and asks for your server's IP addresses. This guide lists every call in the order a real booking makes them, with the mistakes that cost us time when we certified our own integration in September 2026.

If you only need the agent login or registration steps, read our RateHawk guide for travel agencies. If you are deciding between the co-branded product, the affiliate API and the B2B API, start with RateHawk white label explained. This article is for the people who will write and test the code.

What you need before you write code

  • An approved RateHawk account and a signed API agreement. ETG's API documentation says the agreement comes before API use, so start this first. It is usually the slowest step.
  • Sandbox credentials. You receive a key ID and an API key and send them with HTTP basic authentication. The sandbox host is api-sandbox.worldota.net.
  • A payment type decision. With deposit, ETG takes the cost from your prepaid balance and you charge the guest yourself. With now, the guest pays by card in the flow. With hotel, the guest pays at the property. Pick one to certify; deposit is the usual choice for an agency that is the merchant of record.
  • A fixed outbound IP address. Production keys only work from whitelisted IPs, so shared hosting with changing addresses will block you at go-live.

The RateHawk API call sequence

This is the order of calls for one hotel booking on a website. Every endpoint below sits under /api/b2b/v3/.

StepWhen it runsEndpoint
Destination autocompleteThe guest types a city or hotel namesearch/multicomplete/
Region searchThe guest submits the search formsearch/serp/region/
Map searchThe guest moves the mapsearch/serp/geo/
Hotel list searchYou already know which hotel IDs to pricesearch/serp/hotels/
Static contentThe hotel page openshotel/info/ or the dumps
Hotel availabilityThe hotel page openssearch/hp/
Rate re-checkThe guest clicks Book on a roomhotel/prebook/
Booking formThe guest details page openshotel/order/booking/form/
Start bookingThe guest confirms and payshotel/order/booking/finish/
Booking statusEvery few seconds after finishhotel/order/booking/finish/status/
Retrieve bookingVoucher page, admin viewhotel/order/info/
VoucherStaff download the voucherhotel/order/document/voucher/download/
CancelStaff or the guest cancelhotel/order/cancel/

ETG's certification checklist asks you to fill in a table very like this one, so writing it down early saves time later.

Step 1: Search

Most sites resolve the destination with multicomplete, take the region ID it returns, and call serp/region with the dates, the guests per room, the currency and the guest's residency. Residency matters: the same room can be priced differently for a guest from the UAE and a guest from the UK, and certification includes a test with a non-default residency. Send children as ages, not as a count. Ages 0 and 17 are both valid and both appear in the test cases.

Set a hard timeout on every outbound request and decide what the guest sees when it hits. We use 20 seconds for search calls. A search that hangs with no message loses the guest faster than a clear "no rooms found" does.

Step 2: Static content

Search responses carry prices, not photos. Hotel names, images, addresses, amenities and room descriptions come from static data. You have two options. You can download the hotel dump and the incremental dump and keep your own copy up to date, which suits a large site with its own hotel database. Or you can call hotel/info when a hotel page opens and cache the answer for a short time, which is simpler and is what we certified with. Either way, ETG will ask which method you use and how often you refresh.

Room photos and amenities are matched to the live rates through the rg_ext room group fields. Match on those, not on room names, because names vary between rates for the same room.

Step 3: The hotel page and prebook

When the hotel page opens, call search/hp for that hotel alone to get fresh rooms and rates. Search results can be minutes old, and the hotel page is where the guest decides.

When the guest clicks Book, call hotel/prebook with the rate's hash. Prebook confirms the rate still exists and returns a new hash to book with. Send price_increase_percent to say how much of a price rise you will accept without failing. If the response says the price changed, show the guest the old and new totals and ask them to accept before you go on. This exact screen is one of the certification scenarios, and ETG will look for it.

Give prebook enough time. In the sandbox we saw prebook calls take between 13 and 47 seconds, and our first 20-second timeout made the site report a connection failure on rates that were fine. We raised prebook and booking form timeouts to 60 seconds, which is inside ETG's limit.

Step 4: Booking form and payment

hotel/order/booking/form creates the order on ETG's side. You send your own partner_order_id, which must be unique for every attempt, and the guest's IP address in user_ip. Keep that ID in your database from this moment, because it is how you and ETG's support team will talk about the booking.

If you are on deposit and charge the guest yourself, take the payment after the booking form and before finish. Then make sure every failure path after that point refunds the guest automatically. A booking that fails at finish after the card was charged is the support ticket you least want.

Watch the time between booking form and finish. In our sandbox runs, a guest who spent 30 to 90 seconds typing card details sometimes got rate_not_found at finish, while the same request sent straight away worked. Ask your ETG contact how long a rate is held, and design the payment step to be quick.

Step 5: Finish and status polling

This is the step most teams get wrong. A successful reply from hotel/order/booking/finish does not mean the booking is confirmed. It means ETG has started working on it. The final answer comes from hotel/order/booking/finish/status, which you poll every few seconds until it returns a final status. We poll every 5 seconds.

What ETG returnsWhat it meansWhat to do
ok from statusBooking confirmedStop polling, show the confirmation, send the voucher
processingStill workingPoll again
timeout, unknown or a 5xx errorThe result is not known yetKeep polling to your deadline. Never mark the booking failed on these alone
soldout, book_limit and other final errorsBooking failedStop, tell the guest, refund the card
booking_form_expired at finishThe session is too oldSend the guest back to choose the room again
rate_not_found at finishThe rate has goneRefund and send the guest back to the room list

The unknown cases are tested on purpose. ETG's test scenarios ask you to add markers to the end of partner_order_id so the sandbox returns unknown first and then success, sold out or booking limit. Your code passes only if it keeps polling through unknown and then acts on the final status. ETG also offers booking webhooks; polling is accepted, and the checklist asks which you use.

Step 6: Vouchers, retrieval and cancellation

Use hotel/order/info to read a booking back for your admin screens and voucher, and hotel/order/document/voucher/download if you want ETG's own voucher PDF. Cancel with hotel/order/cancel, and read the cancellation policy from the rate before you promise the guest a free cancellation. Show the penalty dates in the hotel's time zone or state clearly which time zone you use.

Which price to show

Each rate lists its payment options. The amount to display is show_amount in show_currency_code on the payment type you use. On a commission contract, the commission is calculated on ETG's side and is already inside that figure. Add your own markup on top in your code, and keep the net price, your markup and the selling price as separate fields on every booking so your accounts reconcile. Our markup guide covers how agencies set that number.

RateHawk API certification in 2027

Certification is a review of your live flow on the sandbox. ETG sends a pre-certification checklist, and you return a filled-in copy with the test bookings attached. Expect it to cover:

  • Your call sequence and which endpoints you use, as in the table above.
  • How you get and refresh static data and region data.
  • Expected requests per minute for search, hotel page and prebook.
  • Your timeouts, your final price field and where commission is calculated.
  • How you show each error and status to the guest.
  • The outbound IP addresses to whitelist and the website URL ETG can test.
  • Test bookings with their partner_order_id values.

The test bookings we ran in September 2026 were:

  1. Two rooms with different guests, including children of different ages.
  2. One room with two adults and children aged 0 and 17.
  3. A booking with a non-default residency.
  4. A rate whose price rises at prebook, with the change shown to the guest and accepted.
  5. Three bookings that return unknown and then end in success, sold out and booking limit.

ETG's own guidance puts certification at about 14 to 30 days. The bookings themselves take a day if your flow is ready. The time goes on fixing what the review finds and on getting the commercial details, IPs and contact names agreed.

Lessons from our own certification

  • Test every screen, not only the API. Our price change alert worked in the code but opened behind the room pop-up, so guests on a price-increase rate looked stuck. Nobody would have noticed in an API test.
  • Never confirm on finish. One of our payment paths marked bookings confirmed on the finish reply. It now waits for the status call like the others.
  • Use the sandbox everywhere. Make sure search, booking, cancellation and admin tools all switch to sandbox keys together. A flow that searches in sandbox and books in production is an expensive mistake.
  • Infants need care. We send an infant as a child aged 0. ETG's order record showed the right guest counts but no age on that line, so check what your vouchers print.
  • Fill in operations contacts early. ETG needs a contact email and phone on every booking. Empty settings in production will block go-live.

Build it yourself or use a certified platform?

Building the integration yourself makes sense if you have developers and want full control of the booking flow. Plan for several weeks of work, the certification review, and maintenance when the API changes. Our travel API integration guide covers the same steps for other suppliers if you plan to connect more than one.

If you would rather sell RateHawk hotels without writing this code, Travora Hub's RateHawk integration already runs the flow above. You keep your own RateHawk account and contract, connect your keys in the dashboard and set your markup. You can add Hotelbeds, WebBeds or flights from PKFARE on the same site. The hotel supplier comparison helps if you are still choosing.

Frequently asked questions

Which RateHawk API version should I use in 2027?

Build on ETG API v3, the B2B API under /api/b2b/v3/. It covers search, prebook, booking, status, vouchers and cancellation in one API.

Is there a RateHawk API sandbox?

Yes. ETG issues sandbox keys for api-sandbox.worldota.net once your account is approved. You build and run all the certification bookings there before you get production keys.

Is the RateHawk API free?

RateHawk says agency registration has no fees, and you pay for hotels at net or earn commission. API access needs a signed agreement, so confirm any commercial terms with your account manager.

How long does RateHawk API certification take?

ETG puts it at about 14 to 30 days. It goes faster when your checklist is complete, all test bookings are done and your server IPs are ready.

Do I need webhooks for RateHawk bookings?

No. Polling the booking status endpoint every few seconds until it returns a final status is accepted. Webhooks are an option you can tell ETG about in the checklist.

Can I call the RateHawk API from the browser?

No. Call it only from your server. Your keys must stay secret, and production keys work only from the IP addresses ETG has whitelisted.

To see this booking flow from the guest's side, try a search in the live demo and follow it through to the voucher.

Related guides

Built for travel agencies

Apply now — launch your own booking platform