Set up custom payment gateways and gift card payments in Booking Engine Plus

Introduction

Cloudbeds Booking Engine Plus can support a custom payment gateway or gift card workflow through custom JavaScript. The custom payment option uses the Booking Engine EventSystem and the Bank Transfer payment option as the base for the custom flow.

The hosted Booking Engine remains the supported checkout environment for custom payment methods. This article explains the setup requirements, what Cloudbeds Support can help with, what remains the responsibility of the payment provider or developer, and how to use premium embeds when a property wants a more immersive website entry experience.

Table of contents

• Who this affects and how
• Requirements and support boundaries
• Use custom payment methods with the Immersive Experience
• Set up a third-party payment gateway or gift card workflow
• Test and troubleshoot a custom payment gateway

Who this affects and how

Custom payment workflows involve both Cloudbeds configuration and third-party development. Use this table to identify which part of the process applies to you.

Requirements and support boundaries

Before implementing a custom payment gateway or gift card workflow, confirm the required Booking Engine settings and who owns each part of the implementation.

• Enable Bank Transfer as a payment option for the Booking Engine in Cloudbeds PMS.
• Use custom JavaScript with the Booking Engine EventSystem to register the custom payment option.
• Only one custom payment gateway can be integrated. The property cannot offer Bank Transfer and a custom payment gateway as separate options at the same time.
• Gift card support requires a custom guest field for the guest to enter the gift card number.
• Custom payment methods are supported only in hosted Booking Engine environments. They are not supported in the full Cloudbeds Booking Engine Immersive Experience 2.0.
• The implementation steps in this article apply only to Booking Engine Plus.

How Cloudbeds Support can assist

Cloudbeds Support can help with the Cloudbeds-side setup needed for your provider to test its implementation. Support can:

• Guide you in creating a test rate plan with a promo code so the payment provider can review the browser console. Use a custom rate of USD 0.50 and make the test rate plan available only for the Booking Engine source.
• Help you add custom scripts supplied by your payment gateway provider to the Booking Engine Customize panel.

For advanced troubleshooting or integration questions, the payment gateway provider must work directly with the Cloudbeds Integrations team. If the provider is not yet a Cloudbeds partner, ask them to apply through the Partner with Cloudbeds page.

Use custom payment methods with the Immersive Experience

Custom payment methods are not supported in the full Cloudbeds Booking Engine Immersive Experience 2.0. If you want to keep the beginning of the booking journey on your property website, use premium embeds as the entry point and complete the booking on the hosted Booking Engine.

You can use premium embeds such as the multi-property, date picker, and accommodation picker widgets on your website. Guests can interact with the supported widget experience on your site, then continue to the Cloudbeds-hosted Booking Engine to complete the reservation and use the custom payment redirect.

Set up a third-party payment gateway or gift card workflow

The custom payment option must be registered through the Booking Engine EventSystem. The setup below covers the Cloudbeds-side event registration and the reservation-created event used by a provider's redirect logic.

Step 1: Add the custom JavaScript to the Customize tab

1. Open the Account Menu and go to Settings > Booking Engine.
2. Click Customize.
3. Add the custom JavaScript to the JavaScript field.
4. Click Save.

The custom JavaScript must subscribe to the on-booking-engine-ready event. This event is dispatched when the Booking Engine is ready to trigger and listen to events. The script must also dispatch the custom-payment-option-change event so the Booking Engine can register the custom payment option.

<script>
window.addEventListener('on-booking-engine-ready', (e) => {
  const { eventSystem } = e.detail;

  eventSystem.dispatchEvent("custom-payment-option-change", {
    id: "%PAYMENT_OPTION_ID%",
    instructions: "Your default text for the instructions goes here.",
    name: "Your default text for the label goes here.",
  });
});
</script>

Step 2: Register the custom payment option with EventSystem

Use eventSystem.dispatchEvent() to dispatch the custom-payment-option-change event with the required payment option details:

• id [string]: Required. The value must have a length greater than 0 and be valid for use as a CSS id. Do not use spaces, semicolons, or special characters that are invalid in CSS selectors. The suggested format is kebab-case. Replace %PAYMENT_OPTION_ID% with the id for the custom payment gateway.
• instructions [string]: Optional. Displays instructions or a description when the guest expands the custom payment option. Use this value as the default text when language-specific text is not customized with CSS.
• name [string]: Required. The value must have a length greater than 0.

