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

<make_reservation>
<user_id>demo</user_id>
<crypto_block>U_--LfP7rp3MoitCr2ofVaNShLkdOlMurxfADnkYLSOFxUoQo
YUZz_Kq23SaaVvPmF43Ndbq2o1t5Nq60tvNucAoeODYcVYViU_lXNIqmcKQa9ID
lXCTGZEvwqddnGIUevnZY</crypto_block>
<trolley_token>M2--2GJtF2mPyKFtMCwqIIB_-MwqruvxEvZd65EDPSomn7jp
aY8wMlDEfE0aR8n4BVFi_hQ9qfSrxAlTJWCaScnRZTALRMyVpi4yAIurPnH28Jv
nXcDTP53yUcoi0c0sTpY80I9jzXnWDZrGmyryYP_WSrY31S9yeu5JmXolM9iV1M
d7Y3YED7aJwzWIeqkB7h_saLv2WaHL9j-5f-ORutfVPSsYZKXgQLmCiTTebkq1U
yLE2lSeUdvSjKc8XqZENBc_idOr5hTMQvmxhyCBgdZR5Bjy6gOorFCr1XyCqbO8
7hFMxHwXW605tAHVHnvB3iSPgVvvZYOkeGuQjSiSDGuLSCsa6FP2Rdb7nZsxdoO
R6LKlHWSKjGHo5---Z</trolley_token>
</make_reservation>

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

<make_reservation_result>
<crypto_block>U4--BSro8S0HG3xBzCMFTcex-Pga_4Lq6ovGfmwjM5zN8vcYU
QEL6iX_nPn29FvBUAyCFf_DFP1JopqaSaH7v4kaGdwLQOD--hMnwmgP1ckwncRj
qSQ2I4Qq3B9JmGSbjY7GEwwQ2lmATJbpHdKB0jL-AQfoS_BBjujD5-2yiJ2J7Sw
Z9kSAsELH2JCUOJddkrb6MZntCcFrdeLJYJCCFV4MK1t3xj80CzdafdJZCnBwr6
d7x2MZWdA85i4sRGpq3_z3oSv5w8FZI-yc6JuiBrWV-asiRbt8qN_vkqatZKuEz
ZdVOCFM_2QFvuPcwpOaME7h2Itl8NCPiWmrAEg0MBZ41pazEMHPdz1xnGnM4LEq
UzUhrOdf76N2zYsUvBjhamq5qSK5s5iztdoNT__aHN0ctF8DyuhaEzpxuqO82Zl
wBMUTud3ZCnYPxQFP7AoaQTA7Evxtt6rEfgRd3qSnEoWcK4egauQccXS1hKa30x
NLA0x_TDODXYD-F8sIf3Q07XqbIAm7_910C-srJ_kLx_nSvg9hgLdsQ2uztGY-w
T4M9m9-Z</crypto_block>
<transaction_id>AE6D-6F28-D9AE-2877</transaction_id>
<minutes_left_on_reserve>10.000</minutes_left_on_reserve>
<failed_orders/>
<need_payment_card>yes</need_payment_card>

<acceptable_cards>
<card>
<card_type>mastercard</card_type>
<card_desc>Mastercard</card_desc>
</card>

<card>
<card_type>switch</card_type>
<card_desc>Switch</card_desc>
</card>

<card>
<card_type>visa</card_type>
<card_desc>VISA/Delta</card_desc>
</card>
</acceptable_cards>

<supports_billing_address>no</supports_billing_address>
<needs_email_address>yes</needs_email_address>
<needs_agent_reference>no</needs_agent_reference>

<prefilled_customer_data>
<can_edit>no</can_edit>
<address_line_one>Ingresso Group Ltd</address_line_one>
<address_line_two>The Metro Building, 1 Butterwick</address_line_two>
<town>Hammersmith</town>
<county>London</county>
<postcode>W6 8DL</postcode>
<country_code>uk</country_code>
<work_phone>020 3137 7407</work_phone>
<home_phone></home_phone>
<email_address></email_address>
</prefilled_customer_data>

<trolley_token>63--8wGlsnLXhW0fmpIifMyoA6rd2b1bMktBOJQ612kwikoz
xBnduwhe-Mf2bqWfGFlaiwhKgu1slbNIFM6a73O4q6MtvVDRPYiEF7xbGSUuAj-
eqowm7Q35mLOGw7FcEMnrBb3zo-6TxrGjnreP46jJ2YIA9TFmgGABE1gz283a4W
uYBuQe6ePh-rEaegcR98UjmuquYeLTnrh6By39GVhhX9K-LblH9T3ZGm3ZyXapm
xXkHkMJkveVRZR2cGvs_Rdx1MYAsVJD4npJhtXRzGJTqLan9Omy6D0OPKQVVILF
5mrsvlUAY4bQESCw_JNfDkNvR1fXOmW9ZFhT_3eLJLHVuq0oJm2M9QnIwmeMHeh
hfhtzveFAMCVpY78IJ08fkWjeYi5oCvppsbB24VOUj-W7m9bM89rd9SjWL3FdJa
ZAY5JHbSOLE2w7R_--Z</trolley_token>
<trolley_order_count>2</trolley_order_count>
</make_reservation_result>

17.3. Potential failure codes

  • 1 - the supplied crypto block was not generated by
    “start_session”
  • 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