Introduction

Welcome to the Roam API.

This is built on modern REST principles and designed to give developers a clear, consistent, and flexible way to embed payment and financial workflows directly into their applications.

The unified API provides access to a broad suite of capabilities, including booking management, multi-currency invoicing, and payment reconciliation—all through a single integration layer. A secure sandbox environment is available so you can build and test confidently using test data before going live in production.

API Endpoints

Two APIs are provided to support your booking and payment flows. These must be used in conjunction and form part of a single integration.

Booking API

Create and manage bookings and their associated metadata.

Environment	API Endpoint
Sandbox	https://rest.synatic.com/roamdev/booking
Production	https://rest.synatic.com/roamprod/booking

Charge API

Create and manage invoices and payment schedules related to a booking.

Environment	API Endpoint
Sandbox	https://rest.synatic.com/roamdev/charge
Production	https://rest.synatic.com/roamprod/charge

Authentication

Access to Roam endpoints is authenticated using API keys. Each endpoint is accessed independently and uses its own key. Keys are issued per environment and are managed by the Roam technical support team.

Request Header

Include your key in the request headers:

X-API-KEY: <your-key>

Choosing the Right Endpoint

Roam separates booking management from financial transaction management. While both APIs are typically used together, each serves a distinct purpose within the booking lifecycle.

Use the Booking API to create and manage the operational context of a booking. This includes traveller information, travel dates, quote references, consultants, itinerary links, booking status, and payment visibility. Booking services also provide access to related charges and payments within a booking.

• CreateBooking — Create a new booking with the provided details.

• UpdateBooking — Update an existing booking with the provided details.

• GetBookingDetails — Retrieve details for a specific booking.

• GetCharges — Retrieve all charges related to a specific booking.

• GetPayments — Retrieve all payments related to a specific booking.

Use the Charge API to manage the financial structure of a booking. This includes creating and updating deposits, balances, refunds, payment schedules, due dates, currencies, FX conversion details, and supplier payout information.

• CreateCharge — Create a new charge for the specified booking.

• UpdateCharge — Update an existing charge with the provided details.

• GetChargeDetails — Retrieve details for a specific charge.

In a typical integration flow, a booking is created first through the Booking API. One or more charges are then created against that booking through the Charge API. Travellers can then view and pay against the consolidated booking through a single booking summary link.

This separation allows your booking and financial data to evolve independently while remaining linked as part of a single flow.

Event Monitoring

Roam uses webhook notifications to provide real-time updates as bookings, charges, and payments progress through their lifecycle. These allow your application to respond automatically to operational and financial changes without the need for continuous polling. Use the Events documentation to configure and manage event notifications within your integration.

Typical Booking Lifecycle

This section describes a common end-to-end flow for a booking within Roam. Use it as a how-to guide to get started.

Create a Booking

Create a booking record with CreateBooking to capture key information such as passenger details, travel dates, consultant name, and quote reference. This is the parent object that all subsequent charge and payment records within the booking will relate to.

Choose the transaction currency that the traveller will pay in by setting the TXN_Currency parameter. Add a link to a digital itinerary, which will display as a clickable button to travellers, through Itinerary_Link.

Create Charges for the Booking

Use CreateCharge to define the payment schedule within a booking. The schedule is loaded through individual charges, which can be likened to invoices raised from an accounting system. Charges are represented as deposits or balances for an amount on a given date in a given base currency.

Once a charge has been added, the BSE_Amount is converted to a TXN_Total at a set exchange rate, and this amount rolls up to the booking.

Presenting the Booking for Payment

Share details and costs of a booking with a traveller through the Booking_Summary_Link. This single link will remain the same for the lifetime of a booking, and from here travellers can view quotes, make payments, and track their transaction history.

When ready to take payment, use UpdateBooking to set Proceeding from false to true. This updates the booking status from “Quote” to “Proceeding” and opens the payment gateway.

Once the first payment has been received, the Booking will be “Confirmed”. This guarantees the exchange rates for all charges that have already been created, essentially locking in the amount that a traveller will pay in their TXN_Currency irrespective of market movement.

Understanding Validity Dates

