Make a payment

After the guest selects the Pay button or chooses to pay with a payment method that requires a redirection, you need to make a make a /payments request, but before you do that, you need to tokenize the guest’s card details for Payment Card Industry (PCI) compliance.

Authorize payments

The authorization lets you hold an amount on a guest’s credit card or charge the amount from an alternatve payment method for 2 hours. Wthin this time you can use the reference to the authorized transaction to send it in with a booking or use it to post the full or partial amounts on a reservation folio by using POST /finance/v1/folios/{folioId}/payments/by-authorization on the Finance API.

The flow type captureOnly tells the apaleo backend how to proceed with such authorization. We put this authorization into the queue awaiting the respective booking to be created or payment to be posted.

It depends on the guaranteeType of the booking (rate plan) and the payment automation settings. As soon as the booking arrives, we capture the proper amounts for each reservation and commit the payment(s). You also must pass on the transaction reference in the booking. If we do not receive a booking for such an authorization within two hours, we will automatically cancel the authorization to unblock the guest’s card money.

You must set the deliveryDate to the earliest arrival of all reservations in the booking so that the payment processor can calculate the potential exposure to chargebacks regarding prepaid reservations correctly and hold back sufficient funds to cover this risk.

If you want to make a booking with rooms from different properties, you can still only send one apaleo property ID. You could take the ID for the property that has the most significant portion of rooms or revenues in the whole booking. The money will be paid out to the bank account of this property then.

Tokenize a payment account

Tokenization takes on the burden of securely managing cardholder data, thus reducing the costs of meeting and monitoring Payment Card Industry (PCI) compliance. A token is created after a successful payment authorization to ensure that the guest’s payment details are linked to an active, chargeable account.

Create a token and make the payment

When the shopper selects to pay, Drop-in calls the onSubmit event, which contains a

  1. Pass the to your server.
  2. From your server, make a /payments request, specifying:
    • paymentMethod: The from the onSubmit event.
curl \
-H "X-API-key: [Your API Key here]" \
-H "Content-Type: application/json" \
-d '{
   "amount": {
    "currency": "EUR",
    "value": 0
      "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":"John Smith"
  "deliveryDate": "2021-08-17T16:00:00.000+01:00",
  "enableOneClick": false,
  "enableRecurring": true,
  "shopperReference": "575b0100-b261-4a36-94cb-eeb49f7c98d3",
  "shopperInteraction": "Ecommerce",
  "recurringProcessingModel": "UnscheduledCardOnFile",
  "additionalData": {
    "metadata.flowType": "CaptureOnly",
    "metadata.accountId": "DEMO", // The apaleo account id
    "metadata.propertyId": "MUC", // The apaleo property id
    "subMerchantID": "48C27Z5QRX3QJBM" // The sub-merchant id
  "returnUrl": "",
  "merchantAccount": "ApaleoGmbHCOM"

The /payments response contains:

After you’ve made the payment request to Adyen, you will receive a response that looks similar to the following:

  "additionalData": {
    "expiryDate": "9/2022",
    "cvcResult": "0 Unknown",
    "authCode": "084985",
    "avsResult": "0 Unknown",
    "cardHolderName": "Expedia VirtualCard",
    "cardSummary": "0211",
    "paymentMethod": "mc",
    "refusalReasonRaw": "00 : Approved or completed successfully",
    "acquirerCode": "AdyenMasterCard_13445",
    "acquirerReference": "927513404474",
    "recurring.recurringDetailReference": "8415689021960227",
    "recurringProcessingModel": "UnscheduledCardOnFile",
    "recurring.shopperReference": "575b0100-b261-4a36-94cb-eeb49f7c98d3"
  "pspReference": "851570021506441J",
  "resultCode": "Authorised",
  "merchantReference": "YOUR_ORDER_NUMBER_Hsz7365uehhgGFFS"

Handle the redirect (3D secure)

The following example shows a /payments response with action.type: redirect.

       "resultCode": "RedirectShopper",
       "action": {
         "paymentMethodType": "scheme",
         "url": "",
         "data": {
           "MD": "OEVudmZVMUlkWjd0MDNwUWs2bmhSdz09...",
           "PaReq": "eNpVUttygjAQ/RXbDyAXBYRZ00HpTH3wUosPfe...",
           "TermUrl": ""
         "method": "POST",
         "type": "redirect"

Handle the redirect result

When the shopper completes authentication, the payment is authorized. The shopper is redirected back to the returnUrl from your /payments request. The redirect is via an HTTP GET and is appended with the Base64-encoded redirectResult.

Verify the payment result, make another API request with the redirectResult parameter:

  1. URL-decode the redirectResult, and pass it to your server.
  2. From your server, make a /payments/details request specifying:
    • details: Object that contains the decoded redirectResult.
 curl \
 -H "x-API-key: YOUR_X-API-KEY" \
 -H "content-type: application/json" \
 -d '{
      "details": {
        "redirectResult": "eyJ0cmFuc1N0YXR1cyI6IlkifQ=="

The /payments/details response contains:

     "resultCode": "Authorised",
     "pspReference": "88154795347618C"

Result codes allow you to understand the current state of a payment. For more information, see result codes.

To get additional details about a payment transaction, see Read transaction details (PSP) and Read transaction details (merchant reference).