L'objet garantie

Une garantie, c’est la carte attachée à une réservation : ce que le client a accepté, combien en a déjà été pris et jusqu’à quand il peut annuler sans être débité. Elle arrive comme champ guarantee d’une réservation et n’a pas de point de terminaison propre.

Champs

Le tableau ci-dessous est généré depuis la spécification OpenAPI et reste en anglais, comme la référence de l'API : noms de champs, valeurs d'énumération et descriptions viennent du backend. Une traduction serait une copie qui ment dès la première évolution du contrat.

objectstring

Valeurs possibles : guarantee

The object type: always guarantee.

kindstring

Valeurs possibles : imprint prepayment

What the guest is guaranteeing with.

• imprint: a saved card, charged only on a no-show or a late cancellation.
• prepayment: payment up front. Reserved: no guarantee is issued with it today.

statestring

Valeurs possibles : awaiting_card active expired released charged partially_charged charge_failed refunded disputed withdrawn

Where the guarantee is in its own lifecycle, which is separate from the booking’s status.

• awaiting_card: waiting for the guest to save a card, until expires_at.
• active: a card is saved and can be charged under the terms the guest accepted.
• expired: the guest did not save a card in time.
• withdrawn: the restaurant withdrew the request before a card was saved.
• released: the card was let go and nothing will be charged.
• charged: the full amount was charged.
• partially_charged: less than amount was charged.
• charge_failed: a charge was attempted and declined; it may be retried.
• refunded: money charged was refunded in full.
• disputed: the guest disputed the charge with their bank.

originstring

Valeurs possibles : online_booking staff_request waitlist_offer

How the card was asked for.

• online_booking: the guest saved it while booking in the restaurant’s widget.
• staff_request: the guest was sent a link to save it — by the restaurant, or because the booking was created through this API.
• waitlist_offer: the guest saves it to claim a place offered from the waitlist.

amountinteger

The most that can be charged, as the guest accepted it: in the minor unit of currency (cents), so 4000 is €40.00. Covers the whole party.

currencystring

ISO 4217 currency code of every amount on this object, e.g. EUR.

charged_amountinteger

How much has been charged so far, in minor units of currency. 0 when nothing has.

refunded_amountinteger

How much of charged_amount has been refunded, in minor units of currency. 0 when nothing has.

cardobjectnullable

null until the guest saves a card, and on a guarantee that never had one. Once a card is saved, its brand and the last four digits of its number; last4 can be null when the card network does not report it.

brandstring

The card network, as the payment processor reports it, e.g. visa.

last4stringnullable

The last four digits of the card number.

cancel_deadline_atstring (date-time)nullable

Until when the guest can cancel without being charged: ISO 8601 with the restaurant’s UTC offset. A cancellation after it may be charged. null means cancelling is always free and only a no-show is charged.

expires_atstring (date-time)nullable

While state is awaiting_card, the deadline for the guest to save a card, in the same format. null in every other state.

consented_atstring (date-time)facultatifnullable

When the terms the guest accepts were recorded, in the same format: when the card was saved in the booking widget, or when the request was sent for a card asked for by link. null on a widget booking whose card is not saved yet.

created_atstring (date-time)

When the guarantee was created, in the same format.

updated_atstring (date-time)

When the guarantee last changed, in the same format.

Son cycle de vie n’est pas celui de la réservation

state avance sur sa propre voie, distincte du status de la réservation. Le seul endroit où les deux se rejoignent est awaiting_guarantee : une réservation dans ce statut attend que le client enregistre une carte et sa garantie est awaiting_card jusqu’à expires_at. Le sens de chaque état est dans le champ ci-dessus.

Rien ici ne s’écrit depuis cette API

Il n’y a ni création, ni mise à jour, ni débit sur cette API. Une garantie apparaît parce que les règles du restaurant ont demandé une carte, ou parce qu’une réservation faite par votre clé est tombée sur un créneau qui en demande une, et elle est débitée, remboursée ou libérée en dehors de cette surface. Tous les montants sont dans l’unité mineure de currency et couvrent toute la table.

Un changement de garantie vous parvient comme un webhook reservation.guarantee_*, qui porte la réservation entière avec sa garantie.

Prendre un acompte déroule une réservation qui demande une carte au client.