Payment Events

Beta - Payment events are currently in beta. The payload structure may still evolve before general availability. If you build on them, share your feedback at support@bookingshake.com.

Overview

Payment events notify you of every change to payments in BookingShake: payment.created, payment.updated, and payment.deleted. These are pure CRUD events - there is no separate “payment received” event. The payment lifecycle is carried by the status field in the payload: a scheduled payment is created with status waiting, then updated to paid when received. An online payment received immediately emits a single payment.created with status paid.

Security deposits (holds) are out of scope. Documents recorded as security deposits never emit payment events. If a security deposit is converted into a payment (or vice versa), no created/deleted event is emitted for the transition.

Common use cases:

Reconcile payments in your accounting software
Track cash-in across venues in real-time
Trigger internal workflows when a payment becomes overdue or is received

Conventions

The payment payload follows the same conventions as invoice events:

Convention	Rule
Amounts	Integer cents (e.g., `90000` = €900.00)
Dates	`YYYY-MM-DD` strings, in the `Europe/Paris` timezone
Timestamps	Unix milliseconds
Missing values	Explicit `null`, never omitted

Payload Example

{
  "event": "payment.created",
  "timestamp": 1749722400000,
  "venue_id": "venue123",
  "venues_group_id": "group456",
  "data": {
    "id": "payment-789",
    "amount": 90000,
    "status": "paid",
    "name": "Acompte 30%",
    "method_id": "wire_transfer",
    "received_date": "2026-06-10",
    "due_date": "2026-06-15",
    "created_at": 1749549600000,
    "updated_at": 1749722400000,
    "invoice_id": "file-456",
    "invoice_number": "FAC-2026-0021",
    "quote_id": "quote-123",
    "booking_id": "booking-abc"
  }
}

All three events (payment.created, payment.updated, payment.deleted) carry the same data structure. Unlike account.deleted and contact.deleted, payment.deleted includes the full payment data as it was just before deletion - not only the ID.

Data Fields

Field	Type	Description
`id`	string	Unique payment ID
`amount`	number \| null	Amount in integer cents
`status`	string \| null	`waiting`, `paid`, or `canceled`
`name`	string \| null	Payment label as entered by the user
`method_id`	string \| null	Stable ID of the payment method in the venue catalog - see Payment methods. `null` on payments recorded before the catalog existed
`received_date`	string \| null	Date the payment was received, `YYYY-MM-DD`
`due_date`	string \| null	Date the payment is expected, `YYYY-MM-DD`
`created_at`	number \| null	Creation timestamp, Unix milliseconds
`updated_at`	number \| null	Last update timestamp, Unix milliseconds
`invoice_id`	string \| null	ID of the linked invoice - matches `data.id` of `invoice.created`
`invoice_number`	string \| null	Number of the linked invoice, denormalized for convenience
`quote_id`	string \| null	ID of the linked quote
`booking_id`	string \| null	Opaque correlation key of the booking: all payments and invoices of the same booking share the same value

Payment Methods

Each venue manages its own catalog of payment methods. A payment carries the stable ID of its method in that catalog as method_id; resolve IDs to labels and translations with GET /payment-methods.

method_id is null on payments recorded before the venue catalog was introduced (mid-2026).

Refunds

Amounts are signed. When a venue refunds money to a client, BookingShake records it as a payment with a negative amount (cents refunded) and status paid (the money has actually left). It emits a regular payment.created, and sums of paid amounts on an invoice are therefore net of refunds by construction. Convention: a negative amount with status paid represents a refund. A negative amount with status waiting is a legacy scheduled line that expects nothing and will eventually be canceled - not a refund. Refund records are immutable: they are never rescheduled or corrected. An erroneous refund is compensated by a new incoming payment, not by editing the record.

When Is `payment.updated` Triggered?

payment.updated is only emitted when at least one field exposed in the payload changes: amount, status, name, payment method, received/due dates, or the invoice, quote, and booking links. Internal changes (sync metadata, technical fields) do not emit events, so you will not receive no-op updates.

Getting Started

Webhooks

REST API

Guides

Overview

Conventions

Payload Example

Data Fields

Payment Methods

Refunds

When Is `payment.updated` Triggered?

Next Steps

Invoice Events

Security & Verification

​Overview

​Conventions

​Payload Example

​Data Fields

​Payment Methods

​Refunds

​When Is payment.updated Triggered?

​Next Steps

Invoice Events

Security & Verification

Overview

Conventions

Payload Example

Data Fields

Payment Methods

Refunds

When Is `payment.updated` Triggered?

Next Steps