When a booking is created, the Validity_Date parameter will be set in the future, dependent on account settings, but is typically 7 days from the creation date. This is the period during which quoted exchange rates in a booking are valid. Rates are left unchanged for this extended period to give travellers time to review a quote without it changing day-to-day due to market movements. A booking will only be “Confirmed” if a payment is received against it while rates are valid.

In order to take this payment, Proceeding can only be set to true if a booking has a Validity_Date greater than or equal to today. If not, use UpdateBooking to set a combination of Refresh_Rates and Force_Rate_Refresh. This will refresh the underlying exchange rates in all unbooked charges and move the date into the future.

Refer to potential refresh options below. Note that in all cases Proceeding can be set to true at the same time as these fields in a single call.

Validity Date	Refresh_Rates	Force_Rate_Refresh	Description
In past	true	false	Rates refreshed and validity date moved to the future
In future	true	false	Rates will not refresh and validity date will not update as booking is already valid
In future	true	true	Even though booking is valid, rates will be forced to refresh and validity date updated to the latest possible date. Use this if wanting to give a traveller more time to consider a quote.
Either	false	true	No action taken as rate refresh trigger not set

Adding an Amendment Charge

To add an amendment charge, set Proceeding to false. If the booking is invalid, this will automatically refresh rates, but will not affect the exchange rate for charges that already have “Booked” status.

Once your changes have been made, set Proceeding to true to confirm the details and reopen the gateway.

Booking Statuses

As a booking progresses through its lifecycle, the values of the Proceeding and Confirmed parameters determine its status.

Status	Proceeding	Confirmed	Description
Quote	false	false	Charges can be added and details updated. Travellers cannot make payment as the gateway is closed.
Proceeding	true	false	No charges can be added or updated. Travellers can make payment through the gateway.
Confirmed	true	true	Payment has been received and the transaction currency cannot be changed. Charge exchange rates have been guaranteed. Travellers can make payments through the gateway.
Amending	false	true	The confirmed booking has been reopened for amendments. Travellers cannot make payment as the gateway is closed.

Charge Statuses

As a charge progresses through its lifecycle, the values of the Booked, Completed, and Paid_Out parameters determine its status. To make any changes to a charge, Proceeding must be set to false at the booking level.

Status	Booked	Completed	Paid_Out	Description
Open	false	false	false	Any charge details can be updated.
Booked	true	false	false	Exchange rates have been booked in. Due date cannot be updated, but all other details can.
Completed	true	true	false	The FX conversion from transaction to base currency has been completed. Only supplier payment details can be updated.

Monitoring Bookings & Charges

Once created, field values on bookings and charges can be updated by Roam as your booking progresses.

Configure webhook notifications for booking and charge events to be notified when this occurs.

Reconciling Payments

Payments are allocated to a booking as they are received. Note that payments are always denominated in the transaction currency of a booking and will be applied to a charge based on the due date of that charge.

Configure webhook notifications for payment events to be notified when this occurs.

Key Parameters

Understanding these parameters is central to managing bookings through Roam.

Booking Parameters

• TXN_Currency — The currency, set at booking level, that a traveller will use to make inward payment to Roam. If available, this should be set to the preferred currency of the traveller’s region. Supported values: USD, AUD, GBP, EUR, CAD, SGD, AED.

• Quote_Reference — The internal reference number of the booking from your CRM. This must be unique across the Roam platform and will be used in payout reports for ease of tracking.

• Consultant_Email — The email address of the sales consultant managing this booking. This is used in authentication flows and must match the value stored on the Roam platform.

Charge Parameters

• BSE_Currency — The currency, set at charge level, that your business raises invoices in. These typically align to the underlying currencies of the services being sold. Roam will pay out in this currency to your nominated bank account. Supported values: ZAR, USD, EUR, GBP.

• Due_Date — The due date displayed to travellers for when a charge is due to be paid. If funds are received before this date, the charge will only be completed on the due date.

Making a Test Payment

The following flow can be used to test traveller payments within the sandbox environment.

