External Payment Account

A Payment Account in apaleo refers to what is commonly refered to as Card on File, or a tokenized credit card, but it can also be other alternative payment methods that are tokenized. In apaleo they can be stored on a reservation or on a booking. The authorization call must also include specific parameters to indicate that this is a recurring authorization.

To create a Payment Account in apaleo using an external recurring authorization you need to call the endpoints:

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

See Payment Accounts in Apaleo - by-stored-payment-method or

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

See Payment Accounts in Apaleo - by-authorization

Example for Adyen classic integration

Using endpoint /pal/servlet/Payment/v68/authorise

shopperReference is the unique identifier to use when storing this recurring authorization

The value of shopperReference is then what should be used when creating or updating a payment account in apaleo. In the apaleo API model for PaymentAccount it is refered to as the payerReference.

Important parameters:

  "shopperReference": "32ca2e32-6133-4afa-99da-5a0558075e49",
  "recurring": {
    "contract": "RECURRING"
  },
  "recurringProcessingModel": "UnscheduledCardOnFile",

Complete request example

{
  "amount": {
    "currency": "EUR",
    "value": 0
  },
  "reference": "Test20230316-2",
  "merchantAccount": "ApaleoGmbHUAT",
  "shopperInteraction": "Ecommerce",
  "shopperReference": "32ca2e32-6133-4afa-99da-5a0558075e49",
  "recurring": {
    "contract": "RECURRING"
  },
  "recurringProcessingModel": "UnscheduledCardOnFile",
  "card": {
    "cvc": "737",
    "expiryMonth": "03",
    "expiryYear": "2030",
    "holderName": "John Doe",
    "number": "4111111111111111"
  },
  "metadata": {
    "accountId": "DEMO",
    "propertyId": "JPOB"
  }
}

Example for Adyen Checkout integration

Using endpoint https://checkout-*/v69/payments

Important parameters:

   "shopperInteraction": "Ecommerce",
   "recurringProcessingModel": "UnscheduledCardOnFile",
   "storePaymentMethod": "true",

Complete request example

{
   "amount":{
      "value":0,
      "currency":"USD"
   },
   "paymentMethod":{
      "type":"scheme",
      "number":"4111111111111111",
      "expiryMonth":"10",
      "expiryYear":"2020",
      "cvc":"737",
      "holderName":"John Smith"
   },
   "reference":"YOUR_ORDER_NUMBER",
   "shopperReference":"YOUR_UNIQUE_SHOPPER_ID_IOfW3k9G2PvXFu2j",
   "shopperInteraction": "Ecommerce",
   "recurringProcessingModel": "UnscheduledCardOnFile",
   "storePaymentMethod": "true",
   "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
   "returnUrl":"https://your-company.com/..."
}

How to Get storedPaymentMethodId When Authorizing a Recurring Payment with Adyen

What is it? storedPaymentMethodId is Adyen’s token that represents a shopper’s saved payment details. You create it during an initial payment (or a zero‑value store), and then reuse it for subsequent charges.

TL;DR

  1. Include storePaymentMethod: true, shopperReference, and an appropriate recurringProcessingModel in your /payments request.
  2. Read the token from additionalData.tokenization.storedPaymentMethodId in the payments response (when present).
  3. You can always fetch tokens later with GET /storedPaymentMethods (each item’s id is the storedPaymentMethodId).

Send the authorization with tokenization enabled

To create a token while authorizing a payment, add these fields to your /payments request:

  • storePaymentMethod: true
  • shopperReference: your unique user ID
  • recurringProcessingModel: UnscheduledCardOnFile
  • shopperInteraction: "Ecommerce" for the shopper‑present transaction that creates the token

These parameters are required for token creation in the Advanced flow.
Refs: Advanced flow – Tokenization parameters, Tokenization overview

Example /payments request (cards)

POST /v69/payments

Sample request:

{
  "merchantAccount": "YOUR_MERCHANT",
  "amount": { "currency": "EUR", "value": 0 },
  "reference": "ORDER-12345",
  "paymentMethod": {
    "type": "scheme",
    "encryptedCardNumber": "test_4111111111111111",
    "encryptedExpiryMonth": "test_03",
    "encryptedExpiryYear": "test_2030",
    "encryptedSecurityCode": "test_737",
    "holderName": "Jane Shopper"
  },
  "shopperReference": "user_123",
  "shopperInteraction": "Ecommerce",
  "recurringProcessingModel": "CardOnFile",
  "storePaymentMethod": true,
  "returnUrl": "https://your.site/checkout/return"
}

Where you receive the token (storedPaymentMethodId)

You will get the token in:

In the /payments response (when available)

If the transaction result is Authorised, some payment methods return:

additionalData.tokenization.storedPaymentMethodId

and

pspReference

Sample (truncated) response:

{
  "pspReference": "ABC1234567890",
  "resultCode": "Authorised",
  "additionalData": {
    "tokenization.storedPaymentMethodId": "M5N7TQ4TG5PFWR50"
  }
}

Store storedPaymentMethodId together with the shopperReference and optionally pspReference.

Alternative: list tokens later

To fetch all tokens for a shopper, call:

GET /v71/storedPaymentMethods?merchantAccount=...&shopperReference=...

Each entry’s id is the storedPaymentMethodId you use for payments.

Example (truncated):

{
  "storedPaymentMethods": [
    {
      "type": "scheme",
      "brand": "visa",
      "expiryMonth": "03",
      "expiryYear": "2030",
      "lastFour": "1111",
      "id": "M5N7TQ4TG5PFWR50"
    }
  ]
}

Common gotchas

  • Missing shopperReference → no token will be created.
  • Missing recurringProcessingModel on the create call → tokenization won’t be set up correctly.
  • Relying only on the synchronous /payments response → can miss tokens for asynchronous methods
  • Expecting a different field name → in /storedPaymentMethods and /paymentMethods responses, the token appears as id; use that value as storedPaymentMethodId.

Quick FAQ

Q: Is storedPaymentMethodId the same as recurringDetailReference?
A: Yes—storedPaymentMethodId replaced the older recurringDetailReference naming across newer Checkout APIs. You will still see id in list APIs which maps to storedPaymentMethodId.

Q: Can I update card details without changing the token?
A: Expiry, holder name, and billing address can be updated without changing the token; for new card numbers, a new token is created.

References