Payment Processing Workflow¶

Overview¶

This document outlines the workflow for processing payments in the booking system, including the integration with payment service providers (PSPs) and property management systems (PMS).

Payment Processing Flow¶

1. Payment Initiation¶

Payment Initiation Flow

The payment process begins when a payment is initiated through one of the following channels:

Guest Booking: Guest completes a booking that requires a deposit
Payment Link: Guest clicks on a payment link sent by the hotel
Agent Interface: Hotel staff initiates a payment on behalf of the guest

The system creates a PaymentInitiation record with status INITIATED and generates a unique payment ID.

2. Payment Gateway Redirect¶

The guest is redirected to the payment gateway (e.g., Saferpay) to enter their payment details. The system passes the following information to the payment gateway:

Payment amount and currency
Guest details (name, email)
Booking reference
Return URL for successful and failed payments
Notification URL for asynchronous updates

3. Payment Processing¶

Payment Processing Flow

The payment gateway processes the payment and redirects the guest back to the booking system with the result. The system updates the PaymentInitiation record with the status from the payment gateway:

COMPLETED: Payment was successful
FAILED: Payment failed
CANCELLED: Payment was cancelled by the guest

4. Asynchronous Notification¶

In addition to the redirect, the payment gateway sends an asynchronous notification to the system's webhook endpoint. This ensures that the payment status is updated even if the guest closes their browser before the redirect completes.

5. PMS Integration¶

PMS Integration Flow

If the payment is successful and the hotel has PMS integration enabled, the system posts the payment to the PMS:

For Apaleo PMS, the system calls the Apaleo API to post the deposit to the guest's folio
The system waits for 5 minutes before posting to ensure that the reservation is properly created in the PMS
The PMS posting is done asynchronously to avoid blocking the main application flow

6. Notification and Confirmation¶

After the payment is processed, the system sends notifications to:

Guest: Email confirmation of the payment
Hotel: Email notification of the payment
Agent: Email notification if the payment was initiated by an agent

Reservation Deposit Flow¶

1. Reservation Creation¶

When a reservation is created, the system checks if a deposit is required based on the hotel's deposit policy and the rate plan selected by the guest. The system uses the PolicyType enum to determine the specific payment requirements based on the reservation details.

2. Deposit Request¶

If a deposit is required (based on the PolicyType determination), the system creates a PaymentInitiation record and either:

Redirects the guest to the payment gateway (for online bookings)
Sends a payment link to the guest (for bookings made through other channels)

3. Deposit Payment¶

The guest completes the deposit payment through the payment gateway.

4. Reservation Confirmation¶

Once the deposit payment is confirmed, the system:

Updates the reservation status to CONFIRMED
Posts the deposit to the PMS (if PMS integration is enabled)
Sends a confirmation email to the guest with the reservation details

Payment Link Flow¶

1. Link Creation¶

A payment link is created through one of the following channels:

Agent Interface: Hotel staff creates a payment link for a guest
Automated Process: System automatically creates a payment link for a booking requiring a deposit

The system generates a unique link ID and sets an expiry date for the link.

2. Link Distribution¶

The payment link is sent to the guest via:

Email
SMS
Other communication channels

3. Link Access¶

When the guest accesses the payment link, they are presented with a payment form that includes:

Booking details
Payment amount and currency
Available payment methods

4. Payment Completion¶

The guest completes the payment through the payment gateway, and the process continues as described in the main payment flow.

Refund Flow¶

1. Refund Initiation¶

A refund is initiated through one of the following channels:

Agent Interface: Hotel staff initiates a refund for a guest
Automated Process: System automatically initiates a refund for a cancelled booking

The system creates a RefundInitiation record with status INITIATED and generates a unique refund ID.

2. Refund Processing¶

The system sends a refund request to the payment gateway with the following information:

Original payment ID
Refund amount and currency
Reason for refund

3. Refund Confirmation¶

The payment gateway processes the refund and sends a confirmation to the system. The system updates the RefundInitiation record with status COMPLETED.

4. PMS Integration¶

If the hotel has PMS integration enabled, the system posts the refund to the PMS:

For Apaleo PMS, the system calls the Apaleo API to post a negative deposit to the guest's folio
The PMS posting is done asynchronously to avoid blocking the main application flow

5. Notification¶

After the refund is processed, the system sends notifications to:

Guest: Email confirmation of the refund
Hotel: Email notification of the refund
Agent: Email notification if the refund was initiated by an agent

Error Handling¶

Payment Processing Errors¶

If an error occurs during payment processing, the system:

Logs the error with detailed information
Updates the payment status to FAILED with the error message
Redirects the guest to an error page with appropriate messaging
Sends a notification to the system administrators if the error is critical

PMS Integration Errors¶

If an error occurs during PMS integration, the system:

Logs the error with detailed information
Retries the operation after a delay (for transient errors)
Continues the payment flow without interrupting the guest experience
Sends a notification to the system administrators if the error persists

Reconciliation¶

The system provides tools for reconciling payments with external systems:

Payment Reports: Detailed reports of all payments processed by the system
PMS Reconciliation: Tools for comparing payments in the system with payments in the PMS
PSP Reconciliation: Tools for comparing payments in the system with payments in the PSP

Monitoring and Alerts¶

The system includes monitoring and alerting for critical payment operations:

Failed Payments: Alerts for payments that fail beyond a certain threshold
PMS Integration Failures: Alerts for persistent PMS integration failures
Payment Gateway Downtime: Alerts for payment gateway availability issues
Unusual Activity: Alerts for unusual payment patterns that might indicate fraud

Security Considerations¶

Data Protection¶

The system follows strict data protection guidelines:

No credit card data is stored in the system database
All sensitive data is transmitted securely using TLS 1.2+
Payment processing is delegated to PCI-compliant payment service providers
Access to payment data is strictly controlled and audited

Fraud Prevention¶

The system includes several fraud prevention measures:

IP Tracking: Monitoring of IP addresses for suspicious activity
Velocity Checks: Limits on the number of transactions from a single source
Amount Validation: Verification that payment amounts match expected values
3D Secure: Support for 3D Secure authentication for credit card payments

Glossary¶

PSP: Payment Service Provider, e.g., Saferpay, Stripe, PayPal
PMS: Property Management System, e.g., Apaleo
Payment Initiation: The process of starting a payment transaction
Payment Gateway: The interface provided by the PSP for processing payments
Webhook: An HTTP callback that provides asynchronous notifications about payment events
Folio: A guest's account in the PMS where charges and payments are recorded

Payment Processing API - API documentation for payment processing endpoints
Apaleo PMS Integration - Details about integration with Apaleo PMS
Payment Integration Guide - Guide for integrating with the payment system
Offers API - Documentation for the Offers API that initiates payment processes

Flow Diagrams¶

Payment Initiation Flow¶