Deposit Collection by Amount Due & Coverage Handling for StayNtouch – Duve

Overview

If your property runs on StayNtouch, Duve now asks each guest for the exact amount that is actually routed to their own bill, instead of treating a reservation as either fully collectable or fully covered.

Duve already reads StayNtouch's routing instructions to tell a guest-paid stay ("Collect") apart from a stay covered by an OTA-issued virtual credit card ("Agent with VCC"), and already excludes specific rate plans from guest collection. What this feature adds is the ability to request the right payment amount based on the real amount due, including partial and deposit amounts.

In practice, Duve does three things:

Reads the guest's true amount due from StayNtouch for every reservation.
Works out how the stay is covered: by the guest, by an agent/OTA virtual credit card, or split between the two.
Requests from the guest only the portion routed to the guest's bill, and reflects that same amount in payment messaging and automation.

Where the amount comes from depends on timing:

Before check-in, while the reservation is still in Reserved status, Duve reads the deposit schedule on the reservation in StayNtouch and adds up every due date on it. Pre-arrival the guest bill is usually empty, but the deposit schedule still exposes the amount owed.
From check-in onward, and after check-out, Duve works the amount out from the reservation's bills. Only the guest's own bills count. Travel agent and company bills are excluded.
Nights that have not been posted to a bill yet are added from the reservation's stay dates, based on which bill the room charge and the city tax land on.

Who this is for

Property and front desk teams at hotels running StayNtouch as their PMS, who rely on Duve to collect payment from guests.

Applies to

The StayNtouch PMS integration only. Other PMS integrations have their own balance and exclusion logic.
Properties that use Duve payment collection (payment for stay, additional holds, and check-out payment).
Enabled by default on the backend. There is no UI toggle to turn it on or off, because StayNtouch currently has a single active property family in production.

Use cases

You stop manually handling payment for OTA-covered bookings, because Duve requests the correct guest amount by itself.
You keep agent and OTA balances off the guest bill, charging the guest only their routed share.
A guest whose stay is paid by city tax only, with the accommodation covered by an OTA virtual credit card, is asked for the city tax and nothing more.
A guest whose stay is fully covered by an agent virtual credit card is never asked to pay, so they trust that their OTA-covered booking was recognized.
A guest paying for their own stay is asked for the full amount due on their bill, including deposit amounts before arrival.
A guest who pays a deposit before arrival is asked for the rest of the stay once they check in, without anyone re-entering the figure.

Before you start

Your StayNtouch sync source must be connected in Duve, with the correct hotel ID and region, and reservations must be syncing.
A payment provider must be configured for the company or brand in Duve. Without it, Duve has no way to request or capture a guest payment.
A deposit rule must be set on the reservation in StayNtouch for pre-arrival collection to work. The deposit schedule is the only place Duve can read a pre-arrival amount from, since the guest bill is still empty at that point.
Routing in StayNtouch must be accurate, and each bill must carry the right entity type. Duve treats a bill as the guest's when its entity type is Guest or is not set, and excludes bills whose entity type is Travel Agent or Company.
Rate plans that should never be charged to the guest (OTA-prepaid rate plans, for example) must be listed in the integration's excluded rate plans configuration. This list is maintained by the Duve team on the sync source, not in the console UI.
Add-ons booked on the reservation in StayNtouch count toward the amount due before arrival, so their prices in StayNtouch need to be correct.

How it works

You do not need to set anything up in the Duve console. The logic runs automatically on every StayNtouch reservation sync. This is what happens behind the scenes:

