Deposit & Payment Rules

Overview

When a booking is created in Kaptio, the platform generates a payment schedule — the set of payment milestones that tells the customer when to pay and how much. The schedule is built from rules you configure, and it supports deposits, final balance payments, percentage-based or fixed amounts, and per-passenger calculations.

Payment schedules are generated automatically by the PaymentScheduleFactory, which reads your configured rules, applies date logic, calculates amounts, and produces the schedule records attached to the itinerary. Understanding how these rules interact is essential for getting deposit and balance amounts right.

This guide covers the configuration objects, how the schedule generation logic works, and how to troubleshoot common issues.

Prerequisites

Before configuring payment rules, ensure the following are in place:

Channels set up with the correct currency and commercial settings
Payment gateway configured if you are collecting payments through Edge Pay (Edge Pay Integration Guide)
Admin or Finance Manager access in Kaptio

Part 1: How Payment Schedules Work

The Generation Flow

When a booking is saved, the PaymentScheduleFactory runs through this sequence:

Read rules — loads all PaymentScheduleRule__c records linked to the active PaymentScheduleConfiguration__c
Apply dates — resolves each rule’s due date based on the date type and offset
Evaluate deposit suppression — determines whether a deposit rule should be created or skipped based on the AlwaysCreateDepositRule__c setting
Calculate amounts — applies the charge type (percentage, fixed, or per-passenger) to produce the monetary value for each schedule line
Create schedule records — writes PaymentSchedule__c records to the itinerary

Deposit vs. Final Balance

Every payment schedule has up to two types of rule:

Type	Label in UI	Purpose
Deposit	”Payment”	The initial amount due — typically collected at or shortly after booking
Final Balance	”Final Balance”	The remaining amount — typically due before travel

The Type__c field on PaymentScheduleRule__c controls which type a rule represents. The “Deposit” value displays as “Payment” in the Kaptio UI.

Part 2: Payment Schedule Configuration

PaymentScheduleConfiguration (KaptioTravelPaymentScheduleConfigurationc)

This is the parent object that groups a set of payment rules together. Each configuration can contain multiple deposit and final balance rules.

Field	API Name	Description
Always Create Deposit Rule	`KaptioTravel__AlwaysCreateDepositRule__c`	Checkbox. When checked, a deposit rule is always created on the schedule — even if the deposit due date falls on or after the final balance due date. If the deposit due date has already passed, it is adjusted to today. When unchecked, the deposit rule is only created if its due date falls before the final balance due date.

The AlwaysCreateDepositRule__c setting is the most important behavioral toggle on this object. It determines whether bookings made close to the travel date still show a deposit line or skip straight to the full balance.

When to enable Always Create Deposit Rule:

You always want a deposit line on the payment schedule, regardless of timing
Your finance process requires a distinct deposit transaction even for late bookings
You use Edge Pay and want the deposit/balance split to always appear on the payment page

When to leave it disabled:

Late bookings should show only the full balance amount
You want the schedule to simplify automatically when the deposit window has passed

Part 3: Payment Schedule Rules

PaymentScheduleRule (KaptioTravelPaymentScheduleRulec)

Each rule defines a single payment milestone — either a deposit or a final balance line.

Core Fields

Field	API Name	Type	Description
Rule Name	`KaptioTravel__RuleName__c`	Text	Display name for the rule
Type	`KaptioTravel__Type__c`	Picklist	`Deposit` (labeled “Payment”) or `Final Balance`
Description	`KaptioTravel__Description__c`	Text Area	Free-text description of the rule’s purpose
Configuration	`KaptioTravel__PaymentScheduleConfiguration__c`	Lookup	Parent configuration record

Amount Fields

Field	API Name	Type	Description
Charge Type	`KaptioTravel__ChargeType__c`	Picklist	How the amount is calculated: `Percentage`, `Fixed`, or `Per Person`
Value	`KaptioTravel__Value__c`	Number	The amount or percentage — interpretation depends on Charge Type
Currency (Fixed)	`KaptioTravel__CurrencyFixed__c`	Text	Currency code for fixed amounts (ISO 4217)
Minimum Deposit	`KaptioTravel__MinimumDeposit__c`	Currency	Floor amount when Charge Type is Percentage — if the calculated percentage is below this value, the minimum is used instead

Date Fields

Field	API Name	Type	Description
Date Type	`KaptioTravel__DateType__c`	Picklist	The reference point for calculating the due date
Days Offset	`KaptioTravel__DaysOffset__c`	Number	Number of days before or after the Date Type reference point

Date Type values:

Date Type	Reference Point	Typical Use
After Booking	The date the booking was created	Deposit due X days after booking
Before Travel	The travel start date	Final balance due X days before departure
After Travel	The travel end date	Post-travel charges
Before/After Package Departure	The package departure date	Rules tied to the departure calendar

Other Fields

