Payments
Read the booking-payment ledger. Read-only on v1 — refunds and rebookings stay in the operator dashboard.
Each booking has one or more payments — deposit, installments, final balance. The ledger tracks every Stripe charge attempt against the booking's payment intent.
| Method | Path | Scope |
|---|---|---|
| GET | /api/v1/payments | payments:read |
The BookingPayment object:
| Field | Type | Notes |
|---|---|---|
id | string | Opaque payment id. |
bookingId | string | Owning booking. |
mode | enum | full, deposit_only, installment. |
status | enum | pending, scheduled, processing, succeeded, failed, cancelled. |
label | string | Operator-facing label (e.g. "Deposit", "Final balance"). |
amountCents | integer | |
currency | string | ISO 4217. |
scheduledFor | ISO 8601 | null | Planned off-session charge time. |
chargedAt | ISO 8601 | null | When Stripe accepted the charge. |
isDeposit | boolean | True for the first payment of a booking. |
paymentRail | string | card, bank, etc. |
kind | string | More specific: stripe_card, stripe_sepa_debit, etc. |
The public surface intentionally omits internal Stripe identifiers, payout deadlines, and dispute-related timing fields.
GET /api/v1/payments
List payments in the tenant. Cursor-paginated. Tenant scoping uses the booking's tenant id.
Required scope — payments:read
Query parameters
| Name | Type | Default | Notes |
|---|---|---|---|
limit | integer | 50 | Max 100. |
cursor | string | — | From a previous response. |
status | string | — | One of pending, scheduled, processing, succeeded, failed, cancelled. Unknown values are ignored. |
bookingId | string | — | Filter to one booking's ledger. |
Response 200
{
"data": [ /* BookingPayment[] */ ],
"meta": { "cursor": "pay_a1b2c3" | null, "hasMore": true | false }
}Errors — 401 unauthorized, 403 (scope-required, or plan-required when the plan has no API access), 429 rate-limited.
/api/v1/paymentsTry itRequests are proxied through this docs site so CORS doesn't block the call. Use a sandbox token if you don't want test calls hitting live data.
Query parameters
limitcursorstatusbookingIdGET /api/v1/paymentsReal-time updates
For reactive flows (e.g. notify on failed installments), subscribe to the payment.succeeded and payment.failed webhooks rather than polling this endpoint.