Duve resolves the reservation's rate plan. It uses the rate plan code or name already stored on the reservation, and if neither exists it fetches the rate from StayNtouch and uses the rate code or name.
Excluded rate plans are treated as paid by the agent. If the resolved rate plan appears in the excluded rate plans list, the room rate is dropped to zero and Duve does not call the deposit endpoint at all. Add-ons booked on the reservation are still listed as extras, so a guest on an OTA-prepaid rate can still be charged for a breakfast they added.
Before check-in, Duve reads the deposit schedule. It adds up the amount on every due date, so a schedule split across several dates is collected in full, and a partial deposit policy asks only for the part that is due. The result is capped at the stay price, so a deposit schedule set above the stay never asks for more than the stay.
Add-ons are counted once each, at the right price. An add-on priced per night is multiplied by the number of nights. An add-on priced per adult, per child, or per person is multiplied by the matching guest count on the reservation. An add-on priced per room or at a flat rate is counted once whatever the party size. Quantity is applied on top. The add-on total is then taken out of the deposit figure so the same money is not counted twice.
From check-in onward, Duve reads the bills instead. It no longer calls the deposit endpoint. It reads every bill on the reservation, not only the first, keeps the charges on the guest's bills, and drops the travel agent and company bills.
Room and city tax are tracked separately, because they can land on different bills and be posted at different times. A night's room counts as posted once its positive room lines across all bills reach half the night price, so a night that StayNtouch splits into two lines still counts as one night, while a small fee on its own does not make a night look posted.
Nights not posted yet are added from the stay dates, but only for the side that the guest is actually carrying. If the room is landing on the guest bill, the coming nights' room charges are added. If the city tax is landing on the guest bill, the coming nights' city tax is added. A night that was moved to the agent bill, or whose room the agent bill also holds, is not billed to the guest.
Duve hides the covered portion. Any amount routed to an agent or company bill is never shown to the guest.
Guards stop a wrong figure from reaching the guest. Duve never asks for more than the stay plus its extras, never asks for a negative amount when the guest has overpaid, and never lets an upsell the guest already paid for reduce what is owed on the stay itself.
Duve requests the guest's share and reflects the same amount in payment messaging and automation, so what the guest reads matches what they are asked to pay.
Duve posts the collected payment back to StayNtouch as a credit card payment on the reservation, and adds a note to the reservation with the payment details.
When something cannot be read, Duve holds still rather than guessing. If the deposit call fails, comes back empty, or returns an amount that is not a number, Duve keeps the last amount it synced for that reservation. The same applies on check-in day when an agent or company bill exists but no night has been posted yet. A reservation that was never priced before falls back to the full stay price. Duve records every one of these cases, so your Duve contact can tell you which reservations were affected and why.

The calls Duve makes to StayNtouch for each reservation, including the deposit call, are recorded in the request logs. That is where to look when you need to trace how an amount was reached.

Host experience

There is nothing to configure, enable, or maintain in the console for this behavior. It is on by default for StayNtouch connections.
Reservations that are fully covered by an agent virtual credit card simply never generate a guest payment request, so they stop appearing in your manual follow-up list.
Partially covered reservations show the guest's routed share as the requested amount, not the full stay value.
Payments the guest makes through Duve are pushed back to the reservation in StayNtouch, with a reservation note recording the charge.
Day-use stays and checked-out reservations are read the same way as in-house ones, so a late charge added after check-out still reaches the guest's balance.

Guest experience

Guests are asked to pay exactly what they owe on their own bill, including deposit amounts before arrival.
A guest whose stay is fully covered by an agent or OTA virtual credit card is not asked to pay anything.
On a split reservation, the guest sees and pays only their routed portion. The amount covered by the agent or OTA is hidden from them entirely.
Payment messaging and automation show the same guest-owed amount, so a guest never reads one figure in a message and sees another in the Guest app.
A guest who paid a deposit before arrival is asked only for the remainder once the stay begins.

Troubleshooting

The guest was not asked to pay anything. Check whether the stay is fully covered by an agent virtual credit card, whether the reservation's rate plan is on the excluded rate plans list, or whether the amount due could not be determined. All three cases intentionally result in no payment request.
The guest was asked for the wrong amount. Check the routing instructions and the settler on the bill in StayNtouch. Duve only collects what StayNtouch routes to the guest's bill, so a mis-routed charge in the PMS produces a wrong amount in Duve.
The amount has not moved since yesterday. This is what Duve does on purpose when it cannot read the figure. Check that the reservation has a deposit rule in StayNtouch, then open the reservation's request logs in Duve and look at the deposits call. If that call is failing or coming back empty, contact Duve support with the reservation number.
The pre-arrival amount looks too high or too low by the price of an add-on. Compare the add-on's price and its pricing type in StayNtouch against the deposit schedule. An add-on priced per person is counted once per guest, so a wrong pricing type in the PMS shifts the amount.
The amount looks out of date. The amount is refreshed when the reservation syncs from StayNtouch. If a charge was posted in the PMS moments ago, wait for the next sync before comparing figures.
Nothing was pushed back to StayNtouch after the guest paid. Confirm the payment actually completed on the provider side, then check the reservation's API logs in Duve for the payment push.

Restrictions & Limitations

