Introduction

Cloudbeds PMS is designed to streamline financial operations, providing a robust suite of payment capabilities.

In terms of API payment capabilities, our PMS offers several options for external partner integrations:

With Cloudbeds SDK
1. Payments
2. Storing card on file
Pay-By-Link
1. Pre-authorisation for incidentals
2. Payments
Stripe tokens
1. Reservation deposit / pre-payment upon booking creation via the API
2. Storing card on file for an existing reservation
Record a payment processed externally

Initial configuration

To see the property currency and time zone use getHotelDetails. (*)
To pull which payment methods are allowed for the property account, use getPaymentMethods.
To retrieve which payment gateway the property uses and whether Pay-by-Link is enabled for the property, use getPaymentsCapabilities
Currently, Cloudbeds supports the payment gateways listed in this article. The capabilities described in this Blueprint are related to the supported payment gateways.
For options with non-supported payment gateways, review this Payment by booking engine redirection blueprint.

Ingest card details via Cloudbeds SDK & process payments

Introduction

The Cloudbeds Payment SDK is a powerful tool designed to simplify the integration of payment processing functionality into your applications or websites.

The SDK is only available if the property has a payment gateway integrated with Cloudbeds.

Benefits of Cloudbeds payment SDK

🚀 Easy Integration: Drop-in web component that works with any framework
🌐 Universal Compatibility: Works with vanilla HTML, Vue, Angular, etc.
🎨 Customizable: Full theming support and customizable styling
🔒 PCI Compliant: Secure tokenization with industry-standard security
🌍 Internationalization: Multi-language support

Main features

Provides a component to render a payment form with support for all implemented payment methods and providers.
Renders the necessary billing fields based on property configurations.
Displays only the available payment methods for the specific property.
Manages 3DS and other external redirection business logic.
The payment methods are tokenised and, therefore, allows partners to be out of scope for PCI compliance.

Look and feel

Review our Payment SDK Demo to understand how it works:
https://unpkg.com/@cloudbeds/[email protected]/demo/index.html

The payment ID generated in the example page is not valid for additional requests to Cloudbeds API.

If you don’t have access to a payment gateway demo account, we can add a test mode gateway account to your Cloudbeds partner account that can be used for testing. Simply email [email protected] to request it.

Use cases

Payments
Storing card on file

For example:

Charge a deposit to an existing reservation
Pay for an upsell item/service using a previously submitted payment method.
Complete a payment for the guest's stay
Capture guest payment details as part of a pre-check-in form to be used for incidentals

Supported payment methods

Credit/debit card in conjunction with any supported payment gateway.
Cloudbeds Payments also supports the following payment methods:
- Google /Apple pay
- Affirm [US and CA properties]
- Oxxo [Mexican properties]

How to Implement Cloudbeds SDK

Authentication

To make use of CB Pay SDK, a token is required. The token will contain the information that the SDK requires to initialize the form for the guest to send a secure payment.

Contact [email protected], providing your property ID and a short description of your use case to request the token.

This token is only valid for the SDK. Additional calls to Cloudbeds API endpoints such as /postCreditCard or postCharge use Cloudbeds regular API authentication.

N.B.: The SDK is only available if the property has a payment gateway integrated with Cloudbeds. You can call /[getPaymentsCapabilities](get_getpaymentscapabilities-2) to retrieve what payment gateway is connected with Cloudbeds.

Documentation

Documentation: https://www.npmjs.com/package/@cloudbeds/payment-element-webcomponent

Integration flow and capabilities

As a partner who would like to capture payment methods/card details via our SDK or process payments, the first step is to embed our payment SDK in your website/app, according to our documentation.
Once the user reaches the payment step in your app/website, they need to be directed to the section where the Cloudbeds SDK is embedded for their payment details to be captured.

The amount can be hard-coded in the HTML form or set from a JavaScript variable, as explained in the Setting Amount Dynamically section of our Documentation.

The SDK will perform the 3DS (3-D Secure) validation on the entered card details.

Upon entering the payment details, an event is triggered as detailed in the Event Handlers section of our Documentation.
This event will include the paymentMethodId required for any subsequent calls.
After the on-submit event is triggered with the PaymentMethodId, the following actions may be performed via the integration:
1. Add a credit card to the reservation (credit card on file)[mandatory]:
  Use postCreditCard with the PaymentMethodId returned by the SDK to store a credit card in the reservation, regardless of the gateway connected. It is not designed to accept raw credit card data.
  This credit card can be used for payment processing in Cloudbeds.
  Use the returnUrl to specify the URL where the guest is redirected after completing the 3DS authentication process, if required at this step.
