payments

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 ones 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 Secure payments by BookingSync guide.

Parameters

OAuth Scopes:

payments_write_owned

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 kinds
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 one of 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)

payments_read

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)

payments_write

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 kinds
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 one of 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

OAuth Scopes:

payments_write_owned / payments_read / payments_write

response.json

{
  "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": [
    {
      "links": {
        "account": 33,
        "bookings": [
          21
        ],
        "bookings_payments": [
          3
        ]
      },
      "id": 2,
      "transaction_id": null,
      "order_id": null,
      "card": null,
      "amount_in_cents": 100000,
      "currency": "USD",
      "kind": "cash",
      "fullname": "John Doe",
      "email": "john@example.com",
      "locale": "en",
      "ip": "192.0.2.1",
      "test": null,
      "notes": null,
      "paid_at": "2025-04-08T12:05:06.332Z",
      "created_at": "2025-04-08T12:05:06.332Z",
      "updated_at": "2025-04-15T12:05:06.332Z",
      "rejected_at": null,
      "canceled_at": null,
      "description": "Payment for Awesome Rental from Friday 01 Jun 2017, 04:00 PM to Friday 8 Jun 2017, 10:00 AM",
      "address1": "Bernhard Creek",
      "address2": null,
      "zip": "07671-8254",
      "city": "East Winifred",
      "state": "Monatana",
      "country_code": "US",
      "forget_me_at": null,
      "processing_restricted_at": null
    }
  ]
}

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

OAuth Scopes:

payments_write_owned / payments_read / payments_write

response.json

{
  "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": [
    {
      "links": {
        "account": 33,
        "bookings": [
          21
        ],
        "bookings_payments": [
          3
        ]
      },
      "id": 2,
      "transaction_id": null,
      "order_id": null,
      "card": null,
      "amount_in_cents": 100000,
      "currency": "USD",
      "kind": "cash",
      "fullname": "John Doe",
      "email": "john@example.com",
      "locale": "en",
      "ip": "192.0.2.1",
      "test": null,
      "notes": null,
      "paid_at": "2025-04-08T12:05:06.334Z",
      "created_at": "2025-04-08T12:05:06.334Z",
      "updated_at": "2025-04-15T12:05:06.334Z",
      "rejected_at": null,
      "canceled_at": null,
      "description": "Payment for Awesome Rental from Friday 01 Jun 2017, 04:00 PM to Friday 8 Jun 2017, 10:00 AM",
      "address1": "Bernhard Creek",
      "address2": null,
      "zip": "07671-8254",
      "city": "East Winifred",
      "state": "Monatana",
      "country_code": "US",
      "forget_me_at": null,
      "processing_restricted_at": null
    }
  ]
}

Create a new payment

Returns a newly created payment.

POST /bookings/:booking_id/payments

OAuth Scopes:

payments_write_owned / payments_read / payments_write

request.json

{
  "payments": [
    {
      "amount_in_cents": 100000,
      "currency": "GBP",
      "kind": "cash",
      "fullname": "John Doe",
      "email": "john@example.com",
      "locale": "en",
      "paid_at": "2025-04-08T12:05:06.336Z",
      "address1": "Bernhard Creek",
      "address2": null,
      "zip": "07671-8254",
      "city": "East Winifred",
      "state": "Monatana",
      "country_code": "US"
    }
  ]
}

response.json

{
  "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": [
    {
      "links": {
        "account": 33,
        "bookings": [
          21
        ],
        "bookings_payments": [
          3
        ]
      },
      "id": 2,
      "transaction_id": null,
      "order_id": null,
      "card": null,
      "amount_in_cents": 100000,
      "currency": "USD",
      "kind": "cash",
      "fullname": "John Doe",
      "email": "john@example.com",
      "locale": "en",
      "ip": "192.0.2.1",
      "test": null,
      "notes": null,
      "paid_at": "2025-04-08T12:05:06.337Z",
      "created_at": "2025-04-08T12:05:06.337Z",
      "updated_at": "2025-04-15T12:05:06.337Z",
      "rejected_at": null,
      "canceled_at": null,
      "description": "Payment for Awesome Rental from Friday 01 Jun 2017, 04:00 PM to Friday 8 Jun 2017, 10:00 AM",
      "address1": "Bernhard Creek",
      "address2": null,
      "zip": "07671-8254",
      "city": "East Winifred",
      "state": "Monatana",
      "country_code": "US",
      "forget_me_at": null,
      "processing_restricted_at": null
    }
  ]
}

Update a payment

Returns an updated payment identified by ID.

PUT /payments/:payment_id

OAuth Scopes:

payments_write_owned / payments_read / payments_write

request.json

{
  "payments": [
    {
      "amount_in_cents": 100000,
      "currency": "GBP",
      "kind": "cash",
      "fullname": "John Doe",
      "email": "john@example.com",
      "locale": "en",
      "paid_at": "2025-04-08T12:05:06.338Z",
      "address1": "Bernhard Creek",
      "address2": null,
      "zip": "07671-8254",
      "city": "East Winifred",
      "state": "Monatana",
      "country_code": "US"
    }
  ]
}

response.json

{
  "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": [
    {
      "links": {
        "account": 33,
        "bookings": [
          21
        ],
        "bookings_payments": [
          3
        ]
      },
      "id": 2,
      "transaction_id": null,
      "order_id": null,
      "card": null,
      "amount_in_cents": 100000,
      "currency": "USD",
      "kind": "cash",
      "fullname": "John Doe",
      "email": "john@example.com",
      "locale": "en",
      "ip": "192.0.2.1",
      "test": null,
      "notes": null,
      "paid_at": "2025-04-08T12:05:06.339Z",
      "created_at": "2025-04-08T12:05:06.339Z",
      "updated_at": "2025-04-15T12:05:06.339Z",
      "rejected_at": null,
      "canceled_at": null,
      "description": "Payment for Awesome Rental from Friday 01 Jun 2017, 04:00 PM to Friday 8 Jun 2017, 10:00 AM",
      "address1": "Bernhard Creek",
      "address2": null,
      "zip": "07671-8254",
      "city": "East Winifred",
      "state": "Monatana",
      "country_code": "US",
      "forget_me_at": null,
      "processing_restricted_at": null
    }
  ]
}

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