Overview

Introduction Changelog Requirements Libraries Authorization Testing the Authorization Enumerables

Endpoints

Accounts Amenities Applications Availabilities Bathrooms Bedrooms Booking Discount Codes Booking Discount Code Usages Bookings Booking Comments Bookings Fees Bookings Payments Bookings Tags Bookings Taxes Change Overs Clients Contacts Destinations Fees Fees Taxes Hosts Inbox Attachments Inbox Conversations Inbox Messages Inbox Participants Inquiries Living Rooms LOS Records Me Mid Term Rate Maps Nightly Rate Maps Payment Gateways Payments Periods Photos Rates Rates Rules Rates Tables Rentals Rental Contacts Rental Agreements Rental Cancelation Policies Rental Cancelation Policy Items Rentals Amenities ! Rentals Contents Overrides Rentals Fees Rental Link Groups Rental Links Rentals Tags Rentals Taxes Rental URLs Reviews Seasons Sources Special Offers Taxes Tax Rules

Payments

  1. Overview
  2. List payments
  3. Search payments
  4. Get a single payment
  5. Create a new payment
  6. Update a payment
  7. Cancel a payment

Overview

This resource represents the Payments for Bookings, which can be either recorded manually (via API or manually) or be automated (with instant-booking and bookingsync kind).

Payments can also drive the lifecycle of the Bookings - creating a paid Payment (the ons that have paid_at timestamp assigned) with instant-booking kind ensures that the Booking is booked (especially useful for confirming tentative Bookings).

If you are interested in implementing your own payment flow, check out this guide.

Parameters

