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.
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.
Example input
~~~~~~~~~~~~~
.. code-block:: xml
demo
U_--LfP7rp3MoitCr2ofVaNShLkdOlMurxfADnkYLSOFxUoQo
YUZz_Kq23SaaVvPmF43Ndbq2o1t5Nq60tvNucAoeODYcVYViU_lXNIqmcKQa9ID
lXCTGZEvwqddnGIUevnZY
M2--2GJtF2mPyKFtMCwqIIB_-MwqruvxEvZd65EDPSomn7jp
aY8wMlDEfE0aR8n4BVFi_hQ9qfSrxAlTJWCaScnRZTALRMyVpi4yAIurPnH28Jv
nXcDTP53yUcoi0c0sTpY80I9jzXnWDZrGmyryYP_WSrY31S9yeu5JmXolM9iV1M
d7Y3YED7aJwzWIeqkB7h_saLv2WaHL9j-5f-ORutfVPSsYZKXgQLmCiTTebkq1U
yLE2lSeUdvSjKc8XqZENBc_idOr5hTMQvmxhyCBgdZR5Bjy6gOorFCr1XyCqbO8
7hFMxHwXW605tAHVHnvB3iSPgVvvZYOkeGuQjSiSDGuLSCsa6FP2Rdb7nZsxdoO
R6LKlHWSKjGHo5---Z
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.
Example output
~~~~~~~~~~~~~~
.. code-block:: xml
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
AE6D-6F28-D9AE-2877
10.000
yes
mastercard
Mastercard
switch
Switch
visa
VISA/Delta
no
yes
no
no
Ingresso Group Ltd
The Metro Building, 1 Butterwick
Hammersmith
London
W6 8DL
uk
020 3137 7407
63--8wGlsnLXhW0fmpIifMyoA6rd2b1bMktBOJQ612kwikoz
xBnduwhe-Mf2bqWfGFlaiwhKgu1slbNIFM6a73O4q6MtvVDRPYiEF7xbGSUuAj-
eqowm7Q35mLOGw7FcEMnrBb3zo-6TxrGjnreP46jJ2YIA9TFmgGABE1gz283a4W
uYBuQe6ePh-rEaegcR98UjmuquYeLTnrh6By39GVhhX9K-LblH9T3ZGm3ZyXapm
xXkHkMJkveVRZR2cGvs_Rdx1MYAsVJD4npJhtXRzGJTqLan9Omy6D0OPKQVVILF
5mrsvlUAY4bQESCw_JNfDkNvR1fXOmW9ZFhT_3eLJLHVuq0oJm2M9QnIwmeMHeh
hfhtzveFAMCVpY78IJ08fkWjeYi5oCvppsbB24VOUj-W7m9bM89rd9SjWL3FdJa
ZAY5JHbSOLE2w7R_--Z
2
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