Payment Accounts in Apaleo

A Payment Account in apaleo is a secure, tokenized representation of a payment method (such as a credit card or alternative payment method) that can be used for recurring charges. This is similar to what is commonly called “Card on File”. Payment Accounts are always created and stored on a reservation or booking.

A Payment Account indicates that a payment method has been authorized for recurring payments (e.g., for hotel stays, incidentals, or other charges).

You can find the detailed documentation for the API endpoints for Payment Accounts in Apaleo Booking module. Samples here are for illustration please refer to the API swagger documentation for the latest details.

Creating Payment Accounts

Payment accounts can be added to existing bookings or reservations. There are several to create a payment account in Apaleo:

By Terminal

Perform an in-person recurring authorization on a POS terminal by calling:

POST https://api.apaleo.com/booking/v1/payment-accounts/by-terminal

Sample Request:

{
  "target": {
    "type": "Booking",
    "id": "KYKXKLWL"
  },
  "propertyId": "MUC",
  "terminalId": "V400m-324689704"
}

By Payment Link

Create a payment link to share with the guest for remote authorization. The Payment Account remains in “Pending” status until the link is used, cancelled or expired.

POST https://api.apaleo.com/booking/v1/payment-accounts/by-link

Sample Request:

{
  "target": {
    "type": "Booking",
    "id": "KYKXKLWL"
  },
  "propertyId": "MUC",
  "expiresAt": "2025-09-21T15:09:51.2376406Z",
  "countryCode": "DE",
  "description": "Payment information for the booking",
  "payerEmail": "user@email.com"
}

By Authorization - External Recurring Authorization

If the recurring authorization is created outside apaleo (e.g., via a third-party integration), you can use the PspReference or apaleo PaymentTransactionId to create a Payment Account.

POST https://api.apaleo.com/booking/v1/payment-accounts/by-authorization

Sample Request:

{
  "target": {
    "type": "Booking",
    "id": "KYKXKLWL"
  },
  "transactionReference": "K9DTTJQD4HNG5S82"
}

By Stored Payment Method - External Recurring Authorization

Alternatively, you can use an externally authorized shopperReference and storedPaymentMethodId to create a Payment Account. If you want to use the most recent authorization for a shopperReference, set storedPaymentMethodId to "LATEST".

POST https://api.apaleo.com/booking/v1/payment-accounts/by-stored-payment-method

Sample Request:

{
  "target": {
    "type": "Booking",
    "id": "KYKXKLWL"
  },
  "payerReference": "f86de5cf-1989-4c74-9ffa-70e82e852423",
  "storedPaymentMethodId ": "H7EJGJQD4HNG5S75"
}

Retrieving Payment Accounts

Individual payment accounts can be retrieved using their paymentAccountId using:

GET https://api.apaleo.com/booking/v1/payment-accounts/{paymentAccountId}

Sample response:

{
  "id": "QWERTYUI",
  "target": {
    "type": "Booking",
    "id": "ASDFGHJK"
  },
  "created": "2025-09-22T14:47:43.0639487Z",
  "updated": "2025-09-22T15:47:43.0639561Z",
  "externalReference": {
    "paymentTransactionId": "VT6G6BFUR6XE5MHZARAX2ODK7Y"
  },
  "status": "Pending",
  "payerInteraction": "PaymentLink",
  "paymentLink": {
    "expiresAt": "2025-09-23T14:47:43.0639591Z",
    "url": "https://test.adyen.link/PL0E1BC57CAEE63F2F0"
  },
  "accountDetails": {
    "accountNumber": "1111",
    "accountHolder": "John Doe",
    "expiryMonth": "8",
    "expiryYear": "2018",
    "paymentMethod": "visa",
    "payerEmail": "s.hopper@test.com"
  },
  "isVirtual": false,
  "actions": [
    {
      "action": "Cancel",
      "isAllowed": false,
      "reasons": [
        {
          "code": "OnlySuccessfulPaymentAccountCanBeCanceled",
          "message": "Only a successful payment account can be canceled."
        }
      ]
    },
    {
      "action": "ExpirePaymentLink",
      "isAllowed": true,
      "reasons": [
        {
          "code": "OnlyPendingPaymentLinkPaymentAccountCanBeExpired",
          "message": "Only pending payment link can be expired."
        }
      ]
    }
  ]
}

A filtered list of payment accounts can be retrieved using:

GET https://api.apaleo.com/booking/v1/payment-accounts?propertyIds=MUC&reservationIds=RECABC-1&payerInteractions=Terminal&status=Canceled&pageNumber=1

For general information how to use the Apaleo APIs please refer to https://apaleo.dev/guides/api/overview.html

Cancel and Expire Payment Account

An existing Payment Account can be cancelled using:

POST https://api.apaleo.com/booking/v1/payment-account-actions/{paymentAccountId}/cancel

An pending Payment Account Payment Link can be expired using:

POST https://api.apaleo.com/booking/v1/payment-account-actions/{paymentAccountId}/expire-payment-link

Using Payment Account to pay charges

Payment Accounts can be used to create Payment on Reservation Folios using:

POST https://api.apaleo.com/finance/v1/folios/{folioId}/payments/by-payment-account

Sample Request:

{
  "accountOwner": "Guest",
  "paymentAccountId": "KHJLSGSD",

  "amount": {
    "amount": 230,
    "currency": "EUR"
  }
}

Using Payment Account to create an Apaleo Authorization

Payment Account can be used to create Apaleo Authorization using:

POST https://api.apaleo.com/booking/v1/authorizations/by-payment-account

Sample Request:

{
  "target": {
    "type": "Booking",
    "id": "KYKXKLWL",
    "propertyId": "MUC"
  },
  "amount": {
    "amount": 150,
    "currency": "EUR"
  },
  "accountOwner": "Guest",
  "paymentAccountId": "UBMFXUFH"
}