Name Type Read/Write Description Constraints
account Integer Read Account’s ID related to the Payment  
payment_gateway Integer Read (requires preferences_payments_read scope) Payment Gateway’s ID related to the Payment  
bookings Array Read Bookings’ IDs related to the Payment  
bookings_payments Array Read Booking Payments’ IDs related to the Payment  
id Integer Read Payment’s id.  
order_id String Read ID of order (only for internal Payments managed by BookingSync)  
gateway_id Integer Write ID of the Payment Gateway of Paypal Express Gateway Required for instant-booking or bookingsync kind
gateway_type String Write Type of the entity representing the gateway (this is a polymorphic relationship) PaymentGateway or PaypalExpressGateway, Required for instant-booking or bookingsync kind
gateway_name String Write Payment Gateway’s name, available values are described in enums section Required for instant-booking or bookingsync kind
transaction_id String Read/Write ID of transaction coming from the Payment Gateway.  
address1 String Read/Write Payer’s first address. Maximum length: 100
address2 String Read/Write Payer’s second address. Maximum length: 100
amount_in_cents Integer Read/Write Payment’s amount in cents. Required
card String Read/Write Payment’s card number, only the last 4 digits are visible. (example: "XXXX-XXXX-XXXX-1234").  
city String Read/Write Payer’s city. Maximum length: 100
country_code String Read/Write Payer’s country code, list of codes is available at wikipedia. Must be one of the country codes if present
currency String Read/Write Payment’s currency code, list of codes described in enums section. Required, must be one of the currencies
description String Read Auto-generated description based on Rental’s name and related Booking’s start_at/end_at timestamps  
kind String Read/Write Payment’s kind, list of kinds described in enums section. Required, must be one of the payment kin
email String Read/Write Payer’s email. Must be of email format if present
fullname String Read/Write Payer’s fullname. Cannot contain non-printing characters
ip String Read Payer’s ip.  
locale String Read/Write Payer’s preferred locale, list of locales described in enums section. Must be of on the Account’s available locales if present
notes Text Read/Write Payment’s additional information.  
state String Read/Write Payer’s state. Maximum length: 100, required if country_code set to US
test Boolean Read Payment’s test status.  
zip String Read/Write Payer’s zip code. Maximum length: 10
credit_card_token String Read/Write Token derived from the Credit Card  
offsite_payment Boolean Read/Write Whether Payment is an offsite one or not  
locked String Read Payment’s locked status.  
chargeable Boolean Read Whether Payment is chargeable or not (e.g. if the related Booking is canceled or fully paid, it’s going to return false)  
created_at Time Read Payment’s create time.  
updated_at Time Read Payment’s update time.  
rejected_at Time Read Payment’s reject time.  
canceled_at Time Read Payment’s cancel time.  
paid_at Time Read/Write Payment’s paid time. Required unless kind is bookingsync or instant-booking, must be in the past
forget_me_at Time Read Refer to GDPR guide.  
processing_restricted_at Time Read Refer to GDPR guide.  
capturable_from Date Read/Write A date from which Payment is capturable  
authorized_at Time Read/Write Payment’s authorization time  
escrow_date Date Read Payment’s escrow date (applicable for BookingPay Payment Gateway)  
Name Type Read/Write Description
account Integer Read Account’s ID related to the Payment
payment_gateway Integer Read (requires preferences_payments_read scope) Payment Gateway’s ID related to the Payment
bookings Array Read Bookings’ IDs related to the Payment
bookings_payments Array Read Booking Payments’ IDs related to the Payment
id Integer Read Payment’s id.
order_id String Read Id of order (only for instant bookings managed by BookingSync)
transaction_id String Read Id of paypal transaction.
address1 String Read Payer’s first address.
address2 String Read Payer’s second address.
amount_in_cents Integer Read Payment’s value.
card String Read Payment’s card number, only the last 4 digits are visible. (example: "XXXX-XXXX-XXXX-1234").
city String Read Payer’s city.
country_code String Read Payer’s country code, list of codes is available at wikipedia.
currency String Read Payment’s currency code, list of codes described in enums section.
description String Read Auto-generated description based on Rental’s name and related Booking’s start_at/end_at timestamps.
kind String Read Payment’s kind, list of kinds described in enums section.
email String Read Payer’s email.
fullname String Read Payer’s fullname.
ip String Read Payer’s ip.
locale String Read Payer’s preferred locale, list of locales described in enums section.
notes Text Read Payment’s additional information.
state String Read Payer’s state.
test Boolean Read Payment’s test status.
zip String Read Payer’s zip code.
credit_card_token String Read Token derived from the Credit Card
offsite_payment Boolean Read Whether Payment is an offsite one or not
locked String Read Payment’s locked status.
chargeable Boolean Read Whether Payment is chargeable or not (e.g. if the related Booking is canceled or fully paid, it’s going to return false)
created_at Time Read Payment’s create time.
updated_at Time Read Payment’s update time.
rejected_at Time Read Payment’s reject time.
canceled_at Time Read Payment’s cancel time.
paid_at Time Read Payment’s paid time.
forget_me_at Time Read Refer to GDPR guide.
processing_restricted_at Time Read Refer to GDPR guide.
capturable_from Date Read A date from which Payment is capturable
authorized_at Time Read Payment’s authorization time
escrow_date Date Read Payment’s escrow date (applicable for BookingPay Payment Gateway)
Name Type Read/Write Description Constraints
account Integer Read Account’s ID related to the Payment  
payment_gateway Integer Read (requires preferences_payments_read scope) Payment Gateway’s ID related to the Payment  
bookings Array Read Bookings’ IDs related to the Payment  
bookings_payments Array Read Booking Payments’ IDs related to the Payment  
id Integer Read Payment’s id.  
order_id String Read ID of order (only for internal Payments managed by BookingSync)  
gateway_id Integer Write ID of the Payment Gateway of Paypal Express Gateway Required for instant-booking or bookingsync kind
gateway_type String Write Type of the entity representing the gateway (this is a polymorphic relationship) PaymentGateway or PaypalExpressGateway, Required for instant-booking or bookingsync kind
gateway_name String Write Payment Gateway’s name, available values are described in enums section Required for instant-booking or bookingsync kind
transaction_id String Read/Write ID of transaction coming from the Payment Gateway.  
address1 String Read/Write Payer’s first address. Maximum length: 100
address2 String Read/Write Payer’s second address. Maximum length: 100
amount_in_cents Integer Read/Write Payment’s amount in cents. Required
card String Read/Write Payment’s card number, only the last 4 digits are visible. (example: "XXXX-XXXX-XXXX-1234").  
city String Read/Write Payer’s city. Maximum length: 100
country_code String Read/Write Payer’s country code, list of codes is available at wikipedia. Must be one of the country codes if present
currency String Read/Write Payment’s currency code, list of codes described in enums section. Required, must be one of the currencies
description String Read Auto-generated description based on Rental’s name and related Booking’s start_at/end_at timestamps.  
kind String Read/Write Payment’s kind, list of kinds described in enums section. Required, must be one of the payment kin
email String Read/Write Payer’s email. Must be of email format if present
fullname String Read/Write Payer’s fullname. Cannot contain non-printing characters
ip String Read Payer’s ip.  
locale String Read/Write Payer’s preferred locale, list of locales described in enums section. Must be of on the Account’s available locales if present
notes Text Read/Write Payment’s additional information.  
state String Read/Write Payer’s state. Maximum length: 100, required if country_code set to US
test Boolean Read Payment’s test status.  
zip String Read/Write Payer’s zip code. Maximum length: 10
credit_card_token String Read/Write Token derived from the Credit Card  
offsite_payment Boolean Read/Write Whether Payment is an offsite one or not  
locked String Read Payment’s locked status.  
chargeable Boolean Read Whether Payment is chargeable or not (e.g. if the related Booking is canceled or fully paid, it’s going to return false)  
created_at Time Read Payment’s create time.  
updated_at Time Read Payment’s update time.  
rejected_at Time Read Payment’s reject time.  
canceled_at Time Read Payment’s cancel time.  
paid_at Time Read/Write Payment’s paid time. Required unless kind is bookingsync or instant-booking, must be in the past
forget_me_at Time Read Refer to GDPR guide.  
processing_restricted_at Time Read Refer to GDPR guide.  
capturable_from Date Read/Write A date from which Payment is capturable  
authorized_at Time Read/Write Payment’s authorization time  
escrow_date Date Read Payment’s escrow date (applicable for BookingPay Payment Gateway)  

