The imin Platform
2.0.0
2.0.0
  • Introduction to the imin Platform
  • Using the Platform
    • imin's Platform Products
    • Authentication
    • Our Platform Data
      • Understanding Responses
      • Namespaces and Extensions
      • Defensive Data Consumption
      • Mocking the Interface
  • platform products
    • Search
      • imin Events API
        • Events API Reference
        • Virtual & Physical Sessions
        • Concepts
          • EventSeries
          • ScheduledSessions and eventSchedules
          • Activities and Collections
            • Activities
            • Activity Concept Collections
          • Accessibility Support
          • Prices
        • Filters
          • Modes
          • Age Ranges
          • Dates and Times
          • Activities and Concept Collections
          • High Frequency Sessions
      • imin Facilities API
        • Query Parameter Search
          • Mandatory Query Parameters
            • mode=discovery-geo
            • mode=upcoming-slots
          • Optional Query Parameters
        • ByID Search
          • FacilityUse By-ID
          • Slot By-ID
        • FacilityUses and IndividualFacilityUses
        • Slots
        • Facilities Slot Booking
      • imin Places API [BETA]
        • Example Request & Response
    • Firehose
      • Introduction to the Firehose
      • Accessing the Firehose
      • Firehose Usage Policy & Restrictions
      • Firehose and Search
      • Bookable Firehose Feeds
      • Bookable Sellers Feed
      • Attribution Catalog Endpoint
    • Live Timetables
      • Pre-Requisites: Open Data Feeds
      • The Onboarding Process
        • 1. Ensuring your Data Offers the Best User Experience
        • 2. Setting up and Embedding your First Timetable
        • 3. Setting up the Rest of your Timetables
        • 4. Activating Booking via Guest Checkout
      • Features Available Upon Request
      • Styling the Live Timetables
      • FAQs
    • Data Dashboard
  • incorporating book and pay
    • imin Branded Checkout
      • Introduction
      • Setup
        • Information We Require From You
        • Actions You Need to Complete
      • Authenticated Checkout
        • Testing [BETA]
        • 👪Group Booking [BETA]
      • Standalone Checkout
      • Firehose and Checkout [BETA]
        • Loading the Checkout via Firehose
    • imin Booking Platform
      • Customer Account Management
        • Create Customer Account
        • Update Customer Account
        • Get Customer Account
        • Delete Customer Account
        • Example Scenario
        • Payment Card Management
        • Linked Accounts
        • Entitlement
          • Evidence Requests
          • Entitlement Pricing in Search
          • Entitlement Pricing in Checkout
        • Access Pass
        • Webhooks
      • Orders
        • Order History
        • Order (by ID)
        • Cancellations & Refunds
      • Upcoming OrderItems
      • Receipt (by ID)
  • imin and booking systems
    • Seller Onboarding
      • API
  • HINTS & TIPS
    • Get the Best Out of Search
      • Displaying Schedule Information
      • URLs and Offering a Call to Action
      • Searching by Activity
      • Your Search Results and HighFrequencySessions
      • Customer Specific Images
  • Info for Data Publishers
    • Your RPDE Feed & the imin Platform [BETA]
      • Providing Places Data [BETA]
      • Providing Schedule Information [BETA]
Powered by GitBook
On this page
  • Introduction
  • Request
  • Response
  • Booking Success Webhook
  1. incorporating book and pay
  2. imin Branded Checkout

Authenticated Checkout

PreviousActions You Need to CompleteNextTesting [BETA]

Last updated 2 years ago

Introduction

The Authenticated Checkout allows the Checkout to be pre-populated with a logged-in user's personal details.

To enable Authenticated Checkout, you must register your webhook with imin. This can be done by contacting your imin liaison.

Please only refer to this page if you are using imin's Events API (as opposed to processing open data directly).

Request

Every ScheduledSession and Slot provided via the imin Events API is bookable if and only if it has an imin:checkoutUrlTemplate field. A "book" button can be attached to each of these bookable items.

