Launch

Certification test scenarios

Before your integration takes live bookings, run these scenarios against the sandbox and send us the evidence. We review it, walk through anything unclear with you, and confirm when you're cleared for production.

How certification works

Get sandbox access. Email support@roaveagents.com for a sandbox key and base URL. Tell us which products you'll sell.
Work through the scenarios for everything you sell — the groups below say which apply. There are 56 in total; most integrations need about half.
Collect the evidence for each scenario (below) and send it in one email, listed by scenario ID.
Review. We check the evidence and arrange a call if there's anything we'd like to see live.
Sign-off. We confirm in writing that you're cleared for production, and your agency admin creates the production key.

What to send for each scenario

IDs: the searchId, quote ID, bookingId and orderRef involved.
Request and response logs with timestamps, and the Idempotency-Key for booking, cancel and pay calls. Remove the API key from logs.
Screenshots where the scenario is about what the traveller sees: checkout, confirmation, voucher, cancellation.
Handling code for scenarios the sandbox can't trigger on demand — sold out, price change, pending confirmation, manual review. A short excerpt showing the branch is enough; we may ask you to walk us through it.

Keys and requests

Required for every integration

ID	Scenario	Passes when
A-01	Authenticated call Call `GET /search/capabilities` with your sandbox key in `X-API-Key`.	`200` with `productTypes`. The key is read from server-side configuration, never shipped to a browser or app.
A-02	Rejected key Send a request with a deliberately wrong key.	Your system logs `401 unauthorized`, alerts, and does not retry in a loop.
A-03	Validation errors Send a search with an extra field, e.g. `"guestCount": 2`.	`400 validation_error` is caught; `details` is logged.
A-04	Rate limiting Exceed 30 searches in a minute, or show the handling code.	On `429` you wait for `Retry-After` before retrying. No request storm.
A-05	Timeouts Show your client configuration.	30 s for search and price-check; 120 s for booking, cancellation and pay.

Hotel search

Required if you sell hotels

ID	Scenario	Passes when
S-01	City search from autocomplete Type a city, pick it from `GET /catalog/suggest`, search with `destinationCityRegionId`.	The search sends region IDs, not free text. Results render.
S-02	Single-hotel search Pick a hotel from suggest and search with `hotelId`.	Only that hotel is returned.
S-03	Two rooms with children Room 1: 2 adults. Room 2: 1 adult, children aged 4 and 9.	`occupancy` has two entries and every child age.
S-04	Results while filling Read results straight after the search; poll while `partial`.	Results show before the search completes; polling stops at `completed`/`failed` or 90 s; a rise in `lateArrivals` re-reads page one.
S-05	Paging Load a second page of results.	Uses `meta.nextCursor`; no second search is created.
S-06	Rate sheet Open a hotel from the listing.	One `POST /search/:id/hotels/:productId/rates` call, only when the hotel is opened.
S-07	Wallet currency Show the search body.	`currency` is your wallet currency; `residency` is the lead guest's passport country.
S-08	Expired search Leave a search idle for 21 minutes, then open a hotel.	`410 search_expired` leads to a fresh search, not an error page.

Price-check and checkout

Required if you sell hotels

ID	Scenario	Passes when
P-01	Unchanged price Price-check a rate and book.	One price-check per checkout; booking follows within 10 minutes.
P-02	Price or policy change Show the handling code.	Old and new price/terms are shown; `changesAcknowledged: true` is sent only after the traveller accepts.
P-03	Sold out Show the handling code for `409 rate_unavailable`.	The traveller is told the room sold out and sent back to a refreshed rate sheet.
P-04	Stale price-check Price-check, wait 11 minutes, then book.	`409 quote_not_price_checked` triggers a new price-check, then the booking.
P-05	Mandatory checkout information Screenshot your checkout for a rate that has rate comments and taxes payable at the hotel.	Total, cancellation terms (deadlines unaltered), `excludedTaxes` labelled as payable at the hotel, and `rateComments` are all visible before confirmation.
P-06	Package rates Show how rows with `summary.isPackage: true` are handled.	Hidden unless sold inside a package; `packageRateAcknowledged` is never sent otherwise.

Hotel booking

Required if you sell hotels

ID	Scenario	Passes when
B-01	Simple booking Refundable rate, 1 room, 2 adults, `paymentMethod: "credit"`.	`confirmed`. `bookingId` and `orderRef` are stored on your order.
B-02	Multi-room booking Book scenario S-03.	Travellers grouped by `roomIndex`; children sent with `type: "child"` and their searched ages. `confirmed`.
B-03	Manifest mismatch Book S-03 with one child missing.	`400 traveler_manifest_mismatch` is shown as a fixable form error.
B-04	Timeout retry Force a client timeout on `POST /bookings`, then retry.	The retry reuses the same `Idempotency-Key` and returns the same booking. Exactly one booking exists.
B-05	Double submit Click “Book” twice quickly.	One booking. A `409 idempotency_in_progress`, if seen, is waited out — not surfaced as a failure.
B-06	Pending confirmation Show the handling code for `supplier_pending`.	Polls `refresh-status` every 15 s for up to 10 minutes, then keeps monitoring and tells the traveller confirmation is on its way.
B-07	Declined booking Show the handling code for `201` with `state: "failed"`.	Treated as not booked; price-check again and retry with a new key.
B-08	Manual review Show the handling code for `manual_review`.	No replacement booking is created; the traveller sees a pending status.
B-09	Lead contact and names Show the traveller form.	Real names required for every guest; lead email and phone always sent; no placeholders. A `title` is collected for every guest and sent when the rate has `requiresGuestTitle: true`; `400 traveler_title_required` is shown as a fixable form error.
B-10	Insufficient credit Show the handling code for `402 credit_limit_exceeded`.	A clear message to your staff; the traveller isn't shown a generic error.
B-11	Hotel confirmation number Read `GET /bookings/:id` after B-01.	`hotelConfirmationNumber` is shown when present and re-read later when missing.