List payments

List all payments for a given account.

GET /payments

Response

{
  "links": {
    "payments.account": "https://www.bookingsync.com/api/v3/accounts/{payments.account}",
    "payments.bookings": "https://www.bookingsync.com/api/v3/bookings/{payments.bookings}",
    "payments.bookings_payments": "https://www.bookingsync.com/api/v3/bookings_payments/{payments.bookings_payments}"
  },
  "payments": [
    {
      "id": 2,
      "address1": "Bernhard Creek",
      "address2": null,
      "amount_in_cents": 100000,
      "card": null,
      "city": "East Winifred",
      "country_code": "US",
      "currency": "USD",
      "description": "Payment for Awesome Rental from Friday 01 Jun 2017, 04:00 PM to Friday 8 Jun 2017, 10:00 AM",
      "email": "john@example.com",
      "fullname": "John Doe",
      "ip": "192.0.2.1",
      "kind": "cash",
      "locale": "en",
      "notes": null,
      "order_id": null,
      "state": "Monatana",
      "test": null,
      "transaction_id": null,
      "zip": "07671-8254",
      "created_at": "2023-12-11T08:26:26Z",
      "updated_at": "2023-12-11T08:26:26Z",
      "rejected_at": null,
      "canceled_at": null,
      "forget_me_at": null,
      "paid_at": "2023-12-11T08:26:26Z",
      "processing_restricted_at": null,
      "links": {
        "account": 33,
        "bookings": [
          21
        ],
        "bookings_payments": [
          3
        ]
      }
    }
  ]
}

Search payments

Search parameters allow to filter payments by specified fields.

Example:

GET /payments?order_id=BS-abc-123

Search Parameters

Name Type Description
order_id String List of comma separated IDs. Returns only payments with this order_id(s)

Get a single payment

Returns a single payment identified by ID.

GET /payments/:payment_id

Response

{
  "links": {
    "payments.account": "https://www.bookingsync.com/api/v3/accounts/{payments.account}",
    "payments.bookings": "https://www.bookingsync.com/api/v3/bookings/{payments.bookings}",
    "payments.bookings_payments": "https://www.bookingsync.com/api/v3/bookings_payments/{payments.bookings_payments}"
  },
  "payments": [
    {
      "id": 2,
      "address1": "Bernhard Creek",
      "address2": null,
      "amount_in_cents": 100000,
      "card": null,
      "city": "East Winifred",
      "country_code": "US",
      "currency": "USD",
      "description": "Payment for Awesome Rental from Friday 01 Jun 2017, 04:00 PM to Friday 8 Jun 2017, 10:00 AM",
      "email": "john@example.com",
      "fullname": "John Doe",
      "ip": "192.0.2.1",
      "kind": "cash",
      "locale": "en",
      "notes": null,
      "order_id": null,
      "state": "Monatana",
      "test": null,
      "transaction_id": null,
      "zip": "07671-8254",
      "created_at": "2023-12-11T08:26:26Z",
      "updated_at": "2023-12-11T08:26:26Z",
      "rejected_at": null,
      "canceled_at": null,
      "forget_me_at": null,
      "paid_at": "2023-12-11T08:26:26Z",
      "processing_restricted_at": null,
      "links": {
        "account": 33,
        "bookings": [
          21
        ],
        "bookings_payments": [
          3
        ]
      }
    }
  ]
}

