Authorization holds

An authorization hold temporarily blocks a specific amount on a guest’s card to cover potential charges — for example, a security deposit at check-in, minibar consumption, or a no-show fee. The hold does not move money; it simply reserves it on the guest’s card until you capture it or release it.

In Apaleo, this is called an “authorization”. Once created, an authorization can be captured against a folio, refreshed, extended, or cancelled.

Create an authorization

Authorizations can be created at either the booking or reservation level. Set targetType to Booking or Reservation accordingly. There is no limit on the number of authorizations per reservation or booking.

An authorization expires 28 days after creation by default, though this may vary depending on the card scheme.

There are four ways to create an authorization. Choose the one that fits your use case:

For full request body details, refer to the Booking V1 API reference.

Creating an authorization from an existing PSP pre-authorization

If you are creating an authorization in Apaleo based on a pre-authorization made directly with Adyen (outside of Apaleo), the original Adyen payment request must include the BlockNHold flow type in the metadata:

"additionalData": {
  "metadata.flowType": "BlockNHold",
  "metadata.accountId": "DEMO",
  "metadata.propertyId": "MUC",
  "subMerchantID": "CWWVG78PRG8AWNK"
}

Manage an authorization

Get a specific authorization

GET /booking/v1/authorizations/{id}

Get all authorizations

Use this to retrieve all authorizations matching specific criteria, such as belonging to a property or reservation:

GET /booking/v1/authorizations

Cancel an authorization

Cancel an authorization that is no longer needed. If you do not cancel it manually, it will expire automatically on its expiration date.

PUT /booking/v1/authorization-actions/{id}/cancel

Expire a payment link authorization

If the authorization was created by link and the guest has not yet acted on it, you can expire the link early. If not expired manually, it will expire on the payment link’s expiration date.

PUT /booking/v1/authorization-actions/{id}/expire-payment-link

Refresh an authorization — change amount or extend

Use the refresh endpoint to either change the blocked amount or extend the authorization period. Both operations use the same endpoint:

PUT /booking/v1/authorization-actions/{id}/refresh

• To change the amount — include the new amount in the request body. The hold on the guest’s card will be adjusted accordingly.
• To extend the authorization — call the endpoint without specifying an amount. The expiry date resets to 28 days from the refresh date (may vary by card scheme).

You can only refresh a successful authorization that has not yet expired.

Capture an authorization against a folio

Once the guest’s charges are known — at check-out, for example — capture the held amount and post it to the folio.

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

{
  "transactionReference": "IUSENHBB",
  "referenceType": "AuthorizationId",
  "amount": {
    "amount": 330,
    "currency": "EUR"
  }
}

Set referenceType to AuthorizationId. This tells Apaleo to look up the authorization by its Apaleo ID rather than a PSP reference.

Do not include paidCharges in this request. An authorization hold is placed before charges exist — you are capturing a blocked amount, not settling specific line items.

The scope of what can be captured depends on where the authorization was created:

• Reservation-level authorization — can only be used to pay charges on folios belonging to that reservation.
• Booking-level authorization — can be used to pay charges on any folio within the booking, including folios across all reservations in that booking.

Payments are processed asynchronously. Use the Location header to poll for the payment status. Payments time out after 60 minutes.