Policy Types¶

Overview¶

The PolicyType enum is a core component of the payment processing system, determining how and when payments or authorizations are handled for different types of reservations. Each policy type implements specific business rules for payment instructions based on the reservation details, booking channel, time until check-in, and other factors.

PolicyType Enum Values¶

DEPOSIT¶

A deposit policy requires guests to pay a percentage of the total reservation amount as a deposit to confirm the booking. The percentage is specified in the policy code (e.g., "25%" would be encoded as "25").

Behavior: - Calculates deposit amount based on the percentage in the policy code - Subtracts any insurance costs from the total before calculating the deposit - Considers any prepaid amounts when determining the final amount to charge - Creates a payment instruction with the calculated deposit amount - May switch to an authorization of €1 if nothing is left to pay after considering prepayments

GUARANTEE¶

A guarantee policy requires a valid payment method to secure the reservation without necessarily charging the guest immediately. The actual charge behavior depends on how close the booking is to the check-in date.

Behavior: - For bookings 60+ days before check-in: Requests a €1 authorization and offers a 3% discount for prepayment - For bookings 14-59 days before check-in: Requests a €1 authorization only - For bookings 2-13 days before check-in: Requests an authorization for 100% of the reservation amount - For bookings less than 2 days before check-in: Requests an authorization for 100% of the reservation amount with no renewal

NONE¶

No payment or guarantee is required to confirm the reservation.

Behavior: - Returns an empty list of payment instructions

GUARANTEE_WEB¶

A special guarantee policy used for web bookings, offering an early payment discount without requiring a separate authorization.

Behavior: - For bookings 60+ days before check-in: Offers a 3% discount for prepayment - For bookings less than 60 days before check-in: No payment instructions

DEPOSIT_B2B¶

A deposit policy specifically for business-to-business bookings, typically handled through invoicing rather than direct payment.

Behavior: - Returns an empty list of payment instructions (payments are handled through separate B2B processes)

GUARANTEE_OTA¶

A guarantee policy specifically for Online Travel Agency bookings, similar to the regular GUARANTEE policy but with adjusted rules for OTA-specific scenarios.

Behavior: - Similar to GUARANTEE, but without the discounted prepayment option - Handles special cases for IATA bookings

Payment Instruction Generation¶

Each policy type implements the getPaymentInstructions() method, which returns a list of PaymentInstruction objects based on the policy rules and the reservation data. These payment instructions contain:

amount: The amount to charge or authorize in cents (e.g., 10000 for €100)
arrival: The check-in date
expiration: When the payment/authorization expires
renewedValidityInDays: How many days the authorization should be valid for renewals
paymentType: The type of payment action (PAYMENT, PAYMENT_DISCOUNTED, or AUTHORIZATION)
enhancementAmount: Any additional costs like insurance
hotelId: The property code
source: Where the payment instruction originated from
payer: Guest details for payment processing
salesDescription: Description of the reservation for payment receipts
referenceNumber: The reservation code

Helper Methods¶

calculateRenewedValidity¶

Determines how many days an authorization should be valid for renewal based on how close the booking is to the check-in date: - 2 days for bookings 14+ days before check-in - 1 day for bookings 2-13 days before check-in - 0 days for bookings less than 2 days before check-in

calculateExpirationDate¶

Determines when a payment or authorization expires based on how close the booking is to the check-in date: - 10 days after creation for bookings 14+ days before check-in - 2 days before check-in for bookings 2-13 days before check-in - Check-in date for bookings less than 2 days before check-in

considerPrepayments¶

Calculates the adjusted amount to charge after considering any prepaid amounts. Returns zero if the booking is already fully paid.

Usage Example¶

// Example of using PolicyType to generate payment instructions
PolicyType policyType = PolicyType.DEPOSIT
    .withPolicyCode("25")  // 25% deposit
    .withReservationData(reservationData);

List<PaymentInstruction> instructions = policyType.getPaymentInstructions();

Business Logic Considerations¶

Insurance Handling¶

When a reservation includes insurance (e.g., Merkur Insurance), the system calculates the insurance cost separately and excludes it from deposit calculations. This ensures that insurance is charged separately and not subject to deposit percentages.

Special Rate Plans¶

Certain rate plans are marked with a special identifier ("*" suffix in the description) or associated with specific IATA codes. These rate plans may have modified payment behavior, particularly for discounted prepayments.

Time-Based Logic¶

Many payment policies adjust their behavior based on how far in advance the booking is made: - Long-term bookings (60+ days): Often offer discounts for prepayment - Medium-term bookings (14-59 days): Typically require only authorization - Short-term bookings (2-13 days): Usually require authorization of the full amount - Immediate bookings (<2 days): May require immediate payment

PaymentType¶

Defines the type of payment action: - PAYMENT: Standard payment charge - PAYMENT_DISCOUNTED: Payment with an applied discount - AUTHORIZATION: Credit card authorization without immediate charge

PaymentInstructionSource¶

Indicates the origin of the payment instruction: - CONFIRMATION_NOTIFICATION: Generated during booking confirmation - MANUAL: Created manually by an operator - SYSTEM: Generated automatically by the system

Integration Points¶

The PolicyType system integrates with:

Payment Processing API: Executes the payment instructions
PMS Integration: Posts payments and authorizations to the property management system
Notification System: Communicates payment requirements to guests

Policy Type Decision Flow¶

Policy Type Decision Flow

The diagram above illustrates how the system determines which payment instructions to generate based on the PolicyType and reservation details.