17. The make_reservation method

This method is used to take a trolley and to make a reservation for all the orders contained within it. Due to the real-time nature of the ticketing systems it is possible that a product which was available when an order was placed in the trolley has since ceased to be available, thus it is not guaranteed that all the items in the trolley will be reserved successfully. This method may therefore have a “partial success” status in which only a subset of the orders were reserved successfully. The failed orders will be listed in the output if this occurs.

Once a set of orders has been reserved, it is guaranteed to be held for a certain length of time exclusively for the user. During this time an appropriate set of information necessary to complete the purchase must be collected and the reservation purchased. At the end of the time period the reservation will be released back into the pool. The output from this method indicates the information which is needed to make a successful purchase. This always consists of the customer information, but may or may not require payment card details. If a payment card is required then the types of cards which are accepted will be indicated in the output. Customer data includes both an email address and also an “agent reference” which can be generated by the user of the core. These are normally optional, but under certain circumstances may be compulsory. If this is the case then this will also be indicated in the return. If any of the address data may be preffiled then this is also passed back, togteher with a flag indicating whether or not it may be modified.

17.1. Required inputs

A “crypto_block” from “start_session” method must be present. This may come from the original “start_session” or may be one of the crypto blocks produced from any of the other methods which are documented as generating a “start_session” compatible block.

If the “despatch_token” requested corresponds to a method with despatch type of “selfprint” then a “self_print_mode” input is required, with the same value as that passed to the “availability_options” call. For simplicity, is safe always to pass this input even if a non-selfprint method was chosen.

An optional “describe_trolley” element may be present to indicate that the output data should contain the full trolley description.

17.1.1. Example input


17.2. Output data

It is possible that none of the orders in the trolley are available when the reservation request is made, and in this case a completely empty response will be returned. This does not indicate an error from the cores point of view, however, as this is part of the normal operation of the system.

In most cases there will be one or more orders in the trolley which will be placed on reservation in order that they may be purchased. In this case a “crypto_block” will be produced for use as input to the purchase method, or possibly the release method if the purchase is abandoned. The allocated reference for this transaction is available in the “transaction_id” element, and the number of minutes that the reservation will remain held for is returned as “minutes_left_on_reserve”. This is a decimal value and may change according to the amount of time it takes to actually make the reservation, as the time limit begins when the first successful reservation is made from the orders within the bundle. If any of the orders have failed to be reserved then these will be found within the “failed_orders” element. This is always present, but will be empty if the entire trolley was reserved without problem. In the case where some orders failed, then these are described as individual “order” elements within this element, each having the format it would in a trolley description. The failed orders are presented as a flat list, and are no longer grouped into bundles.

Purchases may be made from the system either on-credit (with the user of the core taking the payment, and being invoiced later for the amount) or directly though the core, with the payment being taken directly from a customer’s card. Which of these systems is in use is indicated by the boolean element “need_payment_card” which is always present in the output. If this has the value “yes” then payment card details must be provided. The cards which will be accepted for the transaction are then listed in the element “acceptable_cards” which will be present if a card is required. This consists of a set of “card” elements, each containing the card type in “card_type” and a human description of the type in “card_desc”. The current list of known types is as follows.

  • access - Access
  • amex - American Express
  • diners - Diners Club
  • discover - Discover
  • electron - VISA/Electron
  • fraser - House Of Fraser
  • jcb - JCB
  • magasin - Magasin
  • marks - Marks and Spencer
  • mastercard - Mastercard
  • otb - OTB
  • searsuk - Duet/Sears
  • solo - Solo
  • style - Style
  • switch - Switch (with issue number)
  • switch_ni - Switch (without issue number)
  • visa - VISA/Delta

Some systems are capable of making an address check against a credit card before allowing it to be debited. Under normal circumstances this will be the address provided by the customer. Certain systems may allow a separate billing address to be specified so that the card used for payment need not be registered to the customer’s address. The boolean element “supports_billing_addr” indicates if this is the case. If it is “yes” then a separate address may be provided at purchase time, and this will be used to validate the card address should any such check be made.

For those users who require an email address the boolean element “needs_email_address” will be present containing the value “yes”. Normally this will be set to “yes”. Certain users may also require that an agent reference is always supplied (this is normally optional) and if so the boolean element “needs_agent_reference” will contain the value “yes”. If the reference is optional it will be set to “no”.

Some commercial users, particularly those purchasing on-credit, will have an address already held in the system which should be prefilled for the user. If this is the case then an element “prefilled_customer_data” will be present containing all the address felds, the phone numbers and the email address to be prefilled (even if they are blank). This address is sometimes fixed and may not be edited by the user at all. This is indicated by the “can_edit” element within the prefilled data, which is either “yes” or “no”. Note that even if the address cannot be edited, it is still permissible to fill in any prefilled fields which are blank.

The reserved trolley is embedded in the “crypto_block” to be used as input to the next stages of the process, but so that it can also be described if necessary using the “trolley_describe” method then “trolley_token” and “trolley_order_count” elements are also present in the output. As with the trolley modification methods, it is possible for the full description of the reserved trolley to be presented in the output by the addition of a “describe_trolley” element at the input.

17.2.1. Example output






<address_line_one>Ingresso Group Ltd</address_line_one>
<address_line_two>The Metro Building, 1 Butterwick</address_line_two>
<postcode>W6 8DL</postcode>
<work_phone>020 3137 7407</work_phone>


17.3. Potential failure codes

  • 1 - the supplied crypto block was not generated by
  • 2 - the requested “mime_text_type” was not a supported value
  • 901 - no “trolley_token” has been supplied
  • 902 - the supplied “trolley_token” is corrupt
  • 903 - the trolley has already been purchased
  • 904 - the trolley has already been reserved