Payments

Beta - Payment data is currently in beta. The payload structure may still evolve before general availability. Share your feedback at support@bookingshake.com.

List and get payments

Overview

The payment endpoints expose the payments recorded on your venue’s invoices:

GET /payments?invoice_id={id} - list every payment attached to an invoice
GET /payments/{id} - retrieve a single payment by its document ID

Both return the same per-payment shape. Useful to reconcile an invoice’s payments on demand, or to back-fill a missed payment.* webhook.

Security deposits (holds) are out of scope - they are excluded from the list and return 404 on the single-get, consistent with the payment webhooks (which never emit for holds). Amounts are integer cents, dates are YYYY-MM-DD strings in the Europe/Paris timezone, timestamps are Unix milliseconds, and missing values are explicit null.

Authentication

All requests require a Bearer token (your BookingShake API key):

Authorization: Bearer YOUR_API_KEY

List payments of an invoice

GET /payments?invoice_id={id} returns every payment attached to the given invoice. The result is scoped to the authenticated venue, so an invoice that does not exist or belongs to another venue simply returns an empty array.

string

required

ID of the invoice whose payments you want to list - the invoice_id carried by the payment.* webhooks, and the id of GET /invoices/{id}.

curl "https://api.bookingshake.io/api/payments?invoice_id=file-456" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch(
  "https://api.bookingshake.io/api/payments?invoice_id=file-456",
  { headers: { Authorization: `Bearer ${process.env.BOOKINGSHAKE_API_KEY}` } },
);
const { data: payments } = await res.json();

import os, requests

res = requests.get(
    "https://api.bookingshake.io/api/payments",
    params={"invoice_id": "file-456"},
    headers={"Authorization": f"Bearer {os.environ['BOOKINGSHAKE_API_KEY']}"},
)
payments = res.json()["data"]

<?php
$ch = curl_init("https://api.bookingshake.io/api/payments?invoice_id=file-456");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . getenv("BOOKINGSHAKE_API_KEY"),
]);
$payments = json_decode(curl_exec($ch), true)["data"];
curl_close($ch);

The payments are returned wrapped in the standard { message, data } envelope, where data is an array of payment objects (each identical in shape to GET /payments/{id}).

{
  "message": "success",
  "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"
    }
  ]
}

Get a payment

GET /payments/{id} returns a single payment by its document ID, in the same shape as the list items.

string

required

The payment document ID - the id field carried by the payment.* webhooks.

curl https://api.bookingshake.io/api/payments/payment-789 \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch("https://api.bookingshake.io/api/payments/payment-789", {
  headers: { Authorization: `Bearer ${process.env.BOOKINGSHAKE_API_KEY}` },
});
const { data: payment } = await res.json();

import os, requests

res = requests.get(
    "https://api.bookingshake.io/api/payments/payment-789",
    headers={"Authorization": f"Bearer {os.environ['BOOKINGSHAKE_API_KEY']}"},
)
payment = res.json()["data"]

<?php
$ch = curl_init("https://api.bookingshake.io/api/payments/payment-789");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . getenv("BOOKINGSHAKE_API_KEY"),
]);
$payment = json_decode(curl_exec($ch), true)["data"];
curl_close($ch);

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 - resolve it with `GET /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 the `id` of `GET /invoices/{id}`
`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	Correlation key shared with invoice and payment events of the same booking

Amounts are signed: a negative amount with status paid represents a refund - see Refunds. See the payment webhook documentation for the full field reference.

Errors

Status	Meaning
`400`	Missing/invalid token, missing `invoice_id` (`GET /payments`), or missing payment id (`GET /payments/{id}`)
`404`	Payment not found - it does not exist, belongs to another venue, or is a security deposit (hold). (single-get only; the list returns `200` with `[]` instead)
`429`	Rate limit exceeded (60 requests/minute)
`500`	Internal server error

Out-of-scope payments are never disclosed: the single-get returns a uniform 404, and the list silently omits them - an invoice belonging to another venue returns an empty array, never an error revealing its existence.

Next Steps

Get an Invoice

