Recurring payment methods (mandates)

A mandate is a payment method saved against a booking so that future payments can be taken without asking the guest each time. It underpins automatic collection of advance rent, instalments, and any other scheduled charge.

A mandate is one of:

• a stored card, or
• a direct debit authorisation — BACS (UK bank account) or SEPA (IBAN).

This page explains the concepts. Field-level inputs and example mutations live in your Postman collection and Apollo — see the AR & Payments API integration page.

Lifecycle

A mandate moves through three states:

State	Meaning
Pending	Being set up — awaiting the guest to authorise, or a bank confirmation.
Active	Ready to use for taking payments.
Cancelled	No longer usable. Terminal.

Setting up a mandate

Create a mandate on a booking with payments.paymentMandate.create. How the guest authorises it is the collection mode, chosen to suit the flow:

• Self-hosted — you collect the details in your own UI (returns a client secret to confirm).
• Embedded — an embedded checkout session.
• Redirected — the guest is sent to a hosted page and returned afterwards.
• Provider email link — a link is emailed to the guest to set the method up themselves.
• Booking checklist — surfaced as a step in the guest’s booking checklist.

You can change how an existing mandate is collected with payments.paymentMandate.amendCollectionMode, and finalise a direct-debit setup that uses a verification token with payments.paymentMandate.verifyToken.

BACS and SEPA mandates expose a url for completing the direct-debit authorisation; card mandates carry the card brand and last details instead.

Taking a payment from a saved mandate

Once a mandate is Active, request a payment against the booking with payments.paymentRequest.create. A request is fulfilled by one of:

• payment_mandate — charge the saved card or direct debit directly.
• sepa — collect via SEPA direct debit.
• email_link — email the guest a payment link. Set create_mandate on an email-link request to also save the method for future use while the guest pays.

Automatic recurring collection

Where enabled for a workspace, Lavanda collects due payments automatically (for example advance rent or instalments). It attempts the available methods in order of reliability:

1. Direct debit (an active BACS/SEPA mandate)
2. Saved card (an active card mandate)
3. Payment link emailed to the guest as a fallback

You see the outcome as new payments appearing on the booking, each moving through the usual due → success / failed states — see Payments.

Viewing a booking’s mandates

Query payments.paymentMandates to list the mandates on a booking. The filter is booking-scoped (bookingId is required; the workspace is derived from the booking). Each mandate returns its status, paymentMethodType, and the underlying card or bank-account details.

The v1.payments.payment_method.created and .updated webhooks tell you when a mandate is set up or changes — see Payments and payment methods.

API at a glance

Action	API
Create a mandate	payments.paymentMandate.create
Change collection mode	payments.paymentMandate.amendCollectionMode
Verify a direct-debit token	payments.paymentMandate.verifyToken
Cancel a mandate	payments.paymentMandate.cancel
List a booking’s mandates	payments.paymentMandates
Request a payment (mandate / SEPA / link)	payments.paymentRequest.create
One-off payment (card / pay-by-bank / MB WAY)	payments.paymentIntent.create

See also

• Payments — payment states and what each payment shows.
• Instalment plans — schedules that automatic collection pays down.