Entwicklerdokumentation

Geschenkgutscheine verkaufen und einlösen

Geschenkgutscheine einrichten, über Stripe verkaufen, damit Rechnung, Anzahlung oder Tickets zahlen, am Tisch einlösen und Erstattungen verstehen.

Ein Geschenkgutschein ist Geld, das ein Gast verschenken kann: Er wird online gekauft (oder von Hand ausgestellt), kommt per E-Mail mit einem Code an und wird am Tisch oder online gegen eine Rechnung, eine Anzahlung oder Tickets eingelöst. Dieses Tutorial behandelt das ganze Leben eines Gutscheins – Einrichtung, Verkauf, Einlösung, Erstattung – und wo jeder Schritt die API berührt.

Einen Gutschein von Hand auszustellen und ihn am Tisch einzulösen funktioniert in jedem Tarif. Der Online-Verkauf braucht Premium, ein verbundenes Stripe-Auszahlungskonto und eingeschaltete Online-Zahlungen. Mit einem Gutschein zu bezahlen und einen zu erstatten ist nie tarifgebunden.

1. Einrichten, was Sie verkaufen

In den Gutschein-Einstellungen der Konsole (oder mit voucher_settings_update über MCP) legen Sie fest:

  • Welche Arten Sie anbieten. Ein Betragsgutschein wird in Teilen verbraucht, bis das Guthaben aufgebraucht ist. Ein Prozentgutschein nimmt einen Prozentsatz von einer Rechnung, optional in Geld gedeckelt. Ein Artikelgutschein ist ein Menüartikel. Jedes Produkt hat einen Titel; Betragsprodukte haben einen Preis oder lassen den Käufer einen Betrag zwischen Minimum und Maximum wählen.
  • Wie lange ein Gutschein gültig ist: eine Anzahl Monate ab dem Ausstellungstag, ein festes Datum oder bis zum Ende eines Jahres. Ein online gekaufter Gutschein ist mindestens ein Jahr gültig; eine Regel, die weniger ergäbe, wird abgelehnt (voucher-validity-too-short), und der Online-Verkauf bleibt aus, bis eine Regel gesetzt ist (voucher-validity-not-set).
  • Bedingungen auf Englisch und Deutsch, an jedem Gutschein so gespeichert, wie sie bei der Ausstellung waren.
  • Online-Verkauf ein oder aus.

Betragsprodukte brauchen außerdem eine Umsatzsteuer-Einstufung, die Sie in den Einstellungen wählen.

2. Sehen, was verkauft wird

Ihre Seite fragt die Location, was sie gerade verkauft. Der Aufruf antwortet in jedem Tarif: Lässt sich online nichts kaufen, ist onlineSaleAvailable false, und unavailableReason nennt den Grund. Zeigen Sie Gästen für jeden Grund denselben Satz – sie können an der Einrichtung der Location nichts ändern.

curl

curl "https://api.bookdineplay.com/api/venues/your-venue/vouchers/offers" \
  -H "X-BookDinePlay-Key: bdp_pk_your_publishable_key" \
  -H "Origin: https://www.your-venue.example"

JavaScript

const offers = await client.voucherOffers();
if (!offers.onlineSaleAvailable) console.log(offers.unavailableReason);

C#

var offers = await client.GetVoucherOffersAsync("your-venue", cancellationToken);

PHP

<?php
$response = wp_remote_get( 'https://api.bookdineplay.com/api/venues/your-venue/vouchers/offers', [ 'headers' => [ 'X-BookDinePlay-Key' => BOOKDINEPLAY_SECRET_KEY ] ] );
$offers = json_decode( wp_remote_retrieve_body( $response ), true );

Der schnellste Shop ist das Widget – window.BookDinePlay.renderVoucherShop({ container, venueSlug, apiBaseUrl, publishableKey }) – oder in WordPress [bookdineplay_vouchers venue="your-venue"] (Gutschein-Shop).

3. Einen verkaufen

