# Payments

A payment is money moving on a booking — what the guest actually pays, or what is returned to them.
Where a receipt is the document that records a successful payment, the payment is the underlying
movement itself, with richer detail about how and why it happened.

Payments are bound to bookings: a payment is made against a booking and then allocated to that
booking's invoices. Lavanda's billing system automatically requests payment for outstanding invoices
using the booking's preferred payment methods.

> This page explains the concepts and terminology. Example queries and mutations live in your
> Postman collection and Apollo — this guide does not repeat them.

## How payments relate to documents

- A successful payment is recorded as a **receipt**.
- A returned payment is recorded as a **refund note**.
- A refund that never reached the guest is cancelled with a **refund reversal note**, and the money
  goes back on the receipt.
- A payment that is voided or taken back (for example after a lost dispute) is recorded as a
  **payment reversal note**.
- The payment carries context the document does not always show — such as what it was for (for
  example, an advance rent payment) and how it was taken.

## Taking a payment

Lavanda can set up a payment on a booking for a given amount and currency. The guest then completes
it through a secure card flow. A payment can be marked for a specific purpose, such as an **advance
rent payment (ARP)** or a **security deposit**.

API: `payments.paymentIntent.create`

## Managing payment gateways

A workspace can connect more than one payment gateway, but only one gateway is primary.
The primary gateway is used when a payment flow does not select a gateway explicitly.

Use `payments.paymentGateway.makePrimary` to make a connected gateway primary. This also removes the
primary designation from any other gateway in the workspace. Calling it again with the current
primary gateway is safe and leaves the gateway primary.

Use `payments.paymentGateway.disconnect` to stop using a gateway. A primary gateway must be replaced
before it can be disconnected, unless it is the workspace's only connected gateway, for example when a
customer leaves the product. For a Stripe gateway this also revokes the platform's access to the Stripe
account, so no further payments can be taken through it. It is refused when another workspace uses the
same Stripe account, because revoking would stop that workspace's payments too, and for a Flywire
gateway, which has no revoke. Once access is revoked, refunds through that account fail as well.
Calling it again for an already disconnected gateway is safe and leaves the gateway disconnected.

Both mutations accept the gateway's opaque `ID` unchanged and return the provider-specific payment gateway,
including its updated `status` and `primary` fields.

## Saving a payment method and collecting automatically

A booking can hold a saved payment method — a **mandate** — so future payments can be taken without
asking the guest each time, and Lavanda can collect due payments (advance rent, instalments)
automatically. This is covered in full on
[Recurring payment methods (mandates)](/finance-and-accounting/payments/recurring-payment-methods/).

## Seeing the payments on a booking

You can view all payments on a booking and what state each is in:

- **Due** — expected but not yet collected
- **Success** — collected
- **Failed** — collection attempt did not succeed
- **Canceled / Expired** — not collected
- **Refunded** — returned to the guest
- **Disputed / Dispute reversed** — a chargeback was raised, or lost

A refund that is later reversed (because the provider failed it, or because it was reversed by hand)
shows as **Failed**, tagged **Refund failed** with the provider's error. The full reason and the
failure date are on the refund reversal note.

Each payment also shows **what it was for** (reservation, deposit, ARP, down payment, fee, …), **how
it was taken** (card, direct debit, cash, bank transfer, …), **where it came from** (a payment
gateway, an OTA channel, or recorded manually), and **who paid**.

API: `payments.payments` (all payments) · `payments.refunds` (refunds only)

## Refunds

A payment can be refunded in full or in part. A refund is always linked back to the original payment
it relates to, and is recorded as a **refund note**. The refund note is issued as soon as the refund
is raised. Lavanda doesn't wait for the payment provider to confirm it.

For refunds made through Stripe (card, pay by bank, MB Way, and BACS and SEPA Direct Debit), Lavanda
then tracks the provider's outcome. The refund is **pending** until Stripe confirms it **succeeded**
or reports that it **failed**. If it fails, Lavanda issues a refund reversal note on its own, and the
money is back on the receipt for your team to return another way. Refunds aren't retried
automatically. See [Refunds and reversals](/finance-and-accounting/payments/refunds-and-reversals/).

**Direct Debit refunds.** BACS and SEPA Direct Debit payments can be refunded once the debit has
**settled**. Debits that haven't settled yet, or that failed, were reversed or are disputed, can't be
refunded. Direct Debit refunds are available on workspaces where refund reversals are switched on.

API: `payments.payment.refund`

## See also

- [Receipts](/finance-and-accounting/document-types/receipts/) — the document recording a successful payment.
- [Moving payments between bookings](/finance-and-accounting/payments/moving-payments/) — reassign a payment to a different booking.
- [Recurring payment methods (mandates)](/finance-and-accounting/payments/recurring-payment-methods/) — saved cards and direct
  debits, and automatic collection.
- [Instalment plans](/finance-and-accounting/payments/instalment-plans/) — scheduled payment plans on a booking.
- Payments are bound to bookings — see [Bookings](/bookings/bookings/).