Payment Intents

Ein Payment Intent hält fest, dass für eine Reservierung eine Anzahlung fällig ist, und liefert Ihnen, was ein Zahlungsanbieter zum Einziehen braucht. Die API sieht nie Kartennummern: Der Intent trägt ein clientSecret für den clientseitigen Ablauf des Anbieters oder eine checkoutUrl, zu der Sie den Gast schicken. Er folgt denselben Schlüsselregeln wie der Rest von /api/venues/**. Das einbettbare Widget ruft ihn aus dem Schritt „Pay deposit“ seiner Bestätigung auf, auf Wunsch mit einem Gutscheincode (Buchungsablauf); eine eigene Seite kann ihn mit einem veröffentlichbaren Schlüssel aufrufen, nach einer Reservierung mit depositRequired: true, genau wie unten gezeigt.

Endpunkte

POST /api/venues/{venueSlug}/payment-intents

Request-Body (Content-Type: application/json)

Antwort 201 Created

{
  "id": "79501bb3-1e05-4827-82ed-1086e889b3bd",
  "reservationReference": "BDP-KSQS7M",
  "amount": 20.00,
  "currency": "EUR",
  "status": "RequiresConfirmation",
  "provider": "fake",
  "clientSecret": "pi_fake_156d81370b0445619159a5028cc87bff_secret_82d75f634cbb4beaaf530982b18e492c",
  "createdAt": "2026-09-15T12:55:15.2187185+00:00",
  "checkoutUrl": null
}

Eine Anzahlung lässt sich einmal bezahlen, und nur solange die Buchung Pending ist und auf sie wartet. Der Betrag ist immer die eigene Anzahlung der Buchung, sodass nie ein Client bestimmt, was dem Gast berechnet wird.

Mit einem Gutschein

Fügen Sie voucherCode hinzu, und der Gutschein bezahlt, was er von der Anzahlung kann; die Karte bezahlt den Rest über denselben Checkout wie oben. Nur ein Betragsgutschein bezahlt eine Anzahlung. Der Wert des Gutscheins wird reserviert, solange der Gast auf der Stripe-Seite ist, und abgebucht, wenn die Zahlung eintrifft, sodass er nicht zweimal ausgegeben werden kann; bricht der Gast ab, verfällt die Reservierung von selbst. Der Kartenteil beträgt mindestens 0,50 €: Bliebe weniger übrig, zahlt der Gutschein etwas weniger, sodass die Karte genau 0,50 € zahlt (Mit einem Gutschein bezahlen).

Ein Gutschein, der die ganze Anzahlung deckt, öffnet gar keine Zahlung: Die Buchung ist sofort bestätigt, provider ist voucher, cardAmount ist 0, und checkoutUrl ist die Bestätigungsseite der Buchung. status ist succeeded oder paid_but_unavailable, wenn der Slot inzwischen vergeben wurde – dann klärt die Location die Buchung, und ihre Erstattung bucht den Wert auf den Gutschein zurück.

{
  "id": "0b6d2c51-9a7e-4f3b-8c1d-2e4f6a8b0c13",
  "reservationReference": "BDP-KSQS7M",
  "amount": 20.00,
  "currency": "EUR",
  "status": "succeeded",
  "provider": "voucher",
  "clientSecret": "",
  "createdAt": "2026-10-09T12:55:15.2187185+00:00",
  "checkoutUrl": "https://app.bookdineplay.com/booking/confirmed?ref=BDP-KSQS7M",
  "voucherAmount": 20.00,
  "cardAmount": 0.00
}

Mit einem Gutschein braucht die Location eingeschaltete Anzahlungen und einen Tarif, der sie enthält; Online-Zahlungen und ein Auszahlungskonto braucht es nur, solange ein Kartenteil übrig bleibt. Eine Erstattung – durch die Location, bei der eigenen Stornierung des Gasts, wenn die Regeln der Location erstatten, oder im Stripe-Dashboard der Location – bucht den Gutscheinteil auf den Gutschein und den Kartenteil auf die Karte zurück.

Fehler

Die Prüfungen von Schaltern, Tarif und Auszahlungskonto laufen in dieser Reihenfolge – eine Location mit ausgeschalteten Zahlungen bekommt zuerst das Schalter-Problem, selbst bei einem Tarif und Auszahlungskonto, die es sonst erlauben würden.

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" }'

const intent = await (await fetch('https://api.bookdineplay.com/api/venues/your-venue/payment-intents', {
  method: 'POST',
  headers: { 'X-BookDinePlay-Key': 'bdp_pk_your_publishable_key', 'Content-Type': 'application/json' },
  body: JSON.stringify({ reservationReference: reservation.reference, amount: reservation.depositAmount, currency: reservation.currency, voucherCode }) // voucherCode optional
})).json();
if (intent.checkoutUrl) location.assign(intent.checkoutUrl); // bei cardAmount 0 die Bestätigungsseite

var intent = await client.CreatePaymentIntentAsync("your-venue", new CreatePaymentIntentRequest
{
    ReservationReference = reservation.Reference,
    Amount = reservation.DepositAmount ?? 0m,
    Currency = reservation.Currency,
    VoucherCode = voucherCode // optional
}, cancellationToken);

Nächste Schritte

• Reservierungen – woher depositAmount kommt.
• Gutscheine – die Regeln, die jede Gutscheinzahlung teilt.
• Fehler – feature-not-in-plan und payouts-not-connected im Detail.
• .NET-SDK – CreatePaymentIntentAsync und die Ausnahmen, die es bei 403/409 wirft.