Der Käufer wählt ein Angebot und nennt Name und E-Mail, optional einen Beschenkten, eine Nachricht und ein Zustelldatum bis zu einem Jahr voraus. Der Checkout öffnet eine Stripe-Sitzung auf dem eigenen Konto der Location und liefert die Adresse, an die der Käufer geschickt wird. Senden Sie einen Idempotency-Key, damit eine Wiederholung denselben Checkout abspielt:

curl

curl -X POST "https://api.bookdineplay.com/api/venues/your-venue/vouchers/checkout" \
  -H "X-BookDinePlay-Key: bdp_pk_your_publishable_key" \
  -H "Origin: https://www.your-venue.example" \
  -H "Idempotency-Key: 4f9c2a1e8b7d4c3f9e0a1b2c3d4e5f60" \
  -H "Content-Type: application/json" \
  -d '{ "productId": "3f2a1b4c5d6e4f708192a3b4c5d6e7f8", "buyerName": "Ben Buyer", "buyerEmail": "ben@example.com", "recipientName": "Ada" }'

JavaScript

const checkout = await client.checkoutVoucher(
  { productId, buyerName: 'Ben Buyer', buyerEmail: 'ben@example.com', recipientName: 'Ada' },
  { idempotencyKey: crypto.randomUUID() }
);
window.location.assign(checkout.checkoutUrl);

C#

var checkout = await client.StartVoucherCheckoutAsync("your-venue",
    new StartVoucherCheckoutRequest { ProductId = productId, BuyerName = "Ben Buyer", BuyerEmail = "ben@example.com", RecipientName = "Ada" },
    idempotencyKey: Guid.NewGuid().ToString(), cancellationToken);

PHP

<?php
$response = wp_remote_post( 'https://api.bookdineplay.com/api/venues/your-venue/vouchers/checkout', [
    'headers' => [ 'X-BookDinePlay-Key' => BOOKDINEPLAY_SECRET_KEY, 'Content-Type' => 'application/json', 'Idempotency-Key' => wp_generate_uuid4() ],
    'body'    => wp_json_encode( [ 'productId' => $product_id, 'buyerName' => 'Ben Buyer', 'buyerEmail' => 'ben@example.com', 'recipientName' => 'Ada' ] ),
] );
$checkout = json_decode( wp_remote_retrieve_body( $response ), true );

Den Gutschein gibt es erst, wenn die Zahlung bestätigt ist. Dann wird er ausgestellt, sein Code erzeugt, und der Käufer – oder am Zustelltag der Beschenkte – erhält eine E-Mail mit dem Code und der Seite des Gutscheins. Die Antwort enthält nur eine Anzeigereferenz (GV-…), nie einen Code. Ein Verkauf, dessen Zahlung nie eintrifft, erzeugt keinen Gutschein und wird 30 Tage nach Ablauf seines Checkouts gelöscht.

Um einen Gutschein zu verschenken, ohne ihn zu verkaufen – ein Preis, eine Entschuldigung – oder um einen an der Kasse verkauften zu erfassen, stellen Sie ihn von Hand in der Konsole oder mit vouchers_issue aus. Das funktioniert in jedem Tarif; Sie geben an, wie er bezahlt wurde, oder dass er nicht bezahlt wurde (ein Aktions- oder Kulanzgutschein).

4. Einen Gutschein nachschlagen

Der Code ist ein Bearer-Credential wie bei einer Geschenkkarte: Wer ihn hat, kann ihn einlösen. Eine Gästeseite oder Ihre eigene kann ihn ohne Schlüssel nachschlagen, mit dem Code in jeder Form, die ein Gast tippen könnte, und erhält Art, Status, Guthaben und Ablauf – nie den Verlauf oder die Daten des Käufers. Jeder Code, der sich nicht auflösen lässt, antwortet dieselbe 404, sodass sich Codes nicht nacheinander durchprobieren lassen, und der Abruf ist auf 30 pro Minute und Client begrenzt:

curl

curl "https://api.bookdineplay.com/api/vouchers/K7QM-2XRP-9DTA-HV3N-8W4F"

JavaScript

const voucher = await client.voucher(code); // sends no key; null when unknown

C#

var voucher = await client.GetVoucherAsync(code, cancellationToken); // sends no key; null when unknown