Field	API Name	Type	Description
Required For Deposit Date	`KaptioTravel__RequiredForDepositDate__c`	Checkbox	When checked, this rule requires a passenger-level deposit date to be present before it applies

Part 4: Charge Type Behavior

Percentage

The deposit or balance is calculated as a percentage of the total booking value.

Value__c = the percentage (e.g., 30 for 30%)
If the calculated amount is below MinimumDeposit__c, the minimum is used instead

Example: A 30% deposit rule with a minimum deposit of $500 on a $1,200 booking produces a deposit of $500 (because 30% of $1,200 = $360, which is below the $500 minimum).

Fixed

The deposit or balance is a flat currency amount, regardless of booking value.

Value__c = the fixed amount
CurrencyFixed__c = the currency code for the amount

Example: A fixed deposit of $750 USD applies the same amount to every booking under this configuration.

Per Person

The amount is calculated per passenger on the booking.

Value__c = the per-person amount
The PaymentScheduleFactory multiplies this by the passenger count during the applyAmountsPreparation step

Example: A per-person deposit of $200 on a booking with 4 passengers produces a $800 deposit.

Part 5: Date Logic and Deposit Suppression

How Due Dates Are Calculated

Each rule’s due date is resolved by combining the Date Type reference point with the Days Offset:

Due Date = Reference Date ± Days Offset

For example:

Before Travel, 60 days offset → due date is 60 days before the travel start date
After Booking, 3 days offset → due date is 3 days after the booking creation date

Deposit Suppression

When a booking is created close to the travel date, the deposit due date may fall on or after the final balance due date. In this scenario, the AlwaysCreateDepositRule__c setting on the configuration determines what happens:

Setting	Behavior
Always Create Deposit Rule = true	Deposit rule is still created. If the due date has already passed, it is adjusted to today.
Always Create Deposit Rule = false	Deposit rule is suppressed — only the final balance appears on the schedule.

Example scenario:

Final balance rule: 45 days before travel
Deposit rule: 3 days after booking
Travel date: April 15
Booking date: March 10 (36 days before travel)

The deposit due date would be March 13. The final balance due date is March 1 (45 days before April 15). Since the deposit due date (March 13) is after the final balance due date (March 1):

With Always Create Deposit Rule enabled: both lines appear, and the deposit due date may be adjusted to today if it has passed
With Always Create Deposit Rule disabled: the deposit rule is suppressed and only the final balance is shown

Part 6: Validation Checklist

Before activating a payment schedule configuration, verify the following:

Rule Setup

At least one Deposit rule and one Final Balance rule exist
Each rule has a valid Charge Type, Value, and Date Type
Days Offset values produce sensible due dates for your typical booking-to-travel window
Minimum Deposit is set on percentage rules if you need a floor amount
CurrencyFixed is set on any Fixed charge type rules

Date Logic

Final balance due date falls after the deposit due date for typical bookings
AlwaysCreateDepositRule__c is set according to your business requirement (always show deposit vs. suppress when too late)
Rules with RequiredForDepositDate__c checked have passenger deposit dates populated

Per-Passenger Rules (if used)

Charge Type is set to Per Person
The per-person amount in Value__c is correct
Passenger counts on test bookings produce expected totals

Part 7: Common Issues

Deposit not appearing on the payment schedule

Cause: The deposit due date falls on or after the final balance due date, and AlwaysCreateDepositRule__c is unchecked.

Fix: Either enable AlwaysCreateDepositRule__c on the configuration, or adjust the Days Offset values so the deposit due date falls before the final balance due date for your typical booking window.

Deposit amount is lower than expected

Cause: A percentage-based rule calculated an amount below the MinimumDeposit__c floor, but no minimum is configured.

Fix: Set MinimumDeposit__c on the rule to enforce a floor amount.

Per-passenger amount seems wrong

Cause: The Value__c on a Per Person rule represents the amount per passenger, not the total. If the booking has more or fewer passengers than expected, the total will differ.

Fix: Verify the passenger count on the booking and confirm the per-person value is correct.

Due date adjusted to today unexpectedly

Cause: AlwaysCreateDepositRule__c is enabled, and the calculated deposit due date has already passed. The system adjusts the due date to today rather than suppressing the rule.

Fix: This is expected behavior when the setting is enabled. If you do not want this adjustment, disable AlwaysCreateDepositRule__c.

Object	API Name	Role
Payment Schedule Configuration	`KaptioTravel__PaymentScheduleConfiguration__c`	Groups rules together; controls deposit suppression behavior
Payment Schedule Rule	`KaptioTravel__PaymentScheduleRule__c`	Defines a single deposit or final balance milestone
Payment Schedule	`KaptioTravel__PaymentSchedule__c`	The generated schedule record attached to an itinerary

Note: The Channel__c.DefaultDeposit__c (Default Deposit Percentage) field is deprecated and should not be used for new configurations. Use PaymentScheduleConfiguration__c rules instead.