Accept payments online

This page covers the full online payment flow — from understanding what your checkout needs to do based on the booking guarantee type, through collecting card details with Adyen Drop-in, making the payment request to Apaleo Pay, and handling the response.

1. Understand the guarantee type

The payment flow at booking depends on the guarantee type of the rate plan. Check the guarantee type on each reservation in the basket and handle it as follows.

PM6Hold

No payment is required at booking. You may optionally ask the guest to put a card on file to guarantee the reservation for arrivals after 6 pm. Payment is collected at check-in or check-out.

If the guest provides a card, authorise a zero amount and store the resulting payment account against the booking.

CreditCard

The guest must provide a card, but you do not charge it at booking. Perform a zero-amount recurring authorisation to validate the card and store the resulting payment account against the booking. A zero amount alone is not sufficient — see Payment accounts for the required parameters to make the authorisation recurring. Payment is collected at check-in or check-out.

Prepayment

Charge the guest at the time of booking. Authorise the prepayment amount and pass the transactionReference to Apaleo when creating the reservation. Apaleo captures the charge automatically once the booking is confirmed. A payment account is not required for prepaid reservations, but can still be created for any future charges.

If prePaymentAmount is specified in the booking, that amount is captured. If not, the full amount chargeable on the reservation is captured.

If no transactionReference is provided, capture behaviour falls back to the prepayment automation configured on the property and the guarantee type of the rate plan.

For multi-reservation bookings where each reservation is captured separately, always set additionalData.authorisationType to PreAuth, not FinalAuth.

Set deliveryDate to the earliest arrival date across all reservations in the booking. This allows the payment processor to calculate chargeback exposure correctly.

For bookings that span multiple properties, pass the property ID of the property with the largest share of rooms or revenue in metadata.propertyId. For prepayment, funds are paid out to the merchant account used in the original authorisation. When charging against a payment account, funds for each reservation go to the merchant account configured for the property where that reservation sits — regardless of which merchant account was used to create the payment account.

2. Add Adyen Drop-in to your checkout page

Apaleo Pay uses the Adyen Advanced flow. Your server makes three API calls: /paymentMethods → /payments → /payments/details.

Advanced flow required. The Adyen Sessions flow is not supported. Apaleo Pay requires direct control over the additionalData metadata for capture and tokenisation. Follow the Adyen Advanced flow integration guide when setting up Drop-in.

Drop-in handles card encryption, 3D Secure challenges, and alternative payment methods. It also handles tokenisation automatically — when the guest submits the form, Drop-in fires an onSubmit event with an encrypted state.data payload. Pass this to your server. Never handle raw card numbers server-side.

Suppress buy-now-pay-later methods

Hotel bookings should not offer deferred payment methods. When initialising Drop-in, set removePaymentMethods to exclude the following:

klarna_paynow, klarna, klarna_b2b, klarna_account,
ratepay, ratepay_directdebit,
afterpaytouch, afterpay_default, afterpay_directdebit, afterpay_b2b,
facilypay_3x, facilypay_4x, facilypay_6x, facilypay_10x, facilypay_12x

Enable card-on-file for merchant-initiated transactions

To allow the hotel to charge the card later (no-shows, late cancellations, post-stay billing), set these three parameters when initialising Drop-in:

3. Fetch available payment methods

Before rendering Drop-in, fetch the payment methods available for the merchant account and the guest’s country. Call POST /paymentMethods from your server:

curl https://checkout-test.adyen.com/v69/paymentMethods \
  -H "x-API-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantAccount": "ApaleoGmbHCOM"
  }'

Response

{
  "paymentMethods": [
    {
      "name": "AliPay",
      "type": "alipay"
    },
    {
      "brands": ["amex", "diners", "discover", "maestro", "mc", "visa"],
      "name": "Credit Card",
      "type": "scheme"
    },
    {
      "brands": ["bcmc", "maestro", "visa"],
      "name": "Bancontact card",
      "type": "bcmc"
    }
  ]
}

Use name to display the payment method in your UI and type to identify it in the payment request.

4. Required metadata

Every payment request to Apaleo Pay must include the following fields in additionalData. Without these, Apaleo cannot finalise the transaction correctly.

5. Make the payment request

This example shows a prepayment — a real amount charged at the time of booking. The encrypted card data comes from Drop-in’s onSubmit event. Call POST /payments from your server:

curl https://checkout-test.adyen.com/v69/payments \
  -H "X-API-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": {
      "currency": "EUR",
      "value": 56929
    },
    "paymentMethod": {
      "type": "scheme",
      "encryptedCardNumber": "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
      "encryptedExpiryMonth": "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
      "encryptedExpiryYear": "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
      "encryptedSecurityCode": "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
      "holderName": "John Smith"
    },
    "deliveryDate": "2021-08-17T16:00:00.000+01:00",
    "storePaymentMethod": true,
    "shopperReference": "575b0100-b261-4a36-94cb-eeb49f7c98d3",
    "shopperInteraction": "Ecommerce",
    "recurringProcessingModel": "UnscheduledCardOnFile",
    "additionalData": {
      "metadata.flowType": "CaptureOnly",
      "metadata.accountId": "DEMO",
      "metadata.propertyId": "MUC",
      "subMerchantID": "CWWVG78PRG8AWNK"
    },
    "returnUrl": "https://your-company.com/checkout?shopperOrder=12xy",
    "merchantAccount": "ApaleoGmbHCOM"
  }'

For a CreditCard guarantee type where you only want to validate and store the card without charging, set value to 0. See Payment accounts for the full zero-amount recurring authorisation setup.

Successful response

{
  "additionalData": {
    "expiryDate": "9/2022",
    "cardHolderName": "John Smith",
    "cardSummary": "1111",
    "paymentMethod": "visa",
    "recurring.recurringDetailReference": "8415689021960227",
    "recurringProcessingModel": "UnscheduledCardOnFile",
    "recurring.shopperReference": "575b0100-b261-4a36-94cb-eeb49f7c98d3"
  },
  "pspReference": "851570021506441J",
  "resultCode": "Authorised",
  "merchantReference": "YOUR_ORDER_NUMBER"
}

Store the values from the response — the pspReference is passed as transactionReference when creating the booking in Apaleo and can be used to look up the transaction later. The recurring.shopperReference and recurring.recurringDetailReference can be used directly with the Apaleo Payment Account APIs as payerReference and storedPaymentMethodId respectively to store the card on file against the reservation.

6. Handle the response

Result codes

For the full list of result codes, see the Adyen result codes documentation.

Handle 3D Secure redirects

If the response contains "resultCode": "RedirectShopper" and an action object, Drop-in handles the redirect automatically on the client side. Once the guest completes authentication, they are returned to your returnUrl with a redirectResult parameter.

Call POST /payments/details from your server to verify the result:

curl https://checkout-test.adyen.com/v69/payments/details \
  -H "x-API-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "details": {
      "redirectResult": "eyJ0cmFuc1N0YXR1cyI6IlkifQ=="
    }
  }'

Response

{
  "resultCode": "Authorised",
  "pspReference": "88154795347618C"
}

7. What gets captured and when

Once you create the booking in Apaleo with the transactionReference, Apaleo queues the authorisation and waits for the booking to be confirmed. As soon as the booking is created, Apaleo captures the appropriate amount for each reservation automatically (see Create the booking).

If no booking is received within two hours of the authorisation, Apaleo automatically cancels the hold to release the funds. For auto-capture payment methods, a refund is issued instead.