PHP

<?php
$response = wp_remote_get( 'https://api.bookdineplay.com/api/vouchers/' . rawurlencode( $code ) ); // sends no key
$voucher = json_decode( wp_remote_retrieve_body( $response ), true );

Protokollieren Sie nie einen Code und setzen Sie nie einen in eine eigene URL: Der Abruf ist die einzige Route mit dem Code im Pfad, und BookDinePlay entfernt ihn aus seinen eigenen Logs.

5. Mit einem Gutschein bezahlen

Online fügt ein Gast den Gutscheincode einer Zahlung hinzu, die er ohnehin macht; lässt er ihn weg, ändert sich nichts. Dieselben drei Zahlungen nehmen ein optionales voucherCode:

Zahlung Akzeptierte Arten
Eine Tischrechnung (QR-Bestellung) Betrag, Prozent
Eine Reservierungs-Anzahlung (Anzahlungen) Betrag
Event-Tickets (Events) Betrag

Überall gelten dieselben Regeln. Der Gutschein zahlt zuerst, die Karte den Rest; sein Wert wird reserviert, während der Gast auf Stripes Seite ist, und abgebucht, wenn die Zahlung eintrifft, sodass er nicht zweimal ausgegeben werden kann, und eine vom Gast abgebrochene Reservierung läuft von selbst ab. Der Kartenanteil liegt nie unter Stripes Minimum (0,50 € in Euro): Bliebe weniger übrig, zahlt der Gutschein etwas weniger, sodass die Karte genau das Minimum zahlt. Ein Gutschein, der alles deckt, öffnet keine Zahlungsseite – die Zahlung schließt sofort ab, und die zurückgegebene Adresse ist die Erfolgsseite, sodass ein Client, der ihr einfach folgt, in beiden Fällen funktioniert. Ein Prozentgutschein ist ein Rabatt auf die ganze Rechnung, wird vor Betragsgutscheinen angewendet und ist auf das Fällige gedeckelt.

6. Am Tisch einlösen

Das Personal löst einen Gutschein in der Konsole ein: Code nachschlagen (scannen oder tippen), wählen, was er bezahlt, und bestätigen – bei einem Betragsgutschein den vollen Betrag oder einen Teil, bei einem Prozentgutschein den Rabatt, bei einem Artikelgutschein die Position, die er deckt. Über MCP: voucher_lookup, voucher_redeem und voucher_reverse_redemption. Eine Einlösung am Tisch lässt sich einmal rückgängig machen, innerhalb des Rückgängig-Fensters, es sei denn, das Personal gibt einen Grund an (voucher-undo-not-allowed); eine Online-Einlösung macht man stattdessen durch Erstatten der Zahlung rückgängig.

Die Einlösung am Tisch bleibt auch bei ausgesetztem Abonnement der Location möglich: Der Gast hat den Gutschein bereits bezahlt.

7. Erstattungen und was mit dem Guthaben passiert

Das Guthaben eines Gutscheins ist keine gespeicherte Zahl, sondern die Summe eines nur anhängbaren Kontobuchs über alles, was mit ihm geschah; eine Erstattung ändert also nie die Historie, sondern fügt einen Eintrag hinzu:

  • Eine Zahlung zu erstatten, an der ein Gutschein beteiligt war, bucht den Gutscheinanteil auf den Gutschein zurück und schickt nur den Kartenanteil auf die Karte zurück. Ein abgelaufener Gutschein wird auf 30 Tage ab der Erstattung verlängert, damit der Gast das Zurückgebuchte noch nutzen kann. Ein von der Location entwerteter Gutschein bleibt entwertet: Die Erstattung wird vermerkt, und die Location klärt den Wert direkt mit dem Gast.
  • Den Verkauf eines Gutscheins zu erstatten geht nur, solange der Gutschein ungenutzt ist, und es entwertet den Gutschein.
  • Entwerten, Ablauf ändern und die E-Mail erneut senden sind Aktionen der Location (vouchers_void, vouchers_change_expiry, vouchers_resend). Das Entwerten verlangt über MCP zuerst eine Bestätigung.

Nächste Schritte