# 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](/finance-and-accounting/integrations/ar-payments-api/) 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](/finance-and-accounting/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](/finance-and-accounting/integrations/ar-payments-api/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](/finance-and-accounting/payments/) — payment states and what each payment shows.
- [Instalment plans](/finance-and-accounting/payments/instalment-plans/) — schedules that automatic collection pays down.