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

​
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.
​
invoice_id
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": "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"
    }
  ]
}

​
Get a payment

GET /payments/{id} returns a single payment by its document ID, in the same shape as the list items.
​
id
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

FieldTypeDescription
idstringUnique payment ID
amountnumber | nullAmount in integer cents
statusstring | nullwaiting, paid, or canceled
namestring | nullPayment label as entered by the user
methodstring | nullPayment method, verbatim label (not a normalized enum) - appears in the venue locale language. Do not build logic on exact values
received_datestring | nullDate the payment was received, YYYY-MM-DD
due_datestring | nullDate the payment is expected, YYYY-MM-DD
created_atnumber | nullCreation timestamp, Unix milliseconds
updated_atnumber | nullLast update timestamp, Unix milliseconds
invoice_idstring | nullID of the linked invoice - matches the id of GET /invoices/{id}
invoice_numberstring | nullNumber of the linked invoice, denormalized for convenience
quote_idstring | nullID of the linked quote
booking_idstring | nullCorrelation key shared with invoice and payment events of the same booking
See the payment webhook documentation for the full field reference.

​
Errors

StatusMeaning
400Missing/invalid token, missing invoice_id (GET /payments), or missing payment id (GET /payments/{id})
404Payment 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)
429Rate limit exceeded (60 requests/minute)
500Internal 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