Holds

Required if you offer pay-later

ID	Scenario	Passes when
H-01	Hold then pay Book a refundable rate with `hold: true`, then `POST /bookings/:id/pay`.	`held` with a `paymentDeadline`, then `confirmed`.
H-02	Hold then release Hold, then cancel.	`no_refund_due`; nothing charged.
H-03	Ineligible hold Try to hold a non-refundable rate.	`400 hold_not_eligible`; the option isn't offered for such rates.

Cancellations and vouchers

Required for every product you sell

ID	Scenario	Passes when
C-01	Free cancellation Cancel B-01 inside its free window.	The cost shown beforehand is zero; outcome is `refunded` or `no_refund_due`.
C-02	Penalty shown first Screenshot cancelling a booking whose penalty has started, or a rate with `refundable: false`.	The penalty from `cancellationPolicy` is shown, with its time zone, before the user confirms.
C-03	Cancel retry Force a timeout on cancel and retry.	Same `Idempotency-Key`; one cancellation.
C-04	Invalid cancel Cancel an already cancelled booking.	`409 booking_invalid_transition` handled gracefully.
V-01	Voucher delivered Fetch the voucher for B-01 (data or document).	The traveller receives a voucher with the hotel confirmation number, cancellation terms, taxes payable at the hotel and important information.
V-02	Voucher without prices Fetch `voucher/document?prices=without`.	No prices shown to the end client.

Flights

Required if you sell flights

ID	Scenario	Passes when
F-01	One-way 1 adult, economy.	Itinerary with segments, baggage and change rules shown before checkout.
F-02	Return with a child 2 adults and a child aged 7; international.	Every passenger sent with title, date of birth, gender and passport; child as `type: "child", age: 7`. `confirmed` (ticketed), or `supplier_pending` polled to `confirmed` and not shown as ticketed before then. The airline reference is shown from the line item's `supplierConfirmationId`, and ticket numbers from `details.tickets` when present.
F-03	Multi-city Three `slices`.	All legs displayed and booked.
F-04	Expired fare Show the handling code for `409 rate_unavailable` at price-check.	The traveller is sent back to fresh results.
F-05	Name and passport validation Show the passenger form.	Names are validated against the passport, and passports expiring within 6 months of travel are caught, before booking. `400 travel_documents_required` is shown as a fixable form error.
F-06	Cancel Cancel F-01.	Fare conditions shown first; outcome displayed from `refund.status`. A `manual_review` outcome is shown as in progress, and not cancelled again.

Activities

Required if you sell activities

ID	Scenario	Passes when
AC-01	Search by destination code Look up the code with `GET /destinations?productType=activity`, then search.	Search sends `destinationCode`; options grouped by activity.
AC-02	Ages Book for 2 adults and a child aged 10.	Every traveller carries an `age` — adults 18 or over; lead email, phone and `title` sent.
AC-03	Booking questions Book an activity whose price-check returns `bookingQuestions`, or show the handling code.	Every mandatory question is asked and sent in `bookingAnswers`.
AC-04	Operator voucher Deliver AC-02's voucher.	`details.supplierVouchers` reaches the traveller unchanged — not replaced by your own design.
AC-05	Details before booking Screenshot the activity page.	Important information and redemption instructions are shown before checkout.

Transfers

Required if you sell transfers

ID	Scenario	Passes when
T-01	Airport to hotel Search `airport` → `hotel` for 2 adults and a child; book.	The arriving or departing flight's `carrierName`, `flightNumber` (≤7 characters) and `flightTime` sent when `requiresFlightDetails` is true; lead `title` always sent.
T-02	Return transfer Add `returnAt` to T-01.	Both legs shown and booked: a row with `tripType: "round"` as one booking covering both, otherwise one row and one booking per direction.
T-03	Flight number validation Enter `EK 0003X` in your form.	Rejected or normalised by your form before the API is called.
T-04	Pickup-time notice Book a transfer with `mustCheckPickupTime: true`, or show the handling code.	The reconfirmation notice, link and hours appear before booking and on the voucher.
T-05	Operator voucher Deliver T-01's voucher.	`details.supplierVouchers` and pickup instructions reach the traveller unchanged.
T-06	Capacity Search for more passengers than a vehicle holds.	Options with `maxPax` or `luggageAllowance` below the party aren't offered.

After sign-off

Tell us your go-live date so our team can keep an eye on your first live bookings.
Re-run the relevant scenarios whenever you change checkout, traveller forms, vouchers or your booking retry logic, and let us know about major changes.
New products (say, adding transfers later) need their own group signed off before you sell them.