Create a new payment

Returns a newly created payment.

POST /bookings/:booking_id/payments

Example JSON request

{
  "payments": [
    {
      "address1": "Bernhard Creek",
      "address2": null,
      "amount_in_cents": 100000,
      "city": "East Winifred",
      "country_code": "US",
      "currency": "GBP",
      "email": "john@example.com",
      "fullname": "John Doe",
      "kind": "cash",
      "locale": "en",
      "state": "Monatana",
      "zip": "07671-8254",
      "paid_at": "2023-12-11T08:26:26Z"
    }
  ]
}

Response

{
  "links": {
    "payments.account": "https://www.bookingsync.com/api/v3/accounts/{payments.account}",
    "payments.bookings": "https://www.bookingsync.com/api/v3/bookings/{payments.bookings}",
    "payments.bookings_payments": "https://www.bookingsync.com/api/v3/bookings_payments/{payments.bookings_payments}"
  },
  "payments": [
    {
      "id": 2,
      "address1": "Bernhard Creek",
      "address2": null,
      "amount_in_cents": 100000,
      "card": null,
      "city": "East Winifred",
      "country_code": "US",
      "currency": "USD",
      "description": "Payment for Awesome Rental from Friday 01 Jun 2017, 04:00 PM to Friday 8 Jun 2017, 10:00 AM",
      "email": "john@example.com",
      "fullname": "John Doe",
      "ip": "192.0.2.1",
      "kind": "cash",
      "locale": "en",
      "notes": null,
      "order_id": null,
      "state": "Monatana",
      "test": null,
      "transaction_id": null,
      "zip": "07671-8254",
      "created_at": "2023-12-11T08:26:26Z",
      "updated_at": "2023-12-11T08:26:26Z",
      "rejected_at": null,
      "canceled_at": null,
      "forget_me_at": null,
      "paid_at": "2023-12-11T08:26:26Z",
      "processing_restricted_at": null,
      "links": {
        "account": 33,
        "bookings": [
          21
        ],
        "bookings_payments": [
          3
        ]
      }
    }
  ]
}

Update a payment

Returns an updated payment identified by ID.

PUT /payments/:payment_id

Example JSON request

{
  "payments": [
    {
      "address1": "Bernhard Creek",
      "address2": null,
      "amount_in_cents": 100000,
      "city": "East Winifred",
      "country_code": "US",
      "currency": "GBP",
      "email": "john@example.com",
      "fullname": "John Doe",
      "kind": "cash",
      "locale": "en",
      "state": "Monatana",
      "zip": "07671-8254",
      "paid_at": "2023-12-11T08:26:26Z"
    }
  ]
}

Response

{
  "links": {
    "payments.account": "https://www.bookingsync.com/api/v3/accounts/{payments.account}",
    "payments.bookings": "https://www.bookingsync.com/api/v3/bookings/{payments.bookings}",
    "payments.bookings_payments": "https://www.bookingsync.com/api/v3/bookings_payments/{payments.bookings_payments}"
  },
  "payments": [
    {
      "id": 2,
      "address1": "Bernhard Creek",
      "address2": null,
      "amount_in_cents": 100000,
      "card": null,
      "city": "East Winifred",
      "country_code": "US",
      "currency": "USD",
      "description": "Payment for Awesome Rental from Friday 01 Jun 2017, 04:00 PM to Friday 8 Jun 2017, 10:00 AM",
      "email": "john@example.com",
      "fullname": "John Doe",
      "ip": "192.0.2.1",
      "kind": "cash",
      "locale": "en",
      "notes": null,
      "order_id": null,
      "state": "Monatana",
      "test": null,
      "transaction_id": null,
      "zip": "07671-8254",
      "created_at": "2023-12-11T08:26:26Z",
      "updated_at": "2023-12-11T08:26:26Z",
      "rejected_at": null,
      "canceled_at": null,
      "forget_me_at": null,
      "paid_at": "2023-12-11T08:26:26Z",
      "processing_restricted_at": null,
      "links": {
        "account": 33,
        "bookings": [
          21
        ],
        "bookings_payments": [
          3
        ]
      }
    }
  ]
}

Cancel a payment

Required OAuth scope: :payments_write_owned or :payments_write

Returns an empty response with ‘204 No Content’ status code on success.

DELETE /payments/:payment_id