After saving the changes, open the hosted Booking Engine and test checkout. The payment step may open in a separate popup or modal instead of appearing inline on the reservation page. The custom payment option must still be registered through the Booking Engine EventSystem.

The following visual shows the hosted payment window with the available payment methods after the guest continues through checkout.

Step 3: Handle the reservation-created event and provider redirect

When a guest makes a reservation using the custom payment option, the reservation is created in Cloudbeds PMS with an e-banking payment method and no payment is collected by Cloudbeds. The provider's custom script can listen for the reservation-created event, use the reservation data, and redirect the guest to the third-party payment gateway to complete payment.

eventSystem.addEventListener('reservation-created', (data) = {
  // Your code to execute after a booking is created...
})

Use the Booking Engine EventSystem for the registration and reservation-created events. Do not rely only on page-specific click listeners, accordion button clicks, or UI selectors to determine whether the custom payment option was selected.

Expand the advanced reference sections below if you need optional label, instruction, icon, or reservation-data details.

html[lang="%LANG%"] [data-id="%PAYMENT_OPTION_ID%-name"]::before {
  content: "Your lang-specific text for the label goes here.";
}

html[lang="%LANG%"] [data-id="%PAYMENT_OPTION_ID%-instructions"]::before {
  content: "Your lang-specific text for the instructions goes here.";
}

// To hide the default SVG icon
[data-id="%PAYMENT_OPTION_ID%-icon"] svg {
  display: none;
}

// To customize the icon by setting it as a background image
[data-id="%PAYMENT_OPTION_ID%-icon"] {
  background-image: url(PAYMENT_OPTION_ICON_URL);
  background-size: cover;
  background-position: center;
  width: 40px;
  height: 40px;
}

interface CreatedReservation {
  booking_id?: `${number}`;
  booking_total?: number;
  checkin_date?: string;
  checkout_date?: string;
  city?: string;
  currency_code?: string;
  hotel_name?: string;
  real_booking_total?: number;
  resRooms?: {
    adults: `${number}`;
    id: `${number}`;
    kids: `${number}`;
    package: `${number}`;
    package_name: string | null;
    rate_id: `${number}`;
    room_total: `${number}`;
    room_type_id: `${number}`;
    room_type_name: string;
    room_type_photos: ({
      TYPE?: string;
      alt: string;
      cropParam: string | null;
      croppedImage: string;
      fullPath: string;
      galleryPath?: string | null;
      id: string;
      imageHeight: string;
      imageWidth: string;
      mime?: string;
      originalName: string;
      ownerId?: string;
      ownerType?: string;
      parentId: string;
      path: string;
      section?: string;
      size?: string;
      thumbPath: string;
      uploadedAt?: string;
      utype?: string;
    } & {
      featured: number;
      featuredPath: string | null;
    })[];
  }[];
  rooms?: Record<string, {="{" adults:="adults:" number;="number;" amount:="amount:" bookedid:="bookedId:" string[];="string[];" kids:="kids:" name:="name:" string;="string;" packageid?:="packageId?:" packagename?:="packageName?:" picture?:="picture?:" price?:="price?:" rateid:="rateId:" roomid:="roomId:" unit?:="unit?:" }="}">;
  state?: string;
  total_tax?: number;
  widget_property?: number;
};</string,>

Test and troubleshoot a custom payment gateway

Use a controlled Booking Engine test flow when your payment provider needs to inspect browser-console behavior or validate its redirect logic. Cloudbeds Support can help with the Cloudbeds-side test setup, but the payment provider remains responsible for custom gateway code and provider-side troubleshooting.

Create a test rate plan for provider troubleshooting

Cloudbeds Support can guide you in creating a temporary rate plan with a promo code for testing. Use a custom rate of USD 0.50 and make the rate plan available only for the Booking Engine source so your payment provider can reproduce the checkout flow and review the browser console.

Expand the issue that matches the behavior you are seeing.

Related articles

Now that you understand the supported custom-payment setup and ownership boundaries, review these resources for broader Booking Engine Plus capabilities and the supported Immersive Experience configuration:

• Cloudbeds Booking Engine Plus - Overview and activation
• Set up and customize Cloudbeds Booking Engine Immersive Experience 2.0