Vacatia API Catalog
/
Cloudbeds API
/
Payment
/
getPayments

Cloudbeds API (v1.2)

Welcome to the documentation for Cloudbeds API Version v1.2! If you are looking to learn how to use the Cloudbeds API to access guest information, reservations, or similar data for your Cloudbeds customers, then you've come to the right place.

In this document you will find all the API methods we provide along with explanations for parameters and response examples.

If you have questions about different implementation steps (e.g. how to implement OAuth 2.0), please refer to our Integrations Portal.

Be sure to subscribe to the monthly Cloudbeds API announcement mailing list to receive information on new additions and improvements to the Cloudbeds API and related developer tools.

Endpoint: https://api.cloudbeds.com/api/v1.2/{method}

HTTPS: Our API requires HTTPS. We'll respond with an appropriate error if you're not using it.

Request Format: HTTP GET, POST and PUT (Content-Type: application/x-www-form-urlencoded)

Response Format: JSON

Response Header: X-Request-ID is added to response headers in all calls to help accelerate support and troubleshooting.

Run in Postman use this link to access our Public collection in Postman.

Download OpenAPI description
cloudbeds.json
cloudbeds.yaml
Languages
Servers
Mock server
https://tbg-api-docs.vacatia.com/_mock/cloudbeds/
https://api.cloudbeds.com/api/v1.2/

Authentication

Operations

Adjustment

Operations

AllotmentBlocks

Operations

AppSettings

Operations

Currency

Operations

CustomFields

Operations

Dashboard

Operations

Emails

Operations

Groups

Operations

Guest

Operations

Hotel

Operations

HouseAccount

Operations

Housekeeping

Operations

Integration

Operations

Invoices

Operations

Item

Operations

Package

Operations

Payment

Operations

getPayments

Request

Get a list of transactions for a reservation/house account/guest, with its respective payment allocation
¹ one of these fields are required ² only if data.isAllocated = true (and includePaymentAllocation = true)

Query
propertyIDstring

Property ID

reservationIDstringrequired

¹ ID for the reservation to be queried.

houseAccountIDstringrequired

¹ ID for the house account to be queried.

guestIDstringrequired

¹ ID for the guest to be queried.

createdFromstring(date-time)

Datetime (lower limit) to be queried. If not sent, and reservationID informed, will use reservation date. In other cases, current date -7 days is used.

createdTostring(date-time)

Datetime (upper limit) to be queried. If not sent, and reservationID informed, will use check-out date. In other cases, current date is used.

includePaymentAllocationboolean

Adds payment allocation to response, when available.

Default false
pageNumberinteger

Page number

Default 1
pageSizeinteger

Page size

Default 100
curl -i -X GET \
  'https://tbg-api-docs.vacatia.com/_mock/cloudbeds/getPayments?createdFrom=2019-08-24T14%3A15%3A22Z&createdTo=2019-08-24T14%3A15%3A22Z&guestID=string&houseAccountID=string&includePaymentAllocation=false&pageNumber=1&pageSize=100&propertyID=string&reservationID=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

dataArray of objects

Transaction list

countinteger

Number of results returned, based on pagination

totalinteger

Total number of results

messagestring or null

To be used in case any error occurs (if success = false). If success = true, it does not exist.

Response
application/json
{
  "success": true,
  "data": [
    { … }
  ],
  "count": 0,
  "total": 0,
  "message": "string"
}

getTransactions

Request

Get a list of transactions for a property, or list of properties, for the date range specified. If no date range or reservation is specified, it will return the transactions for the last 7 days, unless stated otherwise.
Please note that some reservations modification may not be reflected in this timestamp. ### Group account support

Query
propertyIDstring

ID for the properties to be queried (comma-separated, i.e. 37,345,89).
It can be omitted if the API key is single-property, or to get results from all properties on an association.

includeDebitboolean

If the response should include debit transactions

Default true
includeCreditboolean

If the response should include credit transactions

Default true
includeDeletedboolean

If the response should include deleted transactions

Default false
includeChildrenboolean

If the response should include children transactions (requires the parameter transactionIDs)

Default false
reservationIDstring

Reservation Unique Identifier, used to filter transactions result If reservationID is informed, and dates are not, all transactions with the reservationID will be returned.

subReservationIDstring

Sub Reservation Identifier, used to filter transactions result

roomIDstring

Room ID, used to filter transactions result

guestIDstring

Guest ID, used to filter transactions result

houseAccountIDstring

House Account ID, used to filter transactions result

transactionIDsstring

List of transaction IDs to be returned, comma-separated, i.e. 37,345,89.

resultsFromstring(date)

Inferior limit date, used to filter transactions result (posted transaction date)

resultsTostring(date)

