Payments

A Payment represents a financial transaction associated with a Booking. Only payments with the status ok are included in the calculation of the Booking’s totals; all other payment statuses are ignored for financial settlement.

Each Payment maintains a reference to a PaymentGateway, which defines the processing method used for the transaction. Gateways may represent external payment providers—such as Stripe—or internal methods like On-site Payment, Gift Certificate, or other methods.

When a Booking operates in individual guest payment mode, a Payment may also contain a reference to the Guest who made that specific contribution.

Payments can optionally reference an Invoice, allowing the transaction to be linked to a specific billing document.

The system supports Refunds through any available payment gateway. Refunds may also be issued as gift certificates, enabling the refunded amount to be reused in future transactions.

The Payment object

Attributes

idstring · uuidOptional

Unique identifier for the payment.

Example: 123e4567-e89b-12d3-a456-426614174000

currencystringOptional

Currency code for the payment ISO 4217 format.

Example: USD

amountnumber · floatOptional

Amount of the payment.

Example: 100

refund_amountnumber · floatOptional

Amount that has been refunded, if any.

Example: 0

surchargenumber · floatOptional

Amount of surcharge applied to the payment.

Example: 2.5

statusstring · enumOptional

Current status of the payment.

Example: okPossible values:

payment_gateway_messagestringOptional

Additional message regarding the payment status, set by payment provider if applicable.

Example: Payment completed successfully

foreign_currencystringOptional

Foreign currency code if applicable ISO 4217 format.

Example: EUR

amount_in_foreign_currencynumber · floatOptional

Amount in foreign currency if applicable, used for currency conversion, when booking currency differs from payment currency.

Example: 85

payment_gateway_referencestringOptional

External reference identifier for the transaction.

Example: TXN123456789

commentstringOptional

Additional comments regarding the payment.

Example: Imported from external system

booking_idstring · uuidOptional

Identifier for the associated booking.

Example: 223e4567-e89b-12d3-a456-426614174001

user_idstring · uuid | nullableOptional

Identifier for the user who registered the payment in backoffice.

Example: 323e4567-e89b-12d3-a456-426614174002

invoice_idstring · uuid | nullableOptional

Identifier for the associated invoice.

Example: 423e4567-e89b-12d3-a456-426614174003

payment_gateway_idinteger · int64Optional

Identifier for the payment gateway used.

Example: 1

guest_idstring · uuid | nullableOptional

Identifier for the associated guest, if applicable.

Example: 523e4567-e89b-12d3-a456-426614174004

deleted_atstring · date-timeOptional

Timestamp when the payment was deleted, if applicable.

Example: 2024-01-15T10:00:00Z

created_atstring · date-timeOptional

Timestamp when the payment was created.

Example: 2024-01-10T09:30:00Z

updated_atstring · date-timeOptional

Timestamp when the payment was last updated.

Example: 2024-01-12T14:45:00Z

paid_atstring · date-timeOptional

Timestamp when the payment was completed, if applicable, usually equal to created_at for immediate payments. Can be set manually by user.

Example: 2024-01-11T11:15:00Z

The Payment object

{
  "surcharge": 2.5,
  "amount": 100,
  "payment_gateway_message": "Payment completed successfully",
  "amount_in_foreign_currency": 85,
  "created_at": "2024-01-10T09:30:00Z",
  "foreign_currency": "EUR",
  "deleted_at": "2024-01-15T10:00:00Z",
  "booking_id": "223e4567-e89b-12d3-a456-426614174001",
  "paid_at": "2024-01-11T11:15:00Z",
  "guest_id": "523e4567-e89b-12d3-a456-426614174004",
  "updated_at": "2024-01-12T14:45:00Z",
  "user_id": "323e4567-e89b-12d3-a456-426614174002",
  "refund_amount": 0,
  "invoice_id": "423e4567-e89b-12d3-a456-426614174003",
  "currency": "USD",
  "comment": "Imported from external system",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "payment_gateway_reference": "TXN123456789",
  "payment_gateway_id": 1,
  "status": "ok"
}

Endpoints

List payments

get

List all payments

Query parameters

limitinteger · int32 · min: 1 · max: 100Optional

Number of payments to return

Default: 10

pageinteger · int32 · min: 1Optional

Page number

Default: 1

sort_byobject · enumOptional

Sorts the results based on the passed field. All possible values can be appended with ",asc" or ",desc"

Possible values:

idstring · uuid[]Optional

Filter by payment ID

amountstring · number or rangeOptional

Filter by payment amount

Example: 500,1000

currencystring · iso-4217 currency code[]Optional

Filter by payment currency (ISO 4217 code)

Example: USD,EUR

Responses

200

A list of payments

application/json

get

/payments

HTTPcURLJavaScriptPython

GET /private/payments HTTP/1.1
Host: api.bookinglayer.io
Accept: */*

200

A list of payments

[
  {
    "surcharge": 2.5,
    "amount": 100,
    "payment_gateway_message": "Payment completed successfully",
    "amount_in_foreign_currency": 85,
    "created_at": "2024-01-10T09:30:00Z",
    "foreign_currency": "EUR",
    "deleted_at": "2024-01-15T10:00:00Z",
    "booking_id": "223e4567-e89b-12d3-a456-426614174001",
    "paid_at": "2024-01-11T11:15:00Z",
    "guest_id": "523e4567-e89b-12d3-a456-426614174004",
    "updated_at": "2024-01-12T14:45:00Z",
    "user_id": "323e4567-e89b-12d3-a456-426614174002",
    "refund_amount": 0,
    "invoice_id": "423e4567-e89b-12d3-a456-426614174003",
    "currency": "USD",
    "comment": "Imported from external system",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "payment_gateway_reference": "TXN123456789",
    "payment_gateway_id": 1,
    "status": "ok"
  }
]