In order to make an Authenticated Checkout request, you'll need the following information:

  • Opportunity type: Which type of item is being booked. Presently, there are two options:

    • ScheduledSession: An individual session of an . e.g. a Group Run at 11:00 in Victoria Park

    • Slot: A bookable instance of a at a specific time. e.g. a 10:30 - 11:00 slot for a Badminton court in Whitechapel Sports Centre.

  • Opportunity identifier: The .identifier field of the item.

    • For a ScheduledSession, this might look like "https://opendata.fusion-lifestyle.com/OpenActive/api/scheduled-sessions/1234567"

    • For a Slot, this might look like: "https://tmactive.leisurecloud.net/OpenActive/api/slots/8901234"

    This identifies what, where and when the user is booking.

  • Offer id: Identifies the ticket type e.g. "Junior (8-18) £9".

    • For a ScheduledSession, a list of Offers can be found in the SessionSeries that is its parent

    • For a Slot, a list of Offers can be found in the Slot itself.

    Use the .id field of the selected Offer

  • Broker name: Name of the app that Checkout is branded for e.g. "Acme Sports Finder"

  • Broker home page URL: URL for the home page of the organisation that is represented by Broker name e.g. "https://acmesportsfinder.co.uk"

  • Back to Broker URL: URL to use for a "back" button if the customer, for example, decides to go back and choose another session e.g. "https://acmesportsfinder.co.uk/search"

  • Back to Broker User Profile URL: URL to head to customer's user profile, where they can see the bookings they've made e.g. "https://acmesportsfinder.co.uk/users/rebekahspinoza"

  • Customer: This can be either a ID string or a Customer object

    • ID string: e.g. https://book.imin.co/api/v2/customers/qOZtNY9m. This is the imin ID for a Customer Account you've registered with imin. Details on registering Customer Accounts with imin can be found .

    • Customer Object:

      • [OPTIONAL] Broker customer identifier: Customer's ID within your (the Broker's) system e.g. uDeOzNfX. This is not used by imin internally but will be included in the success webhook, helping you to connect successful bookings with your customers.

      • Customer's given name: e.g. "Rebekah"

      • Customer's family name: e.g. "Spinoza"

      • Customer's email: e.g. "rebekahspinoza@email.com"

      • [OPTIONAL][BOOLEAN] Customer is 13 or over?: Is the customer aged 13 years old or over? The customer must be aged 13 or over in order to book.

        • If this field is excluded, Checkout will ask the customer if they are aged 13 years or over. The booking can only continue if they are.

        • If this field is false, Checkout will return a validation error.

Please make sure all URLs included within the Webhook Request includehttps://or http://.

In your production environment, all URLs included within the Webhook Request includehttps://.

The broker customer identifier [OPTIONAL] is specific to you, the broker. For the avoidance of doubt, the customer.identifier is not related to the provider whose session has been booked.

The request then has the following format (replace the values in << name >>with an appropriate value):

POST /api/checkout-sessions HTTP/1.1
Host: checkout.example.com
Date: Mon, 8 Oct 2018 20:52:35 GMT
Accept: application/json

{
  "@context": ["https://openactive.io/", "https://imin.co/"],
  "type": "imin:CheckoutSession",
  "imin:initialOrder": {
    "type": "OrderQuote",
    "customer":{
      "type": "Person",
      "identifier": "<< Broker customer identifier >>",
      "givenName": "<< first name >>",
      "familyName": "<< last name >>",
      "email": "<< email address >>",
      "imin:is13OrOver": << Customer is 13 or over? >>
    },
    // OR "customer": "https://book.imin.co/api/v2/customers/qOZtNY9m", 
    "broker": {
      "type": "Organization",
      "name": "<< broker name >>",
      "url": "<< broker home page URL >>"
    },
    "orderedItem": [
      {
        "type": "OrderItem",
        "acceptedOffer": "<< Offer ID >>",
        "orderedItem": {
          "type": "<< Opportunity type >>",
          "identifier": "<< Opportunity identifier >>"
        }
      }
    ]
  },
  "imin:navigationLinks": [
    {
      "type": "WebPage",
      "name": "Back to Broker",
      "imin:linkType": "https://imin.co/BackToBrokerLink",
      "url": "<< back to broker URL >>"
    },
    {
      "type": "WebPage",
      "name": "Back to Broker User Profile",
      "imin:linkType": "https://imin.co/BackToBrokerUserProfileLink",
      "url": "<< back to broker user profile URL >>"
    }
  ]
}

Response

The response will reflect back the request, but will additionally contain a few other fields:

  • .id: URL of the Checkout Session in the API. This is the same as the Location header. Navigating to this URL will return this exact JSON.

  • ."imin:initialOrder".id: ID of the order itself. This is a URL but it will not necessarily be possible to navigate to it. This is intended behaviour as it's sole purpose is to uniquely identify the order. When an order is successful, a webhook will be called that will use this same id. This way, the OrderQuote returned here and the Order received by the success webhook can be linked.

  • .potentialAction: Includes an OrderAction . This OrderAction represents the next step to continue the order. Redirect the customer to this OrderAction's .target and they will see Checkout loaded with their chosen event and time. They won't need to type in their name or email as these will already be known. The rest of the flow will then continue in the Checkout.