Superior limit date, used to filter transactions result (posted transaction date)

modifiedFromstring(date)

Inferior limit date, used to filter transactions result

modifiedTostring(date)

Superior limit date, used to filter transactions result

createdFromstring(date-time)

Inferior limit datetime, used to filter transactions result (creation date of the transaction). If informed, all other dates are ignored (except createdTo). If createdFrom is informed, but createdTo is not, the call will return all results since this datetime. Necessary only if createdTo is sent. If time portion not given, assumes 00:00:00.

createdTostring(date-time)

Superior limit datetime, used to filter transactions result (creation date of the transaction). If informed (together with createdFrom), all other dates are ignored. If time portion not given, assumes 23:59:59.

transactionFilterstring

Transaction filter is used to filter transactions result

Default "simple_transactions,adjustments,adjustments_voids,voids,refunds"
pageNumberinteger

Results page number

Default 1
pageSizeinteger

Results page size. Max = 100

Default 100
sortBystring

Sort response results by field

Enum"transactionDateTime""transactionModifiedDateTime""guestCheckIn""guestCheckOut"
orderBystring

Order response in DESCending or ASCending order, used together with sortBy

Default "desc"
Enum"desc""asc"
curl -i -X GET \
  'https://tbg-api-docs.vacatia.com/_mock/cloudbeds/getTransactions?createdFrom=2019-08-24T14%3A15%3A22Z&createdTo=2019-08-24T14%3A15%3A22Z&guestID=string&houseAccountID=string&includeChildren=false&includeCredit=true&includeDebit=true&includeDeleted=false&modifiedFrom=2019-08-24&modifiedTo=2019-08-24&orderBy=desc&pageNumber=1&pageSize=100&propertyID=string&reservationID=string&resultsFrom=2019-08-24&resultsTo=2019-08-24&roomID=string&sortBy=transactionDateTime&subReservationID=string&transactionFilter=simple_transactions%2Cadjustments%2Cadjustments_voids%2Cvoids%2Crefunds&transactionIDs=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

dataArray of objects

Transaction list covering the date range specified

countinteger

Number of results returned, based on pagination and filter parameters

totalinteger

Total count of results, based on filter parameters

messagestring or null

To be used in case any error occurs (if success = false). If success = true, it does not exist.

Response
application/json
{
  "success": true,
  "data": [
    { … }
  ],
  "count": 0,
  "total": 0,
  "message": "string"
}

postPayment

Request

Add a payment to a specified reservation or house account. If both Reservation ID and HouseAccountID are informed, only the former is taken in consideration.

Bodyapplication/x-www-form-urlencoded
propertyIDstring or null

Property ID

reservationIDstring

Reservation identifier

houseAccountIDstring

House Account identifier is necessary if reservationID not sent

subReservationIDstring or null

The Sub Reservation identifier. reservationID is still mandatory if subReservationID is sent.

typestring

Payment type. Use the call getPaymentMethods to get the properties enabled payment methods.

amountnumber

Amount paid on this transaction

cardTypestring

If type = credit, cardType is necessary. Allowed values are property based, but possible strings are: "visa","master","amex","aura","diners","hiper","elo","Discover","jcb","maestro","dan","PostCard","Eurocard","union_pay"

descriptionstring or null

Note to be added to payment

isDepositboolean or null

determine if this payment is a deposit (default: false)

curl -i -X POST \
  https://tbg-api-docs.vacatia.com/_mock/cloudbeds/postPayment \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d propertyID=string \
  -d reservationID=string \
  -d houseAccountID=string \
  -d subReservationID=string \
  -d type=string \
  -d amount=0 \
  -d cardType=string \
  -d description=string \
  -d isDeposit=true

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

paymentIDstring

Returns paymentID of transaction

transactionIDstring

Returns transactionID

messagestring or null

To be used in case any error occurs (if success = false). If success = true, it does not exist.

Response
application/json
{
  "success": true,
  "paymentID": "string",
  "transactionID": "string",
  "message": "string"
}

postCustomPaymentMethod

Request

Add a Custom Payment Method to a property. This call does not allow to add Payment Methods: credit cards, bank transfer or Pay Pal.

Bodyapplication/x-www-form-urlencoded
propertyIDstring or null

Property ID, if not sent will retrieve property ID from credentials, only one property ID call.

methodstring

Payment Method, value used in future calls. Must be unique for each property and no whitespaces are allowed (use camel case or underline instead). Will be verified against existing Payment Methods, if it exists, will try to enable it.

methodNamestring or null

Payment Method Name, value used to represent the Payment Method. Can use spaces. If nothing is sent, will use value for method.

curl -i -X POST \
  https://tbg-api-docs.vacatia.com/_mock/cloudbeds/postCustomPaymentMethod \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d propertyID=string \
  -d method=string \
  -d methodName=string

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

