Apaleo PMS Integration

Overview

The Apaleo PMS integration allows the booking service to synchronize payment data, reservation details, and other information with the Apaleo Property Management System. This integration ensures that all guest payments made through the booking system are properly reflected in the hotel's PMS.

Configuration

The Apaleo integration is configured in the hotel settings using the enableApaleoPosting flag. When enabled, the system automatically posts payments, deposits, and service charges to Apaleo.

Integration Points

Deposit Posting

When a payment is successfully processed, the system can automatically post the deposit to the guest's folio in Apaleo.

Process Flow

1. Guest completes payment through the payment gateway
2. Payment system receives confirmation of successful payment
3. System waits for 5 minutes to ensure the reservation is properly created in Apaleo
4. System posts the deposit to Apaleo using the PMS API
5. Deposit appears in the guest's folio in Apaleo

Technical Implementation

The deposit posting is implemented through the ApaleoService.postPayment() and ApaleoService.postPrePayment() methods. These methods create a CustomPaymentPosting object with the payment details and send it to the Apaleo API.

{
  "method": "CreditCard",       // Payment method mapping
  "receipt": "TX-123456789",    // Transaction reference
  "amount": {
    "amount": 150.00,           // Payment amount
    "currency": "EUR"           // Payment currency
  }
}

Payment Method Mapping

The system maps payment methods from the booking system to Apaleo payment methods using the following mapping:

Booking System Payment Method	Apaleo Payment Method
CREDIT_CARD	CreditCard
DEBIT_CARD	DebitCard
BANK_TRANSFER	BankTransfer
PAYPAL	Other
INVOICE	Invoice

Service Posting

In addition to deposit posting, the system can also post service charges to the guest's folio. This is used for special services, discounts, or other charges.

Spirit Club Discount

When a guest is a member of the Spirit Club loyalty program, the system can automatically post a discount service to the folio.

Process Flow

1. Reservation is created with a Spirit Club discount
2. System identifies the discount and triggers the service posting
3. System waits for 5 minutes to ensure the reservation is properly created in Apaleo
4. System posts the service charge to Apaleo using the PMS API
5. Discount appears in the guest's folio in Apaleo

Technical Implementation

The service posting is implemented through the ApaleoService.postDiscountService() method. This method sends a request to the Apaleo API to post a service charge with the specified service code.

Charge Posting

The system can also post general charges to the guest's folio in Apaleo.

Process Flow

1. System identifies a charge that needs to be posted to the guest's folio
2. System waits for 5 minutes to ensure the reservation is properly created in Apaleo
3. System posts the charge to Apaleo using the PMS API
4. Charge appears in the guest's folio in Apaleo

Technical Implementation

The charge posting is implemented through the ApaleoService.postCharge() method. This method creates a ChargeItem object with the charge details and sends it to the Apaleo API.

API Endpoints

Post Deposit

POST /finance/reservations/{reservationCode}/deposits

Posts a deposit payment to the guest's folio in Apaleo.

Path Parameters

Parameter	Type	Description
reservationCode	string	Reservation identifier

Request Body

{
  "method": "CreditCard",
  "receipt": "TX-123456789",
  "amount": {
    "amount": 150.00,
    "currency": "EUR"
  }
}

Post Service

POST /finance/reservations/{reservationCode}/services/{serviceCode}

Posts a service charge to the guest's folio in Apaleo.

Path Parameters

Parameter	Type	Description
reservationCode	string	Reservation identifier
serviceCode	string	Service code

Post Charge

POST /finance/reservations/{reservationCode}/charges

Posts a general charge to the guest's folio in Apaleo.

Path Parameters

Parameter	Type	Description
reservationCode	string	Reservation identifier

Request Body

{
  "serviceId": "SERVICE-123",
  "date": "2023-07-15",
  "amount": {
    "amount": 50.00,
    "currency": "EUR"
  },
  "vatType": "Standard",
  "description": "Special service"
}

Error Handling

The Apaleo integration includes robust error handling to ensure that payment operations are not lost due to temporary connectivity issues or other errors.

Retry Mechanism

If a posting to Apaleo fails, the system logs the error and continues without interrupting the overall process. This approach ensures that temporary API issues don't impact the guest experience.

Asynchronous Processing

All Apaleo API calls are made asynchronously in a separate thread to avoid blocking the main application flow. This ensures that slow API responses don't impact the responsiveness of the booking system.

Debugging

To debug Apaleo integration issues, set the following logging level in the application configuration:

logging:
  level:
    com.gustaffo.reservations.connectors: trace

This will enable detailed logging of all API calls to Apaleo, including request and response payloads.

Security

The Apaleo integration uses API key authentication. The API key is configured in the application.yml file:

connectors:
  apaleo:
    host: https://api-payone-connector.uat.apps.gustaffo.com/api/v1
    api-key: [API_KEY]

The API key should be kept confidential and rotated periodically according to security best practices.

Troubleshooting

Common Issues

Deposit Not Appearing in Apaleo

If a deposit payment is not appearing in Apaleo, check the following:

1. Verify that enableApaleoPosting is enabled for the hotel
2. Check the application logs for any API errors
3. Verify that the reservation code in Apaleo matches the booking number used in the API call
4. Ensure that the payment was successfully processed before attempting to post to Apaleo

Service Charge Not Applied

If a service charge is not appearing in Apaleo, check the following:

1. Verify that the service code exists in Apaleo
2. Check the application logs for any API errors
3. Verify that the reservation code in Apaleo matches the booking number used in the API call

Future Enhancements

Planned enhancements to the Apaleo integration include:

1. Two-way synchronization: Allow changes in Apaleo to be reflected in the booking system
2. Expanded service charge support: Support for a wider range of service charges and discounts
3. Real-time synchronization: Reduce the delay between payment processing and posting to Apaleo
4. Bulk operations: Support for posting multiple charges or deposits in a single operation

Support

For issues related to the Apaleo integration, please contact:

• Technical Support: support@gustaffo.com
• API Documentation: https://api-payone-connector.uat.apps.gustaffo.com/docs

Related Documentation

• Payment Processing API - Main documentation for the payment processing system
• Payment Workflow - Diagrams and process flows including PMS integration
• Payment Integration Guide - Guide for integrating with the payment system