2. Process a payment to a reservation, group, house account or accounts receivable ledger:
  Use postCharge to process a payment. Here are the supported options:
  - Process a payment to a reservation, group, house account or accounts receivable ledger.
    - Use getReservations, getGroups, accounts-receivable-ledgers and getHouseAccountList to retrieve the ID corresponding to each reservation, group… object
    - The amount and currency to be charged need to be included in the request, so partial and total payments are supported.
    - Deposits are supported and should be flagged by passing the isDeposit parameter.
  Use the returnUrl to specify the URL where the guest is redirected after completing the 3DS authentication process, if required at this step

Refunds cannot be processed via the API and need to be manually completed in Cloudbeds.'''

Pay-by-link

Authentication

The pay-by-link endpoints follow the regular API authentication methods:
https://developers.cloudbeds.com/docs/authentication-1

Integration flow and capabilities

If the property uses the pay-by-link functionality as returned in the getPaymentsCapabilities response, you can send an API request to generate a secure, unique payment link for a specific payment to be completed by the guest.
This functionality is only supported for properties that use CB PAYCloudbeds Paayments gateway ("cloudbedsPayments": true & "payByLink": true)

{
    "success": true,
    "data": {
        "cloudbedsPayments": true,
        "terminal": false,
        "tapToPay": false,
        "gateway": "StripePlatformGateway",
        "payByLink": true
    }
}

The link is returned via the API and your integration would need to send it to the guest via email, SMS, messaging apps or any other means. Cloudbeds will not handle sending the payment link to the guest.
Once received, the guest clicks the link, which directs them to a secure payment page. They can then enter their payment details (e.g., credit card information) and complete the transaction.
The pay by link is not intended to allow adding cards on file, only charges or authorizes on a brand new card each time

How to generate the payment link?

Send a request to POST/ payments/v2/pay-by-link.
- The supported objects are confirmation_number (Cloudbeds reservationID), group_profile and house_account.
- It is required to add an amount in the paid field and a description. The description will be added as a note when the payment is posted in Cloudbeds.
- Optionally, an expiry date can be set in expires_after.
- Even if a folio_id parameter is available, our API does not support multi folio currently and the payment will be posted to the main folio.
- When auth_payment is set as false, it collects a payment immediately. If true, it runs an authorization in the card.

Payment link request example

curl --location 'https://api.cloudbeds.com/payments/v2/pay-by-link' \
--header 'X-Property-Id: 200934' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer ***' \
--header 'Cookie: acessa_session=cdaae4119c1a73bcf06de213032f5048e34dc15a; acessa_session_enabled=1' \
--data '
{
  "inventoryObject": {
    "type": "confirmation_number",
    "id": "8119499944899"
  },
  "paid": 100,
  "description": "Pay-by-link",
  "propertyId": "200934",
  "expires_after": 7,
  "auth_payment": false
}
'

Pre-authorization request example

curl --location 'https://api.cloudbeds.com/payments/v2/pay-by-link' \
--header 'X-Property-Id: 200934' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer ***' \
--data '
{
  "inventoryObject": {
    "type": "confirmation_number",
    "id": "7955965085964"
  },
  "paid": 5,
  "description": "Payment",
  "propertyId": "200934",
  "expires_after": 7,
  "auth_payment": true
}
'

In the response to the /pay-by-link request, you get the url, the id to check the link status and the link expiration date.
This link would need to be sent by your application via email, messaging or any other method, so the guest can complete the payment.

Response example

{
    "url": "https://pay-by-link.cloudbeds.com/#/payment/bSefFM.d45bc08c-d747-41ab-bd0f-fe79203648c8",
    "id": "d45bc08c-d747-41ab-bd0f-fe79203648c8",
    "expires_at": "2025-10-27T10:47:31.032788332"
}

When accessing the link to complete the pre-authorization or the payment, the guest can complete their payment and it will be automatically posted in the reservation folio:

The credit card will be added in the Credit cards tab.

In the case of a pre-authorization, the credit card will be recorded in the reservation and there will be an option to capture or void the payment in Cloudbeds UI.
Capturing or voiding a pre-authorization is not possible via the API. The user will need to complete this action manually in Cloudbeds.
If no action is performed with the pre-authorization, it will auto-expire within 30 days (7 days for properties in Mexico).

How to check the payment link status?

You can use GET/ payments/v2/pay-by-link/uuid to enquire the pay-by-link status, using the UUID returned in POST/ payments/v2/pay-by-link
- The payByLinkStatus may be sent, viewed, paid, expired, cancelled, or 3DSProcessing
  Sent status means that the link has been created and ready to use, but it does not imply that it has been sent to the guest.
- readyForPayment will be true when the link is in sent & viewed status
- The cost object indicates the amount the link is for and you should review the paid boolean parameter or the payByLinkStatus: paid parameters to confirm that the payment has been processed.
- Upon successful payment, the payment will be posted in the reservation main folio.
```
* * curl --location '[https://api.cloudbeds.com/payments/v2/pay-by-link/3c6c757a-e6a7-4251-af17-735c75bc962c](https://api.cloudbeds.com/payments/v2/pay-by-link/3c6c757a-e6a7-4251-af17-735c75bc962c)' \  
    --header 'X-Property-Id: 200934' \  
    --header 'accept: application/json' \  
    --header 'Content-Type: application/json' \  
    --header 'Authorization: Bearer ***' \
```
  In the case of a pre-authorization, the captureMethod will indicate it is an auth. The parameter is charge for completed payments.

Basic integration - record a payment in the folio

For any payments processed externally, such as via a not supported payment payment gateway or a terminal, Cloudbeds API allows posting the payment record into the reservation folio:

Use the call getPaymentMethods to get the property-enabled payment methods. Optionally, you can create a custom payment method via postCustomPaymentMethod to record the payments to this method.
Call /getReservation to retrieve the reservation outstanding balance.
Once the payment is processed, record the payment with /postPayment in the reservation folio. It is highly recommend to add a note in the description parameter with the payment gateway transaction identifier or the last 4 digits of the card for the user to be able to track the payment in the payment gateway.
Use postVoidPayment to void any payments.

Stripe tokens

If a property uses Stripe and it is integrated as a payment gateway in Cloudbeds as returned in the getPaymentsCapabilities endpoint, the following use cases are available:

Pass the Stripe token with postReservation
https://developers.cloudbeds.com/docs/pass-stripe-tokens-to-cloudbeds
It is possible to add a tokenised credit card for further reuse and also add a processed payment to the reservation.
Send a Stripe token to an existing reservation
This can be achieved via the postCreditCard endpoint when passing a cardToken, which must be filled with a Stripe Customer ID.
In this case, it is only possible to post the Stripe token to the reservation and any processing with that token needs to be done manually in Cloudbeds.

Payment by Booking Engine Redirection

The Cloudbeds Booking Engine Plus allows the integration of a custom payment gateway or support gift card payments, providing greater flexibility in managing their payment options.

This flow is recommended to integrate payment gateways not supported by Cloudbeds and involves a redirection from the booking engine to complete the payment.

Documentation

Limitations & FAQ

What's the paymentMethodId parameter?

The paymentMethodId is the tokenised payment method UUID. It is required to post a credit card on file via postCreditCard or to process a payment with postCharge. It will also be required to post authorizations once the corresponding endpoint is released.
As detailed in this article, it can be obtained via Cloudbeds SDK or the postRawCreditCard endpont (ETA: Q1 2026).
The only case when it is not mandatory for postCreditCard is to add a card on file by passing a Stripe token.
Does Cloudbeds SDK or pay-by-link fall within the PCI DSS scope?

Partners remain within PCI DSS scope up to the moment they submit raw cardholder data to Cloudbeds. Cloudbeds provides two PCI DSS–compliant card-data ingestion points:
1. Cloudbeds SDK
2. The /postRawCreditCard endpoint (upcoming)
Both are designed exclusively to securely collect and tokenize cardholder data. Upon successful tokenization, Cloudbeds generates a PaymentMethodId. Once the PaymentMethodId has been created, all subsequent API calls that reference this identifier are out of PCI DSS scope, as they operate solely on tokens and do not involve raw cardholder data.

postCreditCard, postCharge , pay-by-link and the future postAuthorization & /postRawCreditCard endpoint do not fall within the PCI DSS scope, as they always involve tokenized card details.
Is it possible to process payments with cards on file?
We don’t have the ability to “get available cards” on file. Payment processing is only possible if a PaymentMethodId retrieved via Cloudbeds SDK is available.
The possibility of retrieving cards on file is not in our current roadmap.
Can you accept raw credit card details? We are planning to implement a postRawCreditCard endpoint in Q1 2026. This is the PCI compliant ingestion and tokenization point for partners that do not want to adopt our SDK. Via this endpoint, you can submit raw credit card details to Cloudbeds. The response will contain a paymentMethodID that can be further used on calls to postCreditCard, postCharge and /postAuthorization (ETA: Q1 2026).
Do you support pre-authorizations using a UUID returned by the SDK?
We are planning to release a /postAuthorization endpoint in Q1 2026 that will support this functionality.
Do you support processing payments to a specific folio? This is not supported at present. Payments will be allocated to the default folio.
Can I post a refund/void via the API after a pay-by-link or /postCharge payment?
Refunds/voids would need to be completely manually in Cloudbeds.
Do you support posting Virtual Credit Cards (VCCs) into a reservation?
Once the /postRawCreditCard is released in Q1 2026, new Cloudbeds properties will have the ability to import Virtual Credit Cards (VCCs) from a previous PMS and post them into the Cloudbeds reservation.
The flow will involve tokenizing the card details via Virtual Credit Cards (VCCs) to retrieve the paymentMethodId and then use postCreditCard to add the VCC into the reservations.