The *trolley\_describe* method
==============================
This method takes a "trolley\_token" as an input and produces a full
description of the contents of the trolley. This is broken down in to
"bundles" which correspond to a set of orders from a particular
supplier, and within each bundle the orders are listed individually in
the order in which they were added to the trolley. A trolley may be
described at any point, including after it has been purchased. Extra
information which is acquired during the lifetime of the trolley, such
as reference numbers and seat allocations, will be described in the
output if present.
For the sake of efficiency, all methods which manipulate the contents of
a trolley have the ability to produce a trolley description in their
output. This is to avoid the need to perform a trolley operation and
then follow it immediately with a call to this method in order to
display the results. The final purchase method always produces a full
trolley description, as this contains all the reference codes, seat IDs
and final despatch methods produced by the purchase operation.
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. A "trolley\_token"
holding the trolley to be described must also be present.
Example input
~~~~~~~~~~~~~
.. code-block:: xml
demo
U_--LfP7rp3MoitCr2ofVaNShLkdOlMurxfADnkYLSOFxUoQo
YUZz_Kq23SaaVvPmF43Ndbq2o1t5Nq60tvNucAoeODYcVYViU_lXNIqmcKQa9ID
lXCTGZEvwqddnGIUevnZY
c3--ESt4iSq-0h6ewW5aurWrMlaHazPjAoh6aidaqiycuEQx
b5d3JTr2KnNS_eNj_LC5-RHyLa4O-cKULcjllwjpSzx49vJ0mniPPBFgDeZRkfK
gz1x-gLCqsvdp1DTkgKyWu2_GM6_TV7DX6G1fLRCM7oX6D8j802Rz8lNB2VI7hy
dIva0ixEfHu48UMiYdOREp9XDIwdoYi4R0tFO5ZQt4KUzKRp7Rn9i0UNPyIVtMM
2IRP6ob-Dy-054kpOGnFihWBXBkP4kmSM3LOwxCBxVxjq7y2VlRIGg0Q2wl-W8k
-Ui17qiKMn_ZflHByRyv5MBSkiXrJFOZLKRboPT73uq5oxz3NgRHiCeGULnF345
zp6Jz94huDRbV6w4nSv7CVBgJ_H7iZZJcf08Z5q570AoO9e9hZe44ZDGl5H1L61
QD3KDyCzUS3EH1l8JMEm0kQF1Xb4w2joeUbTP7IPhVPUS4zBNcfQGmoc-IZ
Output data
-----------
The complete trolley description is entirely held within a "trolley"
element. If the trolley has been reserved this begins with the system
wide reference code in a "transaction\_id" element. A trolley is
organised as a set of orders, grouped into "bundles", with each bundle
corresponding to a single ticket supplier. The total number of orders
within the trolley is present in the "trolley\_order\_count" element,
and the total number of bundles as "trolley\_bundle\_count". If the
trolley has a departure date then this is in the element
"departure\_date\_yyyymmdd" in YYYYMMDD format, together with a human
readable form in "departure\_date\_desc". This is then followed by the
individual bundles, each within a "bundle" element.
For trolleys which have been purchased there will be a
"purchase\_result" element present after the individual "bundle"
elements. This always contains a single element "success" which has the
value "yes" or "no". As a purchase may only be partial there is also an
element "is\_partial" which is contains "yes" if the trolley contains
failed bundles, else "no". In the case where the purchase was not
successful and thus this element contains "no" then two boolean elements
will also be added into the "purchase\_result" elements. These are
"failed\_cv\_two" and "failed\_avs". They contain either "yes" or "no"
and are used to indicate the reason for a card failure when it is
definitely known. If these flags are "no" then it does not mean that the
AVS or CV2 check passed, merely that no information is available from
the backend. Finally a "purchase\_error" element is added for failed
purchases, which holds one of the following strings to indicate the
cause of the failure.
- **refusal** - one or all of the backend systems refused the booking
- **auth\_failure** - one or all of the payment card debits failed
authorisation
- **auth\_timeout** - one or all of the payment card debits timed out
whilst authorising
- **fraud\_blocked** - the booking details were refused as they matched
a system fraud trigger
- **already\_purchased** - an error caused by attempting to purchase a
second time. This should never happen.
- **already\_failed** - an error caused by attempting to purchase a
second time. This should never happen.
- **unspecified** - some unspecified system error has occurred
The bundle elements group together all the information common to a set
of orders from a single supplier. The supplier's descriptive name is
always present in "bundle\_source\_desc", with the corresponding code in
"bundle\_source\_code". The number of orders in the bundle is held in
"bundle\_order\_count", and the collective costs associated with a
bundle are present in "bundle\_total\_seatprice",
"bundle\_total\_surcharge" and "bundle\_total\_despatch", with a grand
total being calculated and placed in "bundle\_total\_cost". All costs
are to three decimal places and the currency of these costs is denoted
by the "currency" element. This element always contains five sub
elements; "currency\_code" which holds the three letter ISO4217 code for
the currency, "currency\_number" which holds the ISO4217 numeric code
for the currency, "currency\_places" which holds the number of decimal
places that the currency is subdivided into (normally two), plus
"currency\_pre\_symbol" and "currency\_post\_symbol". These latter two
hold the symbol necessary to display the currency. One of them is
normally blank and using the two values to bracket the currency will
give a correct display of the value. Following the "currency" element,
the individual orders in the bundle are then described, each in an
"order" element.
Purchased bundles, as with purchased trolleys, have a "purchase\_result"
element present after the individual orders. This always contains a
"success" element which has the value "yes" or "no". If the value is
"no" then the element will also contain an element "failure\_reason"
which is one of "auth\_failure", "auth\_timeout" or "unknown" to give
some indication, if known, as to why the purchase failed. Individual CV2
and AVS failures are not reported. For successful bundles there will
also be an element "is\_semi\_credit". This will normally be "no" except
in the case of certain on-credit sales to particular users. When this
flag is "yes" it indicates that the full agent cost needs to be paid to
the ticket supplier before the tickets will actually be despatched,
despite the fact that the sale was made on-credit. For on-credit sales,
whether semi-credit or not, there may also be an "agent\_cost" element.
Certain suppliers provide this when the cost of the tickets to the agent
is different to the face value. This element contains the cost in a
"total\_agent\_cost" element, plus another "currency" element as the
cost to the agent is not necessarily in the same currency as the face
value of the tickets.
The individual "order" elements hold all the details about a single
order within the bundle. Each order begins with an "item\_number"
element, holding the integer which uniquely identifies it within the
entire trolley. Item numbers start at zero and increment as more orders
are added. They are never re-used, even when an order is removed from a
trolley. For orders in a purchased trolley, the reference number for the
purchase which was issued by the backend system is to be found in
"backend\_purchase\_reference". This is normally the same across all
orders in a bundle as they are purchased in a single operation, but it
is held at the order level to support those systems which provide
individual references for each order. The venue at which the event is
taking place is described in "venue\_desc", followed by the event itself
in "event\_desc".
For orders where the date on which the tickets are to be used is known,
there now follows either a "performance" or a "usage" element, depending
on whether the date is a time specific performance (such as for theatre
events) or merely a day on which the tickets are to be used (such as for
theme parks). Both elements will contain the date, in the elements
"date\_yyyymmdd" and "date\_desc" for machine and human readable forms
respectively. The "performance" element may additionally contains the
time, held in "time\_hhmmss" and "time\_desc", for performances where a
time is relevent.
The text describing how the tickets are to be despatched is held in the
"despatch\_desc" element. For orders which have not been purchased then
this is the only information regarding the despatch method available.
After purchase, however, a second element "despatch\_final\_type"
containing either "post" or "collect" depending on whether the tickets
are to be sent to the customer, or if they have to collect them at the
venue. If any special conditions are associated with the actual despatch
method then these will be present in the element
"despatch\_final\_comment" and this text should be displayed to the
customer.
The type of ticket for the event is described in the
"ticket\_type\_desc" element. This is then followed by one or more
"discount" elements, each holding a set of tickets at a single price. If
a discount element is not the default price then a description of the
discount is present in the "discount\_desc" element. The price of each
tickets is in "seatprice", and the per ticket surcharge in "surcharge".
The total number of tickets in the discount is present in
"no\_of\_tickets". If individual seat IDs have been allocated then a
"seats" element will be present, containing one string for each ticket
in a set of "id" elements. For each of these there is also a
corresponding "id\_details" element which contains the ID broken down by
row and column, toegther with an separator between them. Seats are
allocated by some systems at reserve time, and others at purchase time.
For certain systems there is no guarantee that actual IDs will ever be
allocated at all. Finally the total price of all seats in the order is
held in "total\_seatprice" with the total surcharge in
"total\_surcharge". The total number of tickets in the order is in the
element "total\_no\_of\_tickets". If the order has been purchased the
the commission due on the order is to be found in the following
"user\_commission" element. This contains the currency of the payment in
"currency" (as this may be different to the transaction currency), plus
two values in "amount\_excluding\_vat" and "amount\_including\_vat"
which are the total value of the commission both including and excluding
VAT. If the user does not charge VAT then these wil be equal.
Example output
~~~~~~~~~~~~~~
.. code-block:: xml
4A2B-7AC9-F630-2749
1
1
Keith Prowse Ticketing
fcg3
1
27.500
4.150
1.500
33.150
gbp
826
£
1
AF291
The Dominion Theatre
We Will Rock U
20031230
Tue, 30th December 2003
143000
2.30 PM
Post (uk only)
post
Please bring your credit card with you
when you collect your tickets.
Stalls
First Call Standard Sale
27.500
4.150
1
WW40
WW
40
27.500
4.150
1
gbp
1.26
1.51
yes
no
yes
no
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
- **701** - no "trolley\_token" has been supplied
- **702** - the supplied "trolley\_token" is corrupt