1. Create a test booking and add a charge

   Use CreateBooking to create a booking using dummy details.

   Then use CreateCharge to add at least one charge with a near-term due date to the booking. This creates the payable amount presented to the traveller during checkout.

2. Run UpdateBooking and set Proceeding = true

   This changes the booking status from “Quote” to “Proceeding” and opens the payment gateway. Until this update is made, travellers will not be able to access payment functionality.

3. Open the Booking_Summary_Link

   This is the traveller-facing booking summary page returned from the booking response and is the same link shared with travellers or embedded within your application.

4. Click the “Pay Now” button

   This will redirect the traveller to the payment gateway where payment can be made by card or bank transfer.

   For testing, only card payments will be reconciled to a booking.

5. Complete the checkout flow

   The email address displayed during checkout is taken from Client_Email.

   For testing purposes, this should be set to an internal email address before initiating payment. We recommend populating Client_Email during CreateBooking or UpdateBooking.

6. Use the following test card details

   Field	Value
   Card Number	4242 4242 4242 4242
   Expiry Date	Any future date
   CVC	Any 3 digits

7. Confirm successful payment

   Once payment is complete:

   • A success screen will be shown in the checkout flow

   • A confirmation email will be sent to the Client_Email

   • A payment event notification will be sent to your webhook endpoint

   • The booking will be confirmed and a payment will be reconciled against the booking

   • The Booking_Summary_Link will reflect the reconciled payment after page refresh

Error Codes

All API errors returned include a standardised error code, message and description to help identify and resolve issues consistently across all services.

Code	Message	Description
ERR001	Account not found	The account id listed as a parameter in the request is not related to an account in Roam.
ERR002	Consultant not found	The consultant email address listed as a parameter in the request is not related to this account in Roam.
ERR003	Booking not found	The booking id listed as a parameter in the request is not related to this account in Roam.
ERR004	Charge not found	The charge id listed as a parameter in the request is not related to this account in Roam.
ERR005	Booking already exists	The booking Quote Reference listed as a parameter in the request needs to be unique and is already related to another booking in Roam.
ERR006	TXN currency update with confirmed booking	The TXN currency cannot be changed as booking has been confirmed.
ERR007	Travel start date in the past	The travel start date cannot be in the past when ticking proceeding.
ERR008	Travel end date before travel start date	The travel end date must be later than travel start date when ticking proceeding.
ERR009	Client name incomplete	At least client first or last name must be completed when ticking proceeding.
ERR010	Passengers incomplete	At least one passenger must be added to the booking.
ERR011	Itinerary link format	The itinerary link is not a valid URL.
ERR012	TXN currency selected is not available to this account	The transaction currency listed as a parameter in the request is not supported for this account in Roam.
ERR013	Refresh rates with proceeding	The booking FX rates cannot be refreshed as it is marked as proceeding.
ERR014	Proceeding with invalid rates	The booking cannot be marked as proceeding as FX rates are invalid.
ERR015	Charge due date in the past	The charge due date cannot be set in the past.
ERR016	Negative charge type mismatch	The charge type can only be Refund or Credit when the amount is negative.
ERR017	Refund without spot contract	The refund due date cannot be set more than 7 days in the future.
ERR018	Forward contracts are not available to this account	The charge due date cannot be set more than 7 days in the future as this feature is not supported for this account in Roam.
ERR019	Charge amount zero	The charge amount cannot be zero when creating a charge.
ERR020	Supplier payment without beneficiary	The beneficiary id listed as a parameter in the request is not related to this account in Roam or does not match the BSE currency of the charge.
ERR021	BSE currency selected is not available to this account	The base currency listed as a parameter in the request is not supported for this account in Roam.
ERR022	Charge edit with proceeding	The charge cannot be edited as the booking is marked as proceeding.
ERR023	Charge edit with invalid rates	The charge cannot be edited as booking rates are invalid.
ERR024	Charge booked	The charge due date cannot be edited as it has already been booked in.
ERR025	Supplier assigned	The charge supplier cannot be edited as it has already been assigned for payout.
ERR026	Charge completed	The charge cannot be edited as it has been completed.
ERR027	Charge type not available	The charge type is not available to this account.