15. 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.

15.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. A “trolley_token” holding the trolley to be described must also be present.

15.1.1. Example input

<trolley_describe>
<user_id>demo</user_id>
<crypto_block>U_--LfP7rp3MoitCr2ofVaNShLkdOlMurxfADnkYLSOFxUoQo
YUZz_Kq23SaaVvPmF43Ndbq2o1t5Nq60tvNucAoeODYcVYViU_lXNIqmcKQa9ID
lXCTGZEvwqddnGIUevnZY</crypto_block>
<trolley_token>c3--ESt4iSq-0h6ewW5aurWrMlaHazPjAoh6aidaqiycuEQx
b5d3JTr2KnNS_eNj_LC5-RHyLa4O-cKULcjllwjpSzx49vJ0mniPPBFgDeZRkfK
gz1x-gLCqsvdp1DTkgKyWu2_GM6_TV7DX6G1fLRCM7oX6D8j802Rz8lNB2VI7hy
dIva0ixEfHu48UMiYdOREp9XDIwdoYi4R0tFO5ZQt4KUzKRp7Rn9i0UNPyIVtMM
2IRP6ob-Dy-054kpOGnFihWBXBkP4kmSM3LOwxCBxVxjq7y2VlRIGg0Q2wl-W8k
-Ui17qiKMn_ZflHByRyv5MBSkiXrJFOZLKRboPT73uq5oxz3NgRHiCeGULnF345
zp6Jz94huDRbV6w4nSv7CVBgJ_H7iZZJcf08Z5q570AoO9e9hZe44ZDGl5H1L61
QD3KDyCzUS3EH1l8JMEm0kQF1Xb4w2joeUbTP7IPhVPUS4zBNcfQGmoc-IZ
</trolley_token>
</trolley_describe>

15.2. 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.

15.2.1. Example output

<trolley_describe_result>
<trolley>
<transaction_id>4A2B-7AC9-F630-2749</transaction_id>
<trolley_order_count>1</trolley_order_count>
<trolley_bundle_count>1</trolley_bundle_count>

<bundle>
<bundle_source_desc>Keith Prowse Ticketing</bundle_source_desc>
<bundle_source_code>fcg3</bundle_source_code>
<bundle_order_count>1</bundle_order_count>
<bundle_total_seatprice>27.500</bundle_total_seatprice>
<bundle_total_surcharge>4.150</bundle_total_surcharge>
<bundle_total_despatch>1.500</bundle_total_despatch>
<bundle_total_cost>33.150</bundle_total_cost>

<currency>
<currency_code>gbp</currency_code>
<currency_number>826</currency_number>
<currency_pre_symbol>&#163;</currency_pre_symbol>
<currency_post_symbol/>
</currency>

<order>
<item_number>1</item_number>
<backend_purchase_reference>AF291</backend_purchase_reference>
<venue_desc>The Dominion Theatre</venue_desc>
<event_desc>We Will Rock U</event_desc>
<performance>
<date_yyyymmdd>20031230</date_yyyymmdd>
<date_desc>Tue, 30th December 2003</date_desc>
<time_hhmmss>143000</time_hhmmss>
<time_desc>2.30 PM</time_desc>
</performance>
<despatch_desc>Post (uk only)</despatch_desc>
<despatch_final_type>post</despatch_final_type>
<despatch_final_comment>Please bring your credit card with you
when you collect your tickets.</despatch_final_comment>
<ticket_type_desc>Stalls</ticket_type_desc>
<discount>
<discount_desc>First Call Standard Sale</discount_desc>
<seatprice>27.500</seatprice>
<surcharge>4.150</surcharge>
<no_of_tickets>1</no_of_tickets>
<seats>
<id>WW40</id>
<id_details>
<row_id>WW</row_id>
<separator/>
<col_id>40</col_id>
</id_details>
</seats>
</discount>
<total_seatprice>27.500</total_seatprice>
<total_surcharge>4.150</total_surcharge>
<total_no_of_tickets>1</total_no_of_tickets>
<user_commission>
<currency>gbp<currency>
<amount_excluding_vat>1.26</amount_excluding_vat>
<amount_including_vat>1.51</amount_including_vat>
</user_commission>
</order>
<purchase_result>
<success>yes</success>
<is_semi_credit>no</is_semi_credit>
</purchase_result>
</bundle>
<purchase_result>
<success>yes</success>
<is_partial>no</is_partial>
</purchase_result>
</trolley>
</trolley_describe_result>

15.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
• 701 - no “trolley_token” has been supplied
• 702 - the supplied “trolley_token” is corrupt