It is advised not to rely on the position in an array of the OrderAction but to instead find the item in the .potentialAction array that has type "OrderAction". In JavaScript this would look like:

const checkoutOrderAction = response.potentialAction.find(item =>
    item.type === 'OrderAction');

The Authenticated Checkout response has the following format:

HTTP/1.1 201 Created
Content-Type: application/json
Location: << your checkout domain >>/api/checkout-sessions/<< an identifier >>

{
  "@context": ["https://openactive.io/", "https://imin.co/"],
  "type": "imin:CheckoutSession",
  "id": "<< your checkout domain >>/api/checkout-sessions/<< an identifier >>",
  "identifier": "BQokikJOvBiI2H",
  "imin:initialOrder": {
    "type": "OrderQuote",
    "id": "https://book.imin.co/api/v2/orders/by-checkout-session/<< an identifier >>",
    "customer":{
      "type": "Person",
      "identifier": "<< Broker customer identifier >>",
      "givenName": "<< first name >>",
      "familyName": "<< last name >>",
      "email": "<< email address >>",
      "imin:is13OrOver": << Customer is 13 or over? >>
    },
    "broker": {
      "type": "Organization",
      "name": "<< broker name >>",
      "url": "<< broker home page URL >>"
    },
    "orderedItem": [
      {
        "type": "OrderItem",
        "acceptedOffer": "<< Offer ID >>",
        "orderedItem": {
          "type": "<< Opportunity type >>",
          "identifier": "<< Opportunity identifier >>"
        }
      }
    ]
  },
  "imin:navigationLinks": [
    {
      "type": "WebPage",
      "name": "Back to Broker",
      "imin:linkType": "https://imin.co/BackToBrokerLink",
      "url": "<< back to broker URL >>"
    },
    {
      "type": "WebPage",
      "name": "Back to Broker User Profile",
      "imin:linkType": "https://imin.co/BackToBrokerUserProfileLink",
      "url": "<< back to broker user profile URL >>"
    }
  ],
  "potentialAction": [
    {
      "type": "OrderAction",
      "name": "Checkout",
      "target": "https://checkout.example.com/checkout-sessions/<< an identifier >>",
     }
  ]
}

Note that the "name" property within WebPage and OrderAction types is deprecated, but must still be included in the request.

Booking Success Webhook

If the customer completes the booking initiated by Authenticated Checkout, imin will call a Booking Success Webhook in your system (please arrange with us to set up your webhook)

The webhook's request has this format:

POST << your webhook URL e.g. http://example.com/webhooks/on-success >> HTTP/1.1
Host: api.example.com
Date: Mon, 8 Oct 2018 20:52:35 GMT
Accept: application/json

{
  "@context": ["https://openactive.io/", "https://imin.co/"],
  "type": "Order",
  "id": "https://book.imin.co/api/v2/orders/by-checkout-session/<< an identifier >>",
  "customer":{
    "type": "Person",
    "identifier": "<< customer identifier >>",
    "givenName": "<< first name >>",
    "familyName": "<< last name >>",
    "email": "<< email address >>",
    "imin:is13OrOver": << Customer is 13 or over? >>
  },
  "broker": {
    "type": "Organization",
    "name": "<< broker name >>",
    "url": "<< broker home page URL >>"
  },
  "orderedItem": [
    {
      "type": "OrderItem",
      "acceptedOffer": "<< Offer ID >>",
      "orderedItem": {
        "type": "<< Opportunity type >>",
        "identifier": "<< Opportunity identifier >>"
      },
      "orderItemStatus": "https://openactive.io/OrderConfirmed",
      "accessToken": [
        {
          "type": "Barcode",
          "text": "<< e.g. "123456" >>"
        }
      ],
      "accessCode": [
        {
          "type": "PropertyValue",
          "name": "Membership ID",
          "value": "<< e.g. "654321" >>"
        }
      ]
    }
  ]
}

If anything fails at any point in the process, the Checkout UI will render the message: "The booking could not be completed, please contact the organiser" (or something to that effect). For the avoidance of doubt, whilst there is a “Success Webhook” and a message for the consumer, there is not a “failure webhook”.

To get more information about the item that's been booked, head to:

  • https://search.imin.co/events-api/v2/scheduled-sessions/{data.identifer} where it is a ScheduledSession; or

  • https://search.imin.co/facilities-api/v2/slots/{data.identifer} where it is a Slot.

NB the data.identifer must be URI encoded.

Event
Facility
here