Checkout

In the context of the Housemates API, the Checkout process is a key feature designed to ensure a smooth, secure, and efficient booking journey. It bridges the gap between the student's selection of their desired accommodation and the confirmation of their booking, aligning the various requirements of multiple accommodation providers into a simple, unified process.

In our API documentation, we present two official solutions for optimising the display of your checkout to your users:

Hosted Checkout (Recommended)

Our Hosted Checkout is the lower-code option, designed to simplify your integration process. This solution equips you with a URL included in the API response, which you can conveniently direct your users to for completing the checkout. Housemates takes care of all the necessary checkout and payment logic, eliminating the need for you to develop a custom checkout solution.

Moreover, you have the flexibility to tailor the visual appearance of the hosted checkout to match your brand or preferences by adjusting the settings within your Connect dashboard. You can read more about this here.

Fully Custom Checkout

You also have the option to design and develop your custom checkout solution, allowing you to capture all the necessary information from the student. Following this, you can utilize the "Complete Checkout" endpoint to submit the collected data. Additionally, we furnish you with pertinent Stripe information, enabling you to securely process payments directly from your students.

The Checkout process consists of two major endpoints, Start Checkout and Complete Checkout, each playing a significant role in managing the booking stages. These endpoints accommodate the diverse needs of different accommodation providers and ensure that all necessary information is captured for successful transaction processing.

As the API user, you'll navigate the student's booking journey, from initiating a checkout session, handling secure payment procedures, to providing essential data to successfully complete the booking. This section will delve deeper into the functionalities and requirements of the 'Start Checkout' and 'Complete Checkout' endpoints, providing a comprehensive understanding of the checkout process within the Housemates API ecosystem.

This section will delve deeper into the functionalities and requirements of the Start Checkout and Complete Checkout endpoints, providing a comprehensive understanding of the checkout process within the Housemates API ecosystem.

Start Checkout

curl -i -X POST \
    'https://api.housemates.io/api/rooms/01H0N7WS7ZN1DGEJFF2C14K8NJ/checkout/start' \
    -H 'X-API-PARTNER-ID: {API_PARTNER_ID}' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer {access_token}' \
    -d '{
        "booking_period_id": {booking_period_id},
        "operator_id": {operator_id}
     }'

{
  "success":true,
  "code":0,
  "locale":"en",
  "message":"OK",
  "data":{
    "stripe":{
      "public_key":"{stripe_public_key}",
      "client_secret":"{stripe_client_secret}"
    },
    "session_token":"a158d1b83393e",
    "checkout_url": "https://your-website.com/01H8PAK22E921ENT260GXAY7F4/start"
  }
}

Complete Checkout

The Complete Checkout endpoint represents the final stage of the booking journey, you only need to utilise this endpoint if you plan to build a fully custom checkout solution. If you are utilising Hosted Checkouts then you don’t to submit data to this endpoint.

Given the diverse portfolio of student accommodation providers that Housemates partners with, each has their unique sets of requirements. To effectively accommodate these various needs and ensure a successful completion of the booking process, the API requires the unique session token, generated during the 'Start Checkout' phase, along with other relevant data.

An important piece of information needed at this stage is the guarantor or emergency contact details. As both types of information share the same data structure, we utilize a unified format for both. However, depending on the payment plan chosen (full payment or instalments) and the geographic location of the property (UK, Australia, or Canada), we present the appropriate contact form to the student, whether that's an Emergency or Guarantor information form.

For a better visual understanding of this process, please refer to the included diagram that outlines the flow of the checkout procedure.

In the context of the Housemates API, the Checkout model holds a pivotal role, enabling a streamlined, secure booking process that caters to a wide range of accommodation providers' requirements, while simultaneously ensuring a friendly and efficient booking experience for the students.

curl -i -X POST \
'https://api.housemates.io/api/rooms/01H0N7WS7ZN1DGEJFF2C14K8NJ/checkout' \
-H 'X-API-PARTNER-ID: {API_PARTNER_ID}' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access_token}' \
-d '{
    "session_token":"a158d1b83393e",
    "paying_in_instalments":true,
    "has_uk_based_guarantor":true,
    "is_using_housing_hand":true,
    "resident_details":{
        "city":"manchester",
        "region":"Greater Manchester",
        "country":"gb",
        "nationality":"gb",
        "postcode":"M1 3DR",
        "first_line":"120 high street",
        "first_name":"John",
        "last_name":"Doe",
        "gender":"male",
        "email":"john.doe@gmail.com",
        "date_of_birth":"01-01-1990",
        "contact_number":"+447904413565"
    },
    "supporting_contact_details":{
        "city":"manchester",
        "region":"Greater Manchester",
        "country":"gb",
        "postcode":"M1 3DR",
        "first_line":"120 high street",
        "second_line":"apartment 1",
        "first_name":"Jane",
        "last_name":"Doe",
        "relationship":"Aunty",
        "email":"jane.doe@gmail.com",
        "date_of_birth":"01-01-1990",
        "contact_number":"+447898807865"
    },
    "course_details":{
        "university":"Manchester University",
        "year_of_study":"Undergraduate - First Year",
        "course_title":"B.Sc Computer Science"
    }
}'

{
    "success":true,
    "code":1020,
    "locale":"en",
    "message":"api.booking_created_successfully",
    "data": {
       "booking_id" : "01H14V1E5EVWGANKXQG7TVYGQ1"
    }
}