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
Section titled “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
Section titled “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
Section titled “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
Section titled “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).
Seeing the payments on a booking
Section titled “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
Section titled “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.
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
Section titled “See also”- Receipts — the document recording a successful payment.
- Moving payments between bookings — reassign a payment to a different booking.
- Recurring payment methods (mandates) — saved cards and direct debits, and automatic collection.
- Instalment plans — scheduled payment plans on a booking.
- Payments are bound to bookings — see Bookings.