Entwicklerdokumentation

Eine Anzahlung bei der Buchung verlangen

Anzahlungen einschalten, mit Opt-in buchen, zu Stripe Checkout schicken, per Zahlung bestätigen und Stornos, Erstattungen und verlorene Slots behandeln.

Eine Anzahlung macht eine Buchung verbindlich: Der Gast zahlt vorab einen Betrag, und die Buchung wird erst bestätigt, wenn die Zahlung eintrifft. Dieses Tutorial führt von den Einstellungen der Location zu einer bezahlten, bestätigten Buchung und dann durch die Fälle, die im Betrieb zählen – ein Gast, der storniert, eine Erstattung und ein Slot, der vergeben wurde, während der Gast bezahlte.

Sie brauchen eine Location im Tarif Premium (Anzahlungen sind eine Premium-Funktion), ein verbundenes Stripe-Auszahlungskonto und einen veröffentlichbaren oder geheimen Schlüssel (Authentifizierung). Die Anzahlung ist eine Direktzahlung auf dem eigenen Stripe-Konto der Location; BookDinePlay sieht nie Kartendaten.

1. Anzahlungen einschalten

Drei Dinge müssen alle zutreffen, bevor eine Buchung eine Anzahlung verlangen kann:

  1. Das Auszahlungskonto kann verkaufen. Öffnen Sie in der Konsole Abrechnung → Auszahlungen und schließen Sie das Stripe-Onboarding ab; der Status muss „aktiviert“ lauten. Bis dahin antwortet die API mit payouts-not-connected, und das Widget zeigt keinen Anzahlungsschritt.
  2. Die Location nimmt Anzahlungen. Schalten Sie auf der Location-Seite unter Anzahlungen und Online-Zahlungen Online-Zahlungen akzeptieren und Anzahlungen bei Buchungen verlangen ein und wählen Sie Währung und einen Standard-Anzahlungsbetrag – den Betrag für jede Ressource, die keinen eigenen hat.
  3. Es gibt einen Betrag. Die Anzahlung einer Ressource gehört zu ihrer Preisgestaltung; eine Ressource ohne eigenen Betrag nimmt den Standard der Location. Gibt es keines von beiden, ist keine Anzahlung fällig.

Legen Sie dann in der Karte zur Stornoregel (Gäste können ihre Buchung selbst stornieren) fest, was passiert, wenn ein Gast eine bezahlte Buchung storniert:

Einstellung Ein Gast, der storniert
Der Gast muss Sie kontaktieren (keine Online-Stornierung) Kann nicht online stornieren; die Buchung bleibt, bis Sie sie bearbeiten. Das ist der Standard
Anzahlung vollständig erstatten Storniert online, und die Anzahlung geht sofort auf seine Karte zurück
Stornieren erlauben, Anzahlung einbehalten Storniert online und verliert die Anzahlung

Alles oben Genannte steht auch über die Betreiber-API und den MCP-Server zur Verfügung (venue_update, payouts_status, cancellation_policy_update).

2. Prüfen, ob die Location eine Anzahlung nehmen kann

Das Location-Profil sagt Ihrer Seite, ob der Schritt überhaupt angeboten werden soll. onlineDepositsAvailable ist nur true, wenn die Location Zahlungen und Anzahlungen nimmt, ihr Tarif sie enthält und ihr Auszahlungskonto verkaufen kann:

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. Mit Anzahlung buchen

Der Gast stimmt der Anzahlung zu, indem er mit der Buchung depositOptIn: true sendet. Treffen alle drei Bedingungen zu, kommt die Reservierung Pending zurück, mit depositRequired: true und dem depositAmount; der Slot bleibt solange reserviert.

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 );

Stimmt der Gast nicht zu oder fehlt eine Bedingung, ist die Buchung sofort Confirmed, und es ist keine Anzahlung im Spiel. Behandeln Sie depositRequired als einziges Signal: Leiten Sie es nicht aus den Einstellungen der Location ab.

4. Den Gast zum Bezahlen schicken

