> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bookingshake.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment Events

> Receive real-time notifications when payments are created, updated, or deleted

<Warning>
  **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](mailto:support@bookingshake.com).
</Warning>

## 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`.

<Note>
  **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.
</Note>

**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](/api-reference/webhooks/invoices):

| 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

```json theme={null}
{
  "event": "payment.created",
  "timestamp": 1749722400000,
  "venue_id": "venue123",
  "venues_group_id": "group456",
  "data": {
    "id": "payment-789",
    "amount": 90000,
    "status": "paid",
    "name": "Acompte 30%",
    "method": "Virement bancaire",
    "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`](/api-reference/webhooks/accounts) and [`contact.deleted`](/api-reference/webhooks/contacts), **`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`         | string \| null | Payment method - see [Payment methods](#payment-methods)                                                                                      |
| `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`](/api-reference/webhooks/invoices)                                         |
| `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](/api-reference/webhooks/invoices) of the same booking share the same value |

### Payment Methods

`method` is the payment method label **verbatim**, as displayed to the user who recorded the payment. It is not a normalized enum: the same method appears in the language of the venue's locale (e.g., `Virement bancaire` / `Wire transfer`). Standard methods include card on site, card remote, voucher, check, cash, online payment, wire transfer, and restaurant vouchers - but free-text values are possible.

<Warning>
  Do not build logic on exact `method` values. Treat it as a display label, or map known labels defensively on your side.
</Warning>

## When Is `payment.updated` Triggered?

`payment.updated` is only emitted when at least one field exposed in the payload changes: amount, status, name, 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.

## Next Steps

<CardGroup cols={2}>
  <Card title="Invoice Events" icon="file-invoice" href="/api-reference/webhooks/invoices">
    Receive the full invoice payload when documents are issued
  </Card>

  <Card title="Security & Verification" icon="shield-halved" href="/api-reference/webhooks/security">
    Verify webhook signatures before processing
  </Card>
</CardGroup>