Overview

Apaleo Pay is the built-in payment layer for Apaleo. It handles the full payment lifecycle for a hotel guest — from the moment they book online, through incidental charges during their stay, to final settlement at check-out. Every transaction, regardless of channel, is recorded in one place and tied to the guest’s reservation.

Apaleo Pay is built on Adyen. You integrate once against the Apaleo APIs; Apaleo manages the Adyen merchant account, tokenisation, settlement, and reconciliation behind the scenes. Your application does not need a direct Adyen contract and you do not need an Adyen developer account. Apaleo Pay works across all common hotel payment scenarios: direct online bookings, OTA bookings paid by virtual card, card-present terminal payments, pay-by-link for remote guests, and merchant-initiated charges such as no-show fees.

Key concepts

Before diving into the integration, make sure you are familiar with these five concepts. They appear throughout the docs.

Payment account A tokenised, stored representation of a guest’s payment method — the hotel industry’s “card on file”. A payment account is always attached to a reservation or booking and can be used for future charges without the guest needing to re-enter their card details.

Folio The billing account for a reservation or booking. All charges (room rate, minibar, restaurant) and payments are posted against a folio. A reservation can have multiple folios.

Authorization (pre-auth) A temporary hold placed on a guest’s card to cover potential charges — for example, a security deposit at check-in. The hold is either captured (converted into a real charge) or cancelled when no longer needed. Authorizations expire after 28 days by default.

Flow type Controls what happens after a payment is authorised. Set via metadata.flowType in the Adyen additionalData on every payment request:

• CaptureOnly (also known as AutoExpire) — authorise now, capture within 2 hours. If not captured, the hold is released automatically.
• BlockNHold — place a hold without capturing; used for authorization holds.

Sub-merchant ID Your property’s identifier within the Apaleo merchant account. Required on every payment request. Each live property has its own sub-merchant ID, provided by Apaleo when you go live.

How your application fits in

The following diagram shows how your application integrates with Apaleo Pay to collect and process a guest payment. Use it as a blueprint for your implementation:

    participant App
    participant ApaleoP as Apaleo Pay

    App->>ApaleoP: 1. POST /paymentMethods — fetch available payment methods
    ApaleoP-->>App: 2. Returns list of payment methods

    App->>ApaleoP: 3. Guest completes Drop-in form; POST /payments to initiate payment
    ApaleoP-->>App: 4. Returns /payments response (resultCode + optional action)

    App->>ApaleoP: 5. Handle any front-end actions (e.g. 3D Secure redirect)
    App->>ApaleoP: 6. POST /payments/details — submit additional details if required
    ApaleoP-->>App: 7. Returns pspReference and final resultCode

Steps explained

1. Fetch payment methods — your server calls /paymentMethods to get the methods enabled for the merchant account and the guest’s country.
2. Payment methods returned — Apaleo Pay returns the available methods for you to render in your checkout UI.
3. Initiate payment — the guest completes the Adyen Drop-in form and your server calls /payments with the encrypted card details, required metadata, and flow type.
4. Payment response returned — Apaleo Pay returns a resultCode and, if further action is needed (e.g. 3D Secure), an action object.
5. Handle front-end actions — your client-side Drop-in handles any redirects or challenges automatically.
6. Submit additional details — if the shopper completed a redirect or 3D Secure challenge, call /payments/details with the redirectResult.
7. Final result — Adyen returns the pspReference (unique transaction ID) and the final resultCode. Store the pspReference — you will need it to look up the transaction later.

Where to go next

Get set up

1. Setup and testing — configure your account and add Drop-in to your checkout page
2. What to test — sandbox credentials and a checklist of scenarios to verify
3. Go live — request live credentials and switch to production

Build your payment scenarios

Once your setup is complete, use the scenario guides for your specific use case:

Look things up

• Read transaction details by PSP reference
• Read transaction details by merchant reference