Let's talk about payment rates

📘

Payment Basics

• Configure payment rates and methods per apartment.
• If you have the same rates and payment methods for each apartment, they can be configured on your account level.
• To update the payment rates or payment methods, you need to push the entire object; partial updates are not possible.
• If Holidu handles the payments, then this endpoint should not be developed!

List of Supported payment methods:

The customer expects you to handle the payments. The customer will select one of those payment methods.

Examples

{
     "paymentMethods": [
          "CREDIT_CARD",
          "BANK_TRANSFER"
     ],
     "paymentRates": {
          "ratesPerDate": [
               {
                    "daysBeforeArrival": 30,
                    "rateAmountInPercentage": 50
               },
               {
                    "daysBeforeArrival": 7,
                    "rateAmountInPercentage": 20
               }
          ],
          "ratePaidOnBookingInPercentage": 30
     }
}

In this sample code, you can see that the supported payment methods for this apartment are:

• CREDIT_CARD & BANK_TRANSFER

The payment rates in the sample code are calculated as follows:

• At the time of booking, the amount to be paid is 30%.
• 30 days before check-in, the amount to be paid is 50%.
• 7 days before check-in, the amount to be paid is 20%.

Use case 1: The total amount of the booking is 1000€, and the guest booked 50 days before check-in. Then, at the time of booking, the guest has to pay 300€ (30%), 500€ (50%) 30 days before the check-in day, and the rest 200€ (20%) 7 days before the check-in day.

Use case 2: The total amount of the booking is 1000€, and the guest booked 14 days before check-in. Then, at the time of booking, the guest has to pay 800€ (30% + 50%), and the rest 200€ (20%) 7 days before the check-in day. Similarly, if the booking happens 5 days before check-in, then the full amount of 1000€ (30% + 50% + 20%) should be paid at the time of booking.

⚠️

To remember:

The accumulative sum of configured payment rates can not exceed a hundred percent. The request to the API would fail in that situation.

Using rateId with Payment Configuration

a) Get Payment Configuration (GET /v2/apartments/payment-configuration)
You can retrieve the payment configuration specific to a rate:

Example Request:

GET /v2/apartments/payment-configuration?providerApartmentId=ABC123&rateId=STANDARD

Notes:

• If rateId is provided, you get payment settings for that specific rate.
• Without rateId, you get the default configuration.

b) Delete Payment Configuration (DELETE /v2/apartments/payment-configuration)
You can delete payment configurations for a specific rate:

Example Request:

DELETE /v2/apartments/payment-configuration?providerApartmentId=ABC123&rateId=NON_REFUNDABLE

c) Update Payment Configuration (POST /v2/apartments/payment-configuration)
When creating or updating payment configuration, specify the rateId to target the correct rate:

Example Request Body:

{  
  "rateId": "NON_REFUNDABLE",  
  "paymentMethods": ["credit_card", "paypal"],  
  "paymentRates": [  
    {  
      "paymentMethod": "credit_card",  
      "downPayment": 20,  
      "fullPaymentBeforeArrival": true  
    }  
  ]  
}