messagestring or null

To be used in case any error occurs (if success = false). If success = true, it does not exist.

Response
application/json
{
  "success": true,
  "message": "string"
}

getPaymentMethods

Request

Get a list of active methods for a property, or list of properties

Query
propertyIDstring

ID for the property to be queried

langstring

Language that payment methods name should return (if available).

Default "en"
Enum"en""pt-br""es"
curl -i -X GET \
  'https://tbg-api-docs.vacatia.com/_mock/cloudbeds/getPaymentMethods?lang=en&propertyID=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

dataobject
Response
application/json
{
  "success": true,
  "data": {
    "propertyID": "string",
    "methods": [ … ],
    "gateway": [ … ]
  }
}

getPaymentsCapabilities

Request

Lists the payment capabilities of a given property

Query
propertyIDstring

ID for the property to be queried

curl -i -X GET \
  'https://tbg-api-docs.vacatia.com/_mock/cloudbeds/getPaymentsCapabilities?propertyID=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

dataArray of objects
Response
application/json
{
  "success": true,
  "data": [
    { … }
  ]
}

postVoidPayment

Request

Voids a payment (using paymentID) to a specified reservation or house account.

Bodyapplication/x-www-form-urlencoded
propertyIDstring or null

Property ID

reservationIDstring

Reservation identifier

houseAccountIDstring

House Account identifier is necessary if reservationID not sent

paymentIDstring

paymentID of transaction that should be voided.

curl -i -X POST \
  https://tbg-api-docs.vacatia.com/_mock/cloudbeds/postVoidPayment \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d propertyID=string \
  -d reservationID=string \
  -d houseAccountID=string \
  -d paymentID=string

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

messagestring or null

To be used in case any error occurs (if success = false). If success = true, it does not exist.

Response
application/json
{
  "success": true,
  "message": "string"
}

postCharge

Request

Use a payment method to process a payment on a reservation, group profile, accounts receivable ledger, or house account.

Bodyapplication/x-www-form-urlencoded
propertyIDstring
reservationIDstring or null

Reservation ID

houseAccountIDstring or null

House Account ID

groupIDstring or null

Group ID

accountsReceivableLedgerIDstring or null

Accounts Receivable Ledger ID

amountstring

Amount to charge

currencystring

Currency to charge

descriptionstring

Description of the payment to display on folio

paymentMethodIdstring

Payment method UUID

isDepositboolean or null

determine if this payment is a deposit (default: false)

redirectUrlstring or null

client will be redirected to this page after he completed 3ds challenge. User will be redirected with HTTP get redirect and parameter result will be added to query string with possible values: - failed if 3ds challenge is not passed - successful if 3ds challenge is passed If not provided for card with 3ds the request will be rejected

curl -i -X POST \
  https://tbg-api-docs.vacatia.com/_mock/cloudbeds/postCharge \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d propertyID=string \
  -d reservationID=string \
  -d houseAccountID=string \
  -d groupID=string \
  -d accountsReceivableLedgerID=string \
  -d amount=string \
  -d currency=string \
  -d description=string \
  -d paymentMethodId=string \
  -d isDeposit=true \
  -d redirectUrl=string

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request was completed

dataobject

Payment details

Response
application/json
{
  "success": true,
  "data": {
    "paymentID": "string",
    "transactionID": "string",
    "paymentStatus": "string",
    "paymentType": "string",
    "nextAction": { … }
  }
}

postCreditCard

Request

Returns the rate of the room type selected, based on the provided parameters

Bodyapplication/x-www-form-urlencoded
propertyIDstring
reservationIDstring
cardTokenstring or null

cardToken provided by Stripe JS, not recommended, not required if paymentMethodId is provided

paymentMethodIdstring or null

Payment Method ID provided by the payments SDK

returnUrlstring or null

client will be redirected to this page after he completed 3ds challenge. User will be redirected with HTTP get redirect and parameter result will be added to query string with possible values: - failed if 3ds challenge is not passed - successful if 3ds challenge is passed If not provided for card with 3ds the request will be rejected

curl -i -X POST \
  https://tbg-api-docs.vacatia.com/_mock/cloudbeds/postCreditCard \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d propertyID=string \
  -d reservationID=string \
  -d cardToken=string \
  -d paymentMethodId=string \
  -d returnUrl=string

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

dataobject

Rates details

Response
application/json
{
  "success": true,
  "data": {
    "cardID": "string",
    "cardNumber": "string",
    "cardType": "visa",
    "redirectUrl": "string"
  }
}

Rate

Operations

Reservation

Operations

Room

Operations

Taxes and Fees

Operations

User

Operations