Make payments to a folio

A folio is the billing account for a reservation or booking. All charges — room rate, restaurant, spa, minibar — are posted to a folio. To settle those charges, you post a payment against the folio using one of the methods below. Folio-related endpoints can be also found here.

All folio payment requests are asynchronous. After calling any of the endpoints on this page:

• Use the Location header in the response to poll for the payment status.
• While a payment is pending, it reduces the number of allowed concurrent payments on the folio.
• Payments time out automatically after 60 minutes if not completed.

Choose your payment method

By authorization

Use this to capture funds from either:

• A PSP pre-authorization made directly with Adyen — pass the pspReference as transactionReference with referenceType: PspReference
• An Apaleo authorization hold — pass the authorization ID as transactionReference with referenceType: AuthorizationId — see Authorization holds

The flow type on the original Adyen payment must have been set to CaptureOnly.

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

{
  "transactionReference": "564578124534890J",
  "referenceType": "PspReference",
  "amount": {
    "amount": 330,
    "currency": "EUR"
  },
  "paidCharges": [
    {
      "chargeId": "BLIPKWXP-1-1-1",
      "amount": 330
    }
  ]
}

paidCharges is optional for standard card payments but required to enable open invoice payment methods.

Split a pre-authorization across multiple folios

A single pre-authorization can be captured in separate amounts and posted to the same or different folios. Call by-authorization once per capture, referencing the same transactionReference each time with the appropriate amount for each folio. This is useful for group bookings or split billing scenarios.

By payment account

Charge the card stored as a payment account on the reservation. The payment account must already exist on the reservation — see Payment accounts.

POST /finance/v1/folios/{folioId}/payments/by-payment-account

{
  "paymentAccountId": "UBMFXUFH",
  "amount": {
    "amount": 230,
    "currency": "EUR"
  },
  "paidCharges": [
    {
      "chargeId": "BLIPKWXP-1-1-1",
      "amount": 200
    }
  ]
}

By link

Generate a hosted Adyen payment page and send the URL to the guest to settle their balance remotely. 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": "2021-09-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
    }
  ]
}

paidCharges is optional for standard card payments. Include it if you want to support open invoice payment methods.

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

By terminal

There are two terminal payment flows depending on whether a folio already exists when the guest pays.

Direct terminal payment (folio exists)

Use this when the guest is physically present and the folio already has charges on it. The payment is collected on the terminal and posted directly to the folio in one step. No separate pre-authorization is needed.

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

{
  "terminalId": "V400m-324689704",
  "amount": {
    "amount": 230,
    "currency": "EUR"
  },
  "paidCharges": [
    {
      "chargeId": "BLIPKWXP-1-1-1",
      "amount": 230
    }
  ]
}

The terminalId is the model name and serial number of the terminal, for example V400m-324689704 or P400Plus-27545332.

Terminal pre-authorization + capture (folio does not exist yet)

Use this when you need to block funds on the terminal before the folio or charges exist — for example, at a walk-in kiosk where the reservation is being created on the spot, or at check-in when you want to hold funds for potential extras before any charges are posted.

Step 1 — Pre-authorize on the terminal

Call the Payment API to initiate the pre-authorization on the terminal:

POST https://payment.apaleo.com/payment/v1/payment-transactions/by-terminal?flow=AutoExpire

{
  "propertyId": "MUC",
  "terminalId": "P400Plus-27545332",
  "amount": {
    "currency": "EUR",
    "value": 680
  },
  "merchantReference": "864c3b9e-4820-407b-a31e-6713f5effcb3"
}

flow=AutoExpire means the pre-authorization has a limited validity period (minimum 2 hours) and will expire and cancel automatically if not captured. This prevents funds from being blocked indefinitely.

Step 2 — Capture against the folio

Once the folio exists and charges are known, capture the pre-authorized amount using by-authorization:

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

{
  "transactionReference": "564578124534890J",
  "referenceType": "PspReference",
  "amount": {
    "amount": 330,
    "currency": "EUR"
  },
  "paidCharges": [
    {
      "chargeId": "BLIPKWXP-1-1-1",
      "amount": 330
    }
  ]
}

The same pre-authorization can be split across multiple folios by calling by-authorization multiple times with the same transactionReference.