Sign in to see your venue's slug and publishable key in every sample.
Your account has no venue yet, so the samples keep their placeholders. Sign out
Signed in as · . Create a publishable key in the console and reload to see it here. Sign out
Signed in as · . The samples show your venue's publishable key. Sign out
Developer docs
Take a deposit on a booking
Switch on deposits, book with an opt-in, send the guest to Stripe Checkout, confirm from the payment and handle cancellations, refunds and a lost slot.
A deposit makes a booking a commitment: the guest pays an amount up front, and the booking is confirmed only when the payment arrives. This tutorial takes you from the venue's settings to a paid, confirmed booking, then through the cases that matter in production — a guest who cancels, a refund, and a slot that was taken while the guest was paying.
You need a venue on the Premium plan (deposits are a Premium feature), a connected Stripe payout account, and a publishable key or a secret key (Authentication). The deposit is a direct charge on the venue's own Stripe account; BookDinePlay never sees card data.
1. Switch deposits on
Three things must all be true before a booking can ask for a deposit:
- The payout account can sell. In the console open Billing → Payouts and finish Stripe's onboarding; the status must read Enabled. Until then the API answers
payouts-not-connectedand the widget shows no deposit step. - The venue takes deposits. On the venue page, in Deposits and online payments, switch on Accept online payments and Require deposits on bookings, and choose the currency and a Default deposit amount — the amount used for any resource that has none of its own.
- There is an amount. A resource's own deposit is part of its pricing; a resource without one uses the venue default. With neither, no deposit is due.
Then decide what happens when a guest cancels a paid booking, in the cancellation policy card (Let guests cancel their own booking):
| Setting | A guest who cancels |
|---|---|
| They must contact you (no online cancel) | Cannot cancel online; the booking stays until you handle it. This is the default |
| Refund the deposit in full | Cancels online and the deposit goes back to their card at once |
| Let them cancel, but keep the deposit | Cancels online and forfeits the deposit |
Everything above is also available through the operator API and the MCP server (venue_update, payouts_status, cancellation_policy_update).
2. Check that the venue can take a deposit
The venue profile tells your page whether to offer the step at all. onlineDepositsAvailable is true only when the venue takes payments and deposits, its plan includes them and its payout account can sell:
curl
curl "https://api.bookdineplay.com/api/venues/your-venue" \
-H "X-BookDinePlay-Key: bdp_pk_your_publishable_key" \
-H "Origin: https://www.your-venue.example"JavaScript
const venue = await client.venue();
const offerDeposit = venue.onlineDepositsAvailable === true;C#
var venue = await client.GetVenueAsync("your-venue", cancellationToken);
var offerDeposit = venue?.OnlineDepositsAvailable == true;PHP
<?php
$response = wp_remote_get( 'https://api.bookdineplay.com/api/venues/your-venue', [ 'headers' => [ 'X-BookDinePlay-Key' => BOOKDINEPLAY_SECRET_KEY ] ] );
$venue = json_decode( wp_remote_retrieve_body( $response ), true );
$offer_deposit = ! empty( $venue['onlineDepositsAvailable'] );3. Book with a deposit
The guest agrees to the deposit by sending depositOptIn: true with the booking. When all three conditions hold, the reservation comes back Pending with depositRequired: true and the depositAmount; the slot is held in the meantime.
curl
curl -X POST "https://api.bookdineplay.com/api/venues/your-venue/reservations" \
-H "X-BookDinePlay-Key: bdp_pk_your_publishable_key" \
-H "Origin: https://www.your-venue.example" \
-H "Content-Type: application/json" \
-d '{ "resourceType": "RestaurantTable", "date": "2026-12-01", "start": "19:00", "partySize": 4, "customerName": "Jana Berger", "email": "jana@example.com", "depositOptIn": true }'JavaScript
const reservation = await client.reserve({
resourceType: 'RestaurantTable', date: '2026-12-01', start: '19:00', partySize: 4,
customerName: 'Jana Berger', email: 'jana@example.com', depositOptIn: true
});
// reservation.status === 'Pending', reservation.depositRequired === true, reservation.depositAmount === 20C#
var reservation = await client.CreateReservationAsync("your-venue", new CreateReservationRequest
{
ResourceType = BookableResourceType.RestaurantTable,
Date = "2026-12-01",
Start = "19:00",
PartySize = 4,
CustomerName = "Jana Berger",
Email = "jana@example.com",
DepositOptIn = true
}, cancellationToken);PHP
<?php
$response = wp_remote_post( 'https://api.bookdineplay.com/api/venues/your-venue/reservations', [
'headers' => [ 'X-BookDinePlay-Key' => BOOKDINEPLAY_SECRET_KEY, 'Content-Type' => 'application/json' ],
'body' => wp_json_encode( [
'resourceType' => 'RestaurantTable', 'date' => '2026-12-01', 'start' => '19:00', 'partySize' => 4,
'customerName' => 'Jana Berger', 'email' => 'jana@example.com', 'depositOptIn' => true,
] ),
] );
$reservation = json_decode( wp_remote_retrieve_body( $response ), true );If the guest does not opt in, or any condition is missing, the booking is Confirmed at once and no deposit is involved. Treat depositRequired as the only signal: do not infer it from the venue's settings.
4. Send the guest to pay
Create a payment intent for exactly the booking's depositAmount and currency. Any other amount is refused with 400, so a client can never decide what the guest is charged. The answer carries a checkoutUrl: send the guest there. It is Stripe's hosted page, so no card data touches your site or BookDinePlay.
curl
curl -X POST "https://api.bookdineplay.com/api/venues/your-venue/payment-intents" \
-H "X-BookDinePlay-Key: bdp_pk_your_publishable_key" \
-H "Origin: https://www.your-venue.example" \
-H "Content-Type: application/json" \
-d '{ "reservationReference": "BDP-7K2Q9H", "amount": 20.00, "currency": "EUR" }'JavaScript
const intent = await client.payDeposit({
reservationReference: reservation.reference,
amount: reservation.depositAmount,
currency: reservation.currency
});
if (intent.checkoutUrl) window.location.assign(intent.checkoutUrl);C#
var intent = await client.CreatePaymentIntentAsync("your-venue", new CreatePaymentIntentRequest
{
ReservationReference = reservation.Reference,
Amount = reservation.DepositAmount ?? 0m,
Currency = reservation.Currency
}, cancellationToken);PHP
<?php
$response = wp_remote_post( 'https://api.bookdineplay.com/api/venues/your-venue/payment-intents', [
'headers' => [ 'X-BookDinePlay-Key' => BOOKDINEPLAY_SECRET_KEY, 'Content-Type' => 'application/json' ],
'body' => wp_json_encode( [ 'reservationReference' => $reservation['reference'], 'amount' => $reservation['depositAmount'], 'currency' => $reservation['currency'] ] ),
] );
$intent = json_decode( wp_remote_retrieve_body( $response ), true );The deposit can be paid once, and only while the booking is Pending. A booking that was cancelled, confirmed by the venue or finished answers 409 with the reason deposit-not-payable; one already paid answers 409 deposit-already-paid.
A guest may pay part of it with a gift voucher: add voucherCode and the voucher pays what it covers, the card the rest. A voucher that covers everything opens no Stripe page and confirms the booking at once (Vouchers).
5. The payment confirms the booking
You do not call anything to confirm. When Stripe reports the payment, BookDinePlay stores the payment identifiers on the booking and moves it to Confirmed. To show the result to the guest, read the booking with the cancelToken from step 3, which needs no key:
curl "https://api.bookdineplay.com/api/reservations/<cancelToken>"The status becomes Confirmed shortly after the payment; keep showing "waiting for payment" until it does, and offer the payment link again if it is still Pending after the Checkout session expired.
6. When it goes wrong
The payment arrives after the slot is gone. A pending booking holds its slot, but a payment can land late — after the booking was cancelled or its slot given to someone else. The payment is never lost: the booking becomes PaidButUnavailable. It holds no slot, because the other booking is the legitimate holder, and the venue resolves it in the console, usually with a refund. A booking in this state cannot be edited, and it is not a status a caller can set.
The guest cancels. With the cancellation policy above: no online cancel answers 409 reservation-deposit-not-refundable and leaves the booking untouched; refund in full refunds first and cancels second, so a failed refund (502 reservation-refund-failed) leaves the booking and the money exactly as they were; keep the deposit cancels and keeps it. Read canCancel and cancelNote on the guest's booking before showing a cancel button.
The venue refunds. The console's refund on the reservation (or reservations_refund_deposit over MCP) returns the card part to the card and the voucher part to the voucher. Refunding twice is harmless. Refunding stays possible after a downgrade: a guest who paid while the plan allowed it is never stranded.
A request is retried. Send an Idempotency-Key with the booking so a retry after a timeout returns the original reservation (Reservations).
Try it
On a venue whose payout account is connected in Stripe's test mode, pay with Stripe's test card 4242 4242 4242 4242, any future expiry and any CVC. The demo venue runs in test mode for exactly this.
Next steps
- Payment intents and Reservations — every field and refusal.
- Events with tickets — the same Stripe Checkout for ticket sales.
- Errors —
feature-not-in-planandpayouts-not-connected.