Legen Sie einen Payment Intent für genau den depositAmount der Buchung und ihre Währung an. Jeder andere Betrag wird mit 400 abgelehnt, damit ein Client nie bestimmt, was der Gast zahlt. Die Antwort enthält eine checkoutUrl: Schicken Sie den Gast dorthin. Das ist Stripes gehostete Seite, sodass keine Kartendaten Ihre Seite oder BookDinePlay berühren.

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 );

Die Anzahlung lässt sich einmal bezahlen, und nur solange die Buchung Pending ist. Eine stornierte, von der Location bestätigte oder abgeschlossene Buchung antwortet mit 409 und dem Grund deposit-not-payable; eine bereits bezahlte mit 409 deposit-already-paid.

Ein Gast kann einen Teil mit einem Geschenkgutschein bezahlen: Fügen Sie voucherCode hinzu, und der Gutschein zahlt, was er deckt, die Karte den Rest. Ein Gutschein, der alles deckt, öffnet keine Stripe-Seite und bestätigt die Buchung sofort (Gutscheine).

5. Die Zahlung bestätigt die Buchung

Zum Bestätigen müssen Sie nichts aufrufen. Meldet Stripe die Zahlung, speichert BookDinePlay die Zahlungskennungen an der Buchung und setzt sie auf Confirmed. Um dem Gast das Ergebnis zu zeigen, lesen Sie die Buchung mit dem cancelToken aus Schritt 3, was keinen Schlüssel braucht:

curl "https://api.bookdineplay.com/api/reservations/<cancelToken>"

Der status wird kurz nach der Zahlung Confirmed; zeigen Sie „Warten auf Zahlung“, bis es so weit ist, und bieten Sie den Zahlungslink erneut an, falls er nach Ablauf der Checkout-Sitzung noch Pending ist.

6. Wenn etwas schiefgeht

Die Zahlung trifft ein, nachdem der Slot weg ist. Eine ausstehende Buchung hält ihren Slot, aber eine Zahlung kann verspätet eintreffen – nachdem die Buchung storniert oder ihr Slot an jemand anderen vergeben wurde. Die Zahlung geht nie verloren: Die Buchung wird PaidButUnavailable. Sie hält keinen Slot, weil die andere Buchung der rechtmäßige Inhaber ist, und die Location löst sie in der Konsole auf, meist mit einer Erstattung. Eine Buchung in diesem Zustand lässt sich nicht bearbeiten, und es ist kein Status, den ein Aufrufer setzen kann.

Der Gast storniert. Mit der Stornoregel oben: keine Online-Stornierung antwortet 409 reservation-deposit-not-refundable und lässt die Buchung unberührt; vollständig erstatten erstattet zuerst und storniert danach, sodass eine fehlgeschlagene Erstattung (502 reservation-refund-failed) Buchung und Geld genau so lässt, wie sie waren; Anzahlung einbehalten storniert und behält sie. Lesen Sie canCancel und cancelNote der Buchung des Gastes, bevor Sie einen Stornieren-Knopf zeigen.

Die Location erstattet. Die Erstattung an der Reservierung in der Konsole (oder reservations_refund_deposit über MCP) gibt den Kartenanteil auf die Karte und den Gutscheinanteil auf den Gutschein zurück. Zweimal zu erstatten schadet nicht. Erstatten bleibt auch nach einem Downgrade möglich: Ein Gast, der bezahlte, während der Tarif es erlaubte, bleibt nie auf seinem Geld sitzen.

Eine Anfrage wird wiederholt. Senden Sie mit der Buchung einen Idempotency-Key, damit eine Wiederholung nach einem Timeout die ursprüngliche Reservierung zurückgibt (Reservierungen).

Ausprobieren

Zahlen Sie bei einer Location, deren Auszahlungskonto im Testmodus von Stripe verbunden ist, mit Stripes Testkarte 4242 4242 4242 4242, beliebigem künftigem Ablaufdatum und beliebiger Prüfziffer. Die Demo-Location läuft genau dafür im Testmodus.

Nächste Schritte