Order overview
Order lifecycle
Understanding the Connect order lifecycle is essential for a successful Connect integration. While each order may vary depending on various factor, the overall flow is as follows.
Note: These steps are conceptual only, and do not map directly to API calls. Each step may or may not involve many calls which are described in detail elsewhere.
1. User session is created
A user session is represented by a user session ID string that should be unique within the Connect instance (we recommend a GUID). This can be either created by the client application or via the CreateOrder end-point. This ID will be passed in all subsequent calls representing the customer's order.
2. Loyalty member is signed in
While not required to make an order, loyalty members should sign in before the order gets underway to ensure that they can use any loyalty recognition rewards they have earned, or purchase any of the tickets/concessions that are only available to loyalty members.
3. Order is created
Typically an order is built using the various ticketing and concession end-points to add, remove, or adjust items on the order until the customer is happy with their order and is ready to pay.
4. Payment is made
While it is possible to make an order of zero value, payment is usually required before the order can be completed. Payment can be done through Vista or done externally to Vista (essentially skipping to the final step in the order lifecycle).
5. Order is completed
The final step is completing the order. This is the most complicated step as it involves several sub-actions:
- Acknowledgement that sufficient payment has been made to cover the order
- Recording of customer information
- Actual commitment of the transaction in the back-end
- Recording of transaction into loyalty if required, including the earning or redemption of loyalty points/rewards
- Sending an email confirmation to the customer regarding their order, if required
Types of order (booking mode)
There are three discrete types of order that can be made through Connect. This is surfaced through the API via the BookingMode property which can be specified when modifying the order or by retrieving the order.
Paid booking
This is the standard order type. This type of order has a non-zero price and it is assumed the customer will pay for the order before it is completed in Connect. This order will appear as a committed transaction downstream and can be subsequently collected at cinema or refunded. The BookingMode must be set on the Connect order before CompleteOrder is called in this scenario.
Unpaid booking
This is an order that has a non-zero price but the customer will not pay for it during the Connect transaction. Instead they will pay for it later either at cinema or via the PayForUnpaid booking end-point.
Zero-value booking
This order has a zero price for the customer and often arises when customers use vouchers and/or loyalty recognitions to purchase tickets and no booking fees are configured.
For paid bookings the client does not need to specify the booking mode however for unpaid and zero-value scenarios it should explicity be set in order to ensdure order completion occurs correctly and appropriate booking fees are calculated.
Example call flow: ordering a ticket (seat first)
This section outlines the minimal calls required to order a ticket at a cinema with ID 0001 for a session with ID 1234. Response information not relevant to the example has been truncated.
Create user session
POST: /orders
Request:
{
"cinemaId": "0001"
}
Response:
{
"order": {
"cinemaId": "0001",
"userSessionId": "a53ac319775849499dd04fd23a6c867b",
"orderTotalValueInCents": 0,
"bookingFeeTotalValueInCents": 0,
"loyaltyPointsTotalCost": [],
"sessions": [],
"concessions": [],
"appliedGiftCards": [],
"expiryDateUtc": "2017-11-22T22:48:53.7561644Z",
"hasCardPaymentPromotionTickets": false,
"promotionCards": []
},
"suggestedDeals": null
}
Sign in loyalty member
POST: /RESTLoyalty.svc/member/validate
Request:
{
"UserSessionId": "a53ac319775849499dd04fd23a6c867b",
"MemberEmail": "victor.lazlo@email.com",
"MemberPassword": "********",
"ReturnMember": true
}
Response:
{
"LoyaltyMember": {
"FirstName": "Victor",
"FullName": "Victor Lazlo"
},
"Result": 0
}
Get seat plan for selected session
GET: /RESTData.svc/cinemas/0001/sessions/1234/seat-plan
Response:
{
"ResponseCode": 0,
"SeatLayoutData": {
"AreaCategories": [
{
"AreaCategoryCode": "0000000001",
"IsInSeatDeliveryEnabled": true
}
],
"Areas": [
{
"AreaCategoryCode": "0000000001",
"ColumnCount": 20,
"Description": "Standard",
"IsAllocatedSeating": true,
"Number": 1,
"NumberOfSeats": 216,
"RowCount": 18,
"Rows": [
{
"PhysicalName": "P",
"Seats": [
{
"Id": "16",
"OriginalStatus": 0,
"Position": {
"AreaNumber": 1,
"ColumnIndex": 2,
"RowIndex": 1
},
"Priority": 0,
"SeatStyle": 0,
"SeatsInGroup": null,
"Status": 0
},
{
"Id": "15",
"OriginalStatus": 0,
"Position": {
"AreaNumber": 1,
"ColumnIndex": 3,
"RowIndex": 1
},
"Priority": 0,
"SeatStyle": 0,
"SeatsInGroup": null,
"Status": 0
}
]
}
]
}
]
}
}
Select a seat
POST: /orders/a53ac319775849499dd04fd23a6c867b/sessions/1234/set-tickets
Request:
{
"tickets": [
{
"ticketDetails": null,
"seats": [
{
"AreaNumber": 1,
"ColumnIndex": 2,
"RowIndex": 1
}
]
}
]
}
Response:
{
"order": {
"cinemaId": "0001",
"userSessionId": "a53ac319775849499dd04fd23a6c867b",
"orderTotalValueInCents": 0,
"bookingFeeTotalValueInCents": 0,
"loyaltyPointsTotalCost": [],
"sessions": [
{
"id": 1234,
"filmTitle": "Airplane!",
"filmClassification": "M",
"startTime": "2017-11-26T16:15:00+12:00",
"allocatedSeating": true,
"tickets": [
{
"ticketDetails": {
"ticketTypeCode": null,
"description": null
},
"seats": [
{
"areaCategoryCode": "0000000001",
"areaNumber": 1,
"rowIndex": 1,
"columnIndex": 2,
"rowDisplay": "P",
"columnDisplay": "15"
}
]
}
]
}
],
"concessions": [],
"appliedGiftCards": [],
"expiryDateUtc": "2017-11-23T00:29:30.4553801Z",
"hasCardPaymentPromotionTickets": false,
"promotionCards": []
},
"suggestedDeals": []
}
Get available tickets
GET: /RESTData.svc/cinemas/0001/sessions/1234/tickets
Response:
{
"ResponseCode": 0,
"Tickets": [
{
"AreaCategoryCode": "0000000001",
"CinemaId": "0001",
"Description": "Adult",
"IsAvailableAsLoyaltyRecognitionOnly": false,
"IsAvailableForLoyaltyMembersOnly": false,
"PriceGroupCode": "0017",
"PriceInCents": 1500,
"QuantityAvailablePerOrder": 3000,
"TicketTypeCode": "0022"
}
]
}
Select a ticket
POST: /orders/a53ac319775849499dd04fd23a6c867b/sessions/1234/set-tickets
Request:
{
"Tickets": [
{
"TicketDetails": {
"ticketTypeCode": "0022"
},
"Seats": [
{
"AreaNumber": 1,
"ColumnIndex": 2,
"RowIndex": 1
}
]
}
]
}
Response:
{
"order": {
"cinemaId": "0001",
"userSessionId": "a53ac319775849499dd04fd23a6c867b",
"orderTotalValueInCents": 1875,
"bookingFeeTotalValueInCents": 375,
"sessions": [
{
"id": 1234,
"filmTitle": "Airplane!",
"filmClassification": "R",
"startTime": "2017-11-26T16:15:00+12:00",
"allocatedSeating": true,
"tickets": [
{
"ticketDetails": {
"ticketId": 1,
"ticketTypeCode": "0022",
"description": "Adult",
"finalPriceInCents": 1500,
"originalPriceInCents": 1500
},
"seats": [
{
"areaCategoryCode": "0000000001",
"areaNumber": 1,
"rowIndex": 1,
"columnIndex": 3,
"rowDisplay": "P",
"columnDisplay": "15"
}
]
}
]
}
],
"expiryDateUtc": "2017-11-23T01:26:50.1543587Z"
}
}
Complete order
Assuming that payment is handled externally to Vista.
POST: /RESTTicketing.svc/order/payment
Request:
{
"PerformPayment": false,
"UserSessionId": "a53ac319775849499dd04fd23a6c867b",
"CustomerName": "Victor",
"CustomerEmail": "victor.lazlo@email.com",
"BookingMode": 0,
"PaymentInfo": {
"CardNumber": "411111......1111",
"CardType": "VISA",
"PaymentValueCents": 1875
}
}
Response:
{
"CinemaID": "0001",
"ExtendedResultCode": 0,
"HistoryID": "11351",
"PaymentInfoCollection": [
{
"BillingValueCents": 1875,
"CardNumber": "411111......1111",
"CardType": "VISA",
"PaymentTenderCategory": "CREDIT"
}
],
"Result": 0,
"VistaBookingId": "WKM5579",
"VistaBookingNumber": "3735",
"VistaTransNumber": "3398"
}