Vouchers

Creates a voucher worth amountCents, narrowed to one room when roomSlug is given (it must be a room of the key's venue). With collectPayment true (the default) the voucher is pending_payment and the answer carries the PaymentIntent's clientSecret and the stripePublishableKey to confirm it with Stripe.js; the voucher becomes active when Stripe reports the payment succeeded, which you read by polling GET /api/embed/vouchers/{code}. A failed card attempt leaves it pending for the buyer to retry. With collectPayment false the venue took the money itself: the voucher is active at once, nothing is charged and clientSecret and stripePublishableKey are null; that needs a key granted "May manage vouchers" (403 API_KEY_NOT_PERMITTED otherwise). No service fee is charged on a sale. When buyerEmail is given and notifyBuyer is true (the default) MyEscapeRoom emails the buyer the voucher (venue, code, value, room if narrowed, expiry date and a link to book) as soon as it is active: when the payment succeeds, or right away with collectPayment false. Send notifyBuyer false when your site sends its own email. An optional invoice (the same "Need an invoice?" object as POST /api/bookings: buyerKind, name, vatNumber for an EU business, address, postalCode, city, country, email) asks MyEscapeRoom to invoice the sale: once the payment succeeds, MTEC Games VOF issues the venue's invoice in its company's name (the sale is a single-purpose voucher, so the VAT falls due when it is sold), for the full amount, with no service fee invoice because a sale has none, and emails it to the buyer (over Peppol as well to a Belgian business that receives them). It is only for a sale charged through MyEscapeRoom at a Belgian venue: with collectPayment false it is refused (422 INVOICE_NOT_AVAILABLE), because a venue that took the money invoices it itself. If the venue's invoicing profile is not complete, or the voucher is for any room and the venue's rooms are taxed at different VAT rates, the venue is emailed the buyer's details to issue the invoice itself instead. Ask later with POST /api/embed/vouchers/{code}/invoice-request.

Poll this after the buyer confirms the payment until status is active. redemptions lists every draw against the balance, newest first: { amountCents, bookingRef (null for a host redeeming in person), reversed, createdAt }. A draw is reversed once it was given back, because its booking was cancelled or released. invoice is where the sale's invoice stands: { available (charged through MyEscapeRoom, at a Belgian venue, not cancelled), requested, state (none, pending — asked for and on its way, issued, or venue_issues — the venue was emailed to invoice it itself), number (the invoice number once issued), deadline (ISO; null until the payment succeeded), canRequest }. The PDF is emailed to the buyer, never served through this API.

For a buyer who asks after the sale. The body is the same invoice object as POST /api/embed/vouchers. Only for a sale charged through MyEscapeRoom at a Belgian venue (a voucher sold with collectPayment false, or cancelled, is 422 INVOICE_NOT_AVAILABLE), until 23:59 Brussels time on the 15th of the month after the payment (422 INVOICE_DEADLINE_PASSED); a sale still waiting for its payment can be asked for already. One request per voucher: a second is 409 INVOICE_ALREADY_REQUESTED, and it cannot be corrected through the API. While the voucher is still pending_payment any key may call it (the buyer's checkout); once it is active the key must be granted "May manage vouchers" (403 API_KEY_NOT_PERMITTED), because the gift's recipient holds the code too and a request cannot be corrected. The answer is the invoice state only, never the buyer's details. The invoice is issued shortly afterwards and emailed to the buyer; poll GET /api/embed/vouchers/{code} for its invoice.state.

A voucher still pending_payment is cancelled together with its payment. Whether it is unpaid is asked of Stripe, not read from the voucher: a payment that went through before its webhook landed counts as paid (409 VOUCHER_PAID; poll until the voucher is active), one still processing is 409 PAYMENT_PROCESSING (try again later), and Stripe not answering is 502 STRIPE_ERROR with nothing cancelled. An active voucher the venue sold with collectPayment false is cancelled while nobody has spent any of it (409 VOUCHER_IN_USE once they have); that needs a key granted "May manage vouchers" (403 API_KEY_NOT_PERMITTED). An active voucher that was paid online is never cancelled here (409 VOUCHER_PAID): refunding a sold voucher is not offered. Cancelling a voucher that is already cancelled is a no-op that answers 200.