There is no toggle. The behavior is enabled by default on the backend and cannot be switched on or off per property from the console.
Collection is always based on the guest's own bills. Amounts routed to an agent or company bill are never shown to the guest and are never collected by Duve.
When the amount due cannot be read, Duve keeps the last synced amount rather than recalculating. That amount can be stale until the next successful sync.
Before check-in, the amount comes from the deposit schedule only. A reservation with no deposit rule in StayNtouch has nothing for Duve to read pre-arrival.
The excluded rate plans list is maintained by the Duve team on the sync source, so adding or removing a rate plan requires a request to Duve.
This logic is specific to StayNtouch. Other PMS integrations handle balances and OTA-prepaid exclusions separately.

Tips & Tricks

Fix routing in StayNtouch before your pre-arrival messaging goes out. Duve reads the PMS at sync time, so correcting routing early is what prevents a wrong request rather than a refund afterwards.
Remember that the guest bill is usually empty before arrival. If you are reconciling a pre-arrival amount, compare it against the deposit information on the reservation, not against the folio.
When a new OTA-prepaid rate plan is introduced, send it to Duve for the excluded rate plans list at the same time you create it in StayNtouch.
If you want an upsell to reach StayNtouch as a reservation add-on rather than a folio charge, turn on "Sync as package/add-on" in the upsell's Advanced section and put the StayNtouch add-on ID in the Billing Identifier. It is available for custom services, early check-in, late check-out, and menu products. Room upgrades keep their own flow. Keep the price identical in both systems, because StayNtouch posts its own add-on price.

FAQs

Q: Do I need to turn this on for my property?

A: No. It is enabled by default on the backend for StayNtouch connections, and there is no toggle in the console.

Q: Where does Duve get the amount before the guest arrives?

A: From the deposit schedule on the reservation in StayNtouch. Duve adds up every due date on the schedule. The guest bill is usually empty pre-arrival, but the deposit schedule still exposes the amount owed.

Q: Where does Duve get the amount during the stay?

A: From the reservation's bills. Duve reads every guest bill on the reservation, excludes travel agent and company bills, and adds the nights that have not been posted yet from the reservation's stay dates.

Q: How does Duve know which charges belong to the guest and which belong to the agent?

A: From the entity type on each bill. A bill marked as Guest, or with no entity type at all, is the guest's. A bill marked as Travel Agent or Company is excluded from what the guest is asked to pay, and is hidden from the guest.

Q: What happens when a stay is fully covered by an agent or an OTA virtual credit card?

A: Duve requests nothing from the guest, and the guest is not prompted to pay in the Guest app or in payment messaging.

Q: What happens on a split reservation?

A: Duve requests only the portion routed to the guest's bill. A common example is the guest paying the city tax while the agent covers the room.

Q: What happens if Duve cannot work out the amount due?

A: Duve keeps the last amount it synced for that reservation rather than guessing a new one. A reservation that was never priced before falls back to the full stay price, so it is never left at zero by accident.

Q: Can Duve ask for a partial amount instead of the full balance?

A: Yes. That is the core of this feature. Deposit and partial amounts are supported, not only the full balance.

Q: Can the guest ever be asked for more than the stay is worth?

A: No. The amount is capped at the stay plus its extras, even when the deposit schedule in StayNtouch is set above the stay price, and it never goes negative when the guest has overpaid.

Q: How are add-ons counted before arrival?

A: Once each, at the price StayNtouch holds. Per-night add-ons are multiplied by the nights, per-adult, per-child, and per-person add-ons by the matching guest count, and per-room or flat add-ons are counted once. The add-on total is taken out of the deposit figure so nothing is counted twice.

Q: Will the amount in the guest's message match what they are asked to pay?

A: Yes. Payment messaging and automation reflect the same guest-owed amount that Duve requests.

Q: Does the guest ever see the amount covered by the agent or OTA?

A: No. Any amount routed to an agent or company bill is hidden from the guest.

Q: A rate plan should never be charged to the guest. How do I exclude it?

A: Ask your Duve contact to add the rate plan code to the excluded rate plans list on the StayNtouch sync source. Once excluded, the room rate for reservations on that rate plan is not collected from the guest. Add-ons the guest booked are still charged.

Q: Does the guest's payment reach StayNtouch?

A: Yes. Duve posts the payment back to the reservation in StayNtouch as a credit card payment and adds a note with the payment details.