Payment links

A payment link is a secure, hosted Adyen payment page that you send to a guest — by email, SMS, or any other channel. The guest opens the link on any device, selects their preferred payment method, and completes the action. No card details are collected by your application.

Payment links in Apaleo cover three distinct use cases:

Use case Endpoint What it does
Collect a folio payment POST /finance/v1/folios/{folioId}/payments/by-link Guest pays an outstanding balance on a folio.
Store a payment account POST /booking/v1/payment-accounts/by-link Guest stores their card on file against a booking or reservation.
Create an authorization hold POST /booking/v1/authorizations/by-link Guest authorises a hold for a specific amount — for example, a security deposit.

The payment page appearance — brand name, logo, colours — is configured by the hotel in their Adyen settings, not by your application.

Collect a folio payment

Use this to send a guest a link to settle an outstanding balance on a folio. The reservation must exist and charges must already be posted to the folio before a payment link can be generated. The payment is committed to the folio automatically once the guest completes payment.

For some open invoice payment methods, the folio’s full billing address must be set before creating the link.

POST /finance/v1/folios/{folioId}/payments/by-link

{
  "expiresAt": "2026-06-10T07:13:26.1389028Z",
  "countryCode": "DE",
  "description": "Prepayment for your upcoming stay",
  "payerEmail": "guest@example.com",
  "amount": {
    "amount": 150,
    "currency": "EUR"
  },
  "paidCharges": [
    {
      "chargeId": "BLIPKWXP-1-1-1",
      "amount": 150
    }
  ]
}

Key fields

Field Required Description
expiresAt Yes When the link expires. After this the link can no longer be used.
countryCode Yes The guest’s country. Determines which payment methods are shown.
description No A description shown to the guest on the payment page.
payerEmail No The guest’s email. Used by some payment methods for receipts or verification.
amount Yes The total amount to collect.
paidCharges No The specific charges this payment covers. Required to enable open invoice payment methods.

Store a payment account

Use this to send a guest a link to store their card on file against a booking or reservation — for example, during the digital guest journey before arrival, or when a card needs to be added remotely.

POST /booking/v1/payment-accounts/by-link

{
  "target": {
    "type": "Booking",
    "id": "KYKXKLWL"
  },
  "propertyId": "MUC",
  "expiresAt": "2026-06-10T13:18:40.5848632Z",
  "countryCode": "DE",
  "description": "Payment information for the booking",
  "payerEmail": "guest@example.com"
}

Key fields

Field Required Description
target.type Yes Booking or Reservation — the level at which the payment account is stored.
target.id Yes The Apaleo booking or reservation ID.
propertyId Yes The Apaleo property ID.
expiresAt Yes When the link expires.
countryCode Yes The guest’s country. Determines which payment methods are shown.
description No A description shown to the guest on the payment page.
payerEmail No The guest’s email. Used by some payment methods for receipts or verification.

Create an authorization hold

Use this to send a guest a link to authorise a hold for a specific amount — for example, a security deposit before arrival or a hold for potential extras during the stay.

POST /booking/v1/authorizations/by-link

{
  "target": {
    "type": "Booking",
    "id": "KYKXKLWL",
    "propertyId": "MUC"
  },
  "expiresAt": "2026-06-10T13:18:40.338939Z",
  "countryCode": "DE",
  "description": "Consumption authorization for the reservation",
  "payerEmail": "guest@example.com",
  "amount": {
    "amount": 150,
    "currency": "EUR"
  }
}

Key fields

Field Required Description
target.type Yes Booking or Reservation — the level at which the authorization is created.
target.id Yes The Apaleo booking or reservation ID.
target.propertyId Yes The Apaleo property ID.
expiresAt Yes When the link expires.
countryCode Yes The guest’s country. Determines which payment methods are shown.
description No A description shown to the guest on the payment page.
payerEmail No The guest’s email. Used by some payment methods for receipts or verification.
amount Yes The amount to hold on the guest’s card.