Retrieve the invoice linked to a payment via invoice_id

Payment Events

Receive payments in real time via the payment.* webhooks

Update a payment

Overview

PATCH /payments/{id} updates a single payment by its document ID. It is a partial update: only the fields you include in the body are modified, everything else is left untouched. The request body uses the same conventions as the response - amount in integer cents, dates as YYYY-MM-DD (interpreted in the Europe/Paris timezone), and status verbatim. So you can read a payment with GET /payments/{id}, change a few fields, and send them straight back.

Updating a payment automatically emits the payment.updated webhook when at least one exposed field changes. Security deposits (holds) are out of scope and return 404, consistent with the payment webhooks.

Authentication

All requests require a Bearer token (your BookingShake API key):

Authorization: Bearer YOUR_API_KEY

Path Parameters

string

required

The payment document ID - the id field carried by the payment.* webhooks.

Body Parameters

All body fields are optional, but at least one must be provided.

string

Payment label.

integer

Amount in integer cents (e.g., 90000 = €900.00). Must be a non-negative integer.

string

One of waiting, paid, or canceled.

string

Stable ID of a payment method from the venue catalog - see GET /payment-methods. Must reference an active (non-archived) method; the display label stored on the payment is derived from the catalog.

string

Date the payment was received, YYYY-MM-DD. Pass null to clear it.

string

Date the payment is expected, YYYY-MM-DD. Pass null to clear it.

Request

curl -X PATCH https://api.bookingshake.io/api/payments/payment-789 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paid", "received_date": "2026-06-10" }'

const res = await fetch("https://api.bookingshake.io/api/payments/payment-789", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.BOOKINGSHAKE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ status: "paid", received_date: "2026-06-10" }),
});
const { data: payment } = await res.json();

import os, requests

res = requests.patch(
    "https://api.bookingshake.io/api/payments/payment-789",
    headers={"Authorization": f"Bearer {os.environ['BOOKINGSHAKE_API_KEY']}"},
    json={"status": "paid", "received_date": "2026-06-10"},
)
payment = res.json()["data"]

<?php
$ch = curl_init("https://api.bookingshake.io/api/payments/payment-789");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PATCH");
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "status" => "paid",
    "received_date" => "2026-06-10",
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . getenv("BOOKINGSHAKE_API_KEY"),
    "Content-Type: application/json",
]);
$payment = json_decode(curl_exec($ch), true)["data"];
curl_close($ch);

Response

The full payment is returned in its post-update state, wrapped in the standard { message, data } envelope - identical in shape to GET /payments/{id}.

{
  "message": "success",
  "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"
  }
}

See the Get a Payment reference for the full field descriptions.

Errors

Status	Meaning
`400`	Missing/invalid token, missing payment id, empty/invalid body, no updatable fields, or a field that fails validation (unknown `status`, non-integer `amount`, malformed date, `method_id` not matching an active method of the venue catalog)
`404`	Payment not found - it does not exist, belongs to another venue, or is a security deposit (hold)
`429`	Rate limit exceeded (30 requests/minute)
`500`	Internal server error

A 404 is returned uniformly whenever the payment is outside your scope, so the existence of another venue’s payment is never disclosed.

Getting Started

Webhooks

REST API

Guides

List and get payments

Overview

Authentication

List payments of an invoice

Get a payment

Fields

Errors

Next Steps

Get an Invoice

Payment Events

Update a payment

Overview

Authentication

Path Parameters

Body Parameters

Request

Response

Errors

Next Steps

Get a Payment

Payment Events

​List and get payments

​Overview

​Authentication

​List payments of an invoice

​Get a payment

​Fields

​Errors

​Next Steps

Get an Invoice

Payment Events

​Update a payment

​Overview

​Authentication

​Path Parameters

​Body Parameters

​Request

​Response

​Errors

​Next Steps

Get a Payment

Payment Events

List and get payments

Overview

Authentication

List payments of an invoice

Get a payment

Fields

Errors

Next Steps

Update a payment

Overview

Authentication

Path Parameters

Body Parameters

Request

Response

Errors

Next Steps