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:

  1. 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-connected and the widget shows no deposit step.
  2. 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.
  3. 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 === 20

C#

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