Payment Accounts

A payment account in Apaleo is a tokenised, stored representation of a guest’s payment method — what the industry commonly calls “card on file”. It can be a credit card, debit card, or alternative payment method that has been authorised for recurring charges.

Payment accounts are always stored on a reservation or booking. Once stored, they can be used to charge the guest at any point during or after the stay — for room charges, incidentals, no-shows, or late cancellations — without the guest needing to provide their card details again.

All payment account endpoints are in the Apaleo Booking API. Refer to the Booking V1 Swagger documentation for the full API reference.

Ways to create a payment account

There are four ways to create a payment account in Apaleo. Choose the one that matches your integration:

How payment accounts are created

Via Adyen Drop-in

When a guest completes a payment through Adyen Drop-in, Adyen tokenises the card and returns the token in the /payments response as recurring.recurringDetailReference. Drop-in handles card encryption automatically — your application never handles raw card data.

Apaleo does not store the payment account automatically. Your application must pass the payment account details — including the token and shopperReference — to Apaleo explicitly. You can do this either:

• As part of the booking creation call (pass the paymentAccount in the booking payload — see Booking examples)
• After the booking is created, using POST /booking/v1/payment-accounts/by-stored-payment-method

To enable tokenisation via Drop-in, set storePaymentMethod: true, shopperReference, and recurringProcessingModel: UnscheduledCardOnFile in your Drop-in configuration. See Accept online payments for the full setup.

Via a zero-amount authorisation (IBE flow)

If your IBE performs a zero-amount authorisation to validate the guest’s card at booking time, follow the three steps below to tokenise the card with Adyen and register the resulting token in Apaleo.

Zero-amount authorisation flow

Step 1 — Make the authorisation request to Adyen

Call POST /payments from your server with a zero amount and tokenisation enabled. The encrypted card data comes from Adyen Drop-in’s onSubmit event.

POST https://checkout-test.adyen.com/v69/payments

{
  "amount": {
    "value": 0,
    "currency": "EUR"
  },
  "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": "Jane Shopper"
  },
  "reference": "YOUR_ORDER_REFERENCE",
  "shopperReference": "32ca2e32-6133-4afa-99da-5a0558075e49",
  "shopperInteraction": "Ecommerce",
  "recurringProcessingModel": "UnscheduledCardOnFile",
  "storePaymentMethod": true,
  "merchantAccount": "ApaleoGmbHCOM",
  "returnUrl": "https://your-company.com/checkout/return",
  "additionalData": {
    "metadata.flowType": "CaptureOnly",
    "metadata.accountId": "DEMO",
    "metadata.propertyId": "MUC",
    "subMerchantID": "CWWVG78PRG8AWNK"
  }
}

Required parameters:

Step 2 — Retrieve the token from the Adyen response

If the authorisation is successful, Adyen returns the token in the response:

{
  "pspReference": "851570021506441J",
  "resultCode": "Authorised",
  "additionalData": {
    "tokenization.storedPaymentMethodId": "M5N7TQ4TG5PFWR50",
    "recurring.shopperReference": "32ca2e32-6133-4afa-99da-5a0558075e49"
  }
}

Store the storedPaymentMethodId, pspReference, and shopperReference from the response. You will need them in the next step to register the payment account in Apaleo.

storedPaymentMethodId replaces the older recurringDetailReference field in newer Adyen APIs. If you see recurringDetailReference in older responses, treat it the same way.

If the token is missing from the response (can happen with some asynchronous payment methods), fetch it using the shopperReference:

GET https://checkout-{prefix}.adyen.com/v71/storedPaymentMethods
  ?merchantAccount=ApaleoGmbHCOM
  &shopperReference=32ca2e32-6133-4afa-99da-5a0558075e49

Each item’s id in the response is the storedPaymentMethodId.

Step 3 — Register the payment account in Apaleo

Once you have the token, register it in Apaleo. Use the endpoint that matches what you have from step 2.

Option A — You have the storedPaymentMethodId

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

{
  "target": {
    "type": "Booking",
    "id": "KYKXKLWL"
  },
  "payerReference": "32ca2e32-6133-4afa-99da-5a0558075e49",
  "storedPaymentMethodId": "M5N7TQ4TG5PFWR50"
}

Set "type" to "Reservation" and the reservation ID if you want to attach the payment account to a specific reservation rather than the whole booking.

If you want to use the most recent authorisation for a shopperReference without looking up the exact token, set storedPaymentMethodId to "LATEST".

Key fields:

Option B — You have an Apaleo payment transaction ID or pspReference

Use this if you do not have the storedPaymentMethodId but you have either the Apaleo payment transaction ID or the pspReference from the authorisation:

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

{
  "target": {
    "type": "Booking",
    "id": "KYKXKLWL"
  },
  "payerReference": "32ca2e32-6133-4afa-99da-5a0558075e49",
  "transactionReference": "851570021506441J"
}

Set transactionReference to the Apaleo payment transaction ID or the pspReference returned from the Adyen /payments response.

Retrieve a payment account

To retrieve a specific payment account by its ID:

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

Common mistakes

Missing shopperReference — no token will be created by Adyen. Always include it on every authorisation request.

Missing storePaymentMethod: true — the payment will succeed but no token will be created. The card cannot be charged later.

Missing recurringProcessingModel — tokenisation will not be set up correctly even if the payment succeeds. Future merchant-initiated charges will fail.

Wrong payerReference in Apaleo — the payerReference must exactly match the shopperReference used in the Adyen authorisation. A mismatch means Apaleo cannot link the token to the correct guest, and future charges will fail silently.

prePaymentAmount exceeds the authorised amount — the prePaymentAmount passed when creating the booking must be less than or equal to the amount authorised in the Adyen payment request. If it exceeds the authorised amount, the capture will fail.

Relying solely on the synchronous response for the token — some payment methods return the token asynchronously. Always have a fallback to fetch it via GET /storedPaymentMethods if it is missing from the /payments response.