The *purchase\_reservation* method
==================================

.. note:: 

    This API call should only be used by clients who are set up to take payment from customers 
    themselves, and who will purchase the tickets on credit from Ingresso (a credit agreement 
    must be in place between the two parties).
    Clients who wish to rely on TicketSwitch for processing customer's payments should not use
    this call - they should instead use the two part payment process (:ref:`purchase_reservation_part_one` and :ref:`purchase_reservation_part_two`)


Purchase reservation completes the purchasing process by taking a
reserved transaction and confirming it in the backend systems. Customer
data is supplied at this point, along with any payment data which may be
required. A successful result from this means that the payment has been
taken, that the customer data was acceptable and that at least some of
the tickets have been purchased. Note that it is possible for a purchase
to partially succeed, with some individual transactions with specific
suppliers failing. The individual results for each order in the trolley
are then output, along with the despatch options available for each and
any allocated seat IDs. If the backend system has produced a reference
number for each order then these are also included. The purchased
trolley is produced as a token in the output, and it may also be fully
described, if requested, as usual.

A purchase request may fail for a number of reasons. The customer data
supplied must be complete, and the request will be rejected if it is
not. The credit card data must also be plausible (passes appropriate
checksums and is of an accepted type), and will only be accepted if it
is submitted over an encrypted connection. If the purchase fails for any
of these three reasons then the purchase may be re-attempted with
different data. If a purchase fails due to the credit card authorisation
failing, or due to the reservation having timed out, then the purchase
must be restarted from the "make\_reservation" stage. The output data is
structured such that permanent failures are not reported as errors, but
are reported as an actual result from a successful operation.

For purchases where a card payment is being made, a separate debit will
be made on the card for each supplier within the trolley. This should be
made clear to the customer, as they may be expecting a single debit. It
is perfectly possible for a transaction to take place in different
currencies for the different suppliers.

For purchases where a despatch method with a type of "selfprint" was
selected, and where TicketSwitch provides an HTML representataion of the
voucher, a URL will be returned from where this HTML may be downloaded.
The client software must fetch the HTML and present it to the customer
to print.

Required inputs
---------------

A purchase always requires the "crypto\_block" generated by
"make\_reservation" and also a "customer\_details" element containing
the data for the particular customer. If a payment card is required then
an element "card\_data" is required containing the payment card details.

If one of the "despatch\_token"s originally 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 when no selfprint method was chosen.

The "customer\_data" element contains the name and contact details for
the customer. The customers name can include a title such as "Mr" or
"Dr" as well as a suffix in order to handle such things as professional
status or honours. The complete customer name is thus held in five
elements called "title", "first\_name", "initials", "last\_name" and
"suffix". Of these only the first and last names are required to be
present and not whitespace. Address data consists of four lines,
nominally corresponding to the first two lines of the address and a town
and county, plus a postcode and an ISO 3166 country code. These should
be supplied in elements named "address\_line\_one",
"address\_line\_two", "town", "county", "postcode" and "country\_code".
Of these at least one of the first two lines plus the town must be
present and not whitespace. The country code is compulsory due to the
need to verify against the chosen despatch method. If the customer has
an email address then this can be supplied in the "email\_address"
element, and usually this is compulsory as indicated by the response
from "make\_reservation". If supplied, the address must correspond to
RFC822 and the syntax will be checked before a purchase is attempted.
Finally two telephone numbers must be supplied in the "work\_phone" and
"home\_phone" elements. To avoid a proliferation of failure codes there
is only one code for incomplete customer data, and it is the
responsibility of the user to check that the data passes these rules
before attempting the purchase.

The "customer\_data" element may also contain an "agent\_reference"
element, which will, if present, be stored against the transaction and
passed through to all backend systems. For certain users this is
compulsory, and if absent or blank will cause the customer data to be
marked as incomplete.

The XML core also allows the collection of simple data protection
information relating to the booking which specified who may use the
customers data. There are two distinct classes of data user, the first
being the user making the booking, and the second being the supplier of
all the tickets. If the element "user\_can\_use\_data" is present in the
input then the booking will be flagged to indicate that the user may
have the customers contact details. If the element
"supplier\_can\_use\_data" is present then each backend system will be
told that they may contact the customer. There is a third flag
"world\_can\_use\_data" which is used to indicate that the data may be
passed on to third parties for them to contact the customer. If this
flag is true then it implies that both of the other flags are also true.

If a card payment is being made then the "card\_data" element should be
provided to hold all the necessary information to perform a debit. This
consists of "card\_number", "expiry\_date" and "cv\_two" to hold the
three mandatory fields for a card. The format of the expiry date is MMYY
and for cards with no CV2 value then the "cv\_two" element should be
present but empty. An "issue\_number" element should also be present for
those cards which have one, but must not be present for cards which do
not. A "start\_date" element may also be provided for those cars which
have it. Certain types of card require this, and an error will be
generated if it is not supplied when one of these cards is used. For
transactions which allow an alternate card billing address then this may
be specified using the elements "address\_line\_one",
"address\_line\_two", "town", "county", "postcode" and "country\_code"
within the "card\_data" element. As with the customer data the billing
address requires that at least one of the first two lines is not
whitespace, along with at least a town or a county.

Sales made on credit are normally as a result of the user having a
credit agreement with Ingresso and will be invoiced for the amount.
Certain users, however, may not have credit facilities, but are still
allowed to make credit sales, as long as full payment is made to
Ingresso before the tickets are despatched. The booking process will
indicate if payment is required before despatch for a successful sale if
the user has one of these credit arrangements.

It should be noted that a backend system is at liberty to refuse a
booking based on its own internal criteria, which cannot be determined
by the core. This may be due to an internal fraud check algorithm being
used, or possibly due to unknown restrictions on customer data which may
have been violated. An example of this would be a system that does not
allow single character customer names, or names containing only vowels.

Example input
~~~~~~~~~~~~~

.. code-block:: xml

    <purchase_reservation>
        <user_id>demo</user_id>
            <crypto_block>s2--AgBUIdqCoM8BTmPgRUz8Zep1a9SB4hvttQdoT5qxan96T
    ogehZ-l_SI4rqn2uJJQHH-tH-v20N4yZEA3jWCBzK-3dqQsjfa_MYufnw-bCaZT
    b-NaqraAOBBwCymw2pojKN-8BRagvzW_cf3Gd9s-XiCz8I74B6A1XSMNmkqN6Ml
    CgAZFw8JHYra2Qp9PXw0h95Y__8_pPVRsJTNLlv4HoBcj-sf4d7C1A-7auwfB52
    gC9jfi16cXSkDhfI5dgZmRHVs6H8Y95N9QQYuXfXuD9eDsEqEqZKNBn5-RTfwfu
    yzWQGOPfI1xjsXhEaRejKQcKPVLrAB0RbaIEr437itxWg2LhSzbSd8LfcWrJ9Uw
    -Q_EfsKtVcFhF453ewreN1aeqvRkCGJ8x8DWlwzeg7sCCeRAB1NctLs6Z
            </crypto_block>

        <customer_data>
            <title>Mr</title>
    <first_name>Peter</first_name>
    <initials>C</initials>
    <last_name>French</last_name>
    <suffix>MIEE, MEng</suffix>
    <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>gb</country_code>
    <work_phone>020 3137 7407</work_phone>
    <home_phone>020 3137 7407</home_phone>
    <email_address>petefrench@ingresso.co.uk</email_address>
    <supplier_can_use_data/>
    </customer_data>

    <card_data>
    <card_number>4929123456788</card_number>
    <expiry_date>1204</expiry_date>
    <cv_two>123</cv_two>
    </card_data>
    </purchase_reservation>

Output data
-----------

Completing a successful purchase of a trolley is the final stage in the
process and thus no "crypto\_block" is produced as there are no
subsequent stages to be undertaken. A purchase results in a large amount
of data being associated with each order, such as seat identifiers, any
special options on send methods, and costs that will be incurred by the
agent for on-credit bookings. All of this data is held in the trolley,
and thus the output from a successful purchase is a complete description
of the trolley in the output. This is in the form documented for the
"trolley\_describe" method, including the "purchase\_result" element. So
that this information may be reproduced if necessary, the completed
trolley is also output in a "trolley\_token", along with the associated
"trolley\_order\_count" for ease of code-reuse.

Another element which may be present is "fraud\_warning" which indicates
that the purchase matched one or more of the fraud triggers. This is
only in the case where the trigger allows the purchase to proceed. If
the trigger causes the purchase to be blocked then an error will be
produced as described below.

For a purchase which fails for a normal operational reason, there will
be elements called "purchase\_fail\_code" and "purchase\_fail\_desc"
present. These indicate a permanent failure of the purchasing process,
and their possible values and meanings are documented below.

Purchases that result in TicketSwitch generating HTML representing a
selfprint voucher will return a "self\_print\_html\_page" element for
each selfprint order. This will contain a "page\_url" element containing
a relative URL and an "item\_no" corresponding to the "item\_number" of
the order. The latter allows the orders and vouchers to be matched up in
case there are several. The "page\_url" element can be turned into a
fully-qualified URL by concatenating "http://" and the hostname from the
URL currently being used for communication with the core with the
contents of "page\_url". The client must download the HTML and present
it to the customer for printing.

Example output
~~~~~~~~~~~~~~

.. code-block:: xml

    <purchase_reservation_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>
    </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>
    </purchase_result>
    </trolley>

    <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_order_count>1</trolley_order_count>
    </purchase_reservation_result>

Potential failure codes
-----------------------

The following failure codes are to be treated as any other codes in the
system would be, and appear inside "fail\_code" and "fail\_desc"
elements as usual. Apart from code 1101 the reservation will still exist
after one of these errors has been generated, and may be re-attempted
with different data.

- **1** - the supplied crypto block was not generated by
   "make\_reservation"

- **2** - the requested "mime\_text\_type" was not a supported value

- **1101** - the reservation has expired

- **1102** - no "customer\_data" element has been supplied

- **1103** - no "card\_data" element has been supplied when required

- **1104** - a "card\_data" element has been supplied when not required

- **1105** - no "country\_code" element was present in the customer
   data

- **1106** - the chosen despatch method does not allow the given
   country code in the customer data

- **1107** - the supplied email address fails RFC822 syntax checking

- **1108** - the customer details supplied are incomplete

- **1109** - no "card\_number" element was present in the payment card
   data

- **1110** - the payment card type is not known from the supplied card
   number

- **1111** - the payment card type is not one of those accepted for
   this transaction

- **1112** - the card number given is not valid for cards of that type

- **1113** - no "expiry\_date" element was present in the payment card
   data

- **1114** - the expiry date given is not valid

- **1115** - no "cv\_two" element was present in the payment card data

- **1116** - the CV2 value given is not valid

- **1117** - no "issue\_number" element has been supplied when required

- **1118** - an "issue\_number" element has been supplied when not
   required

- **1119** - the issue number given is not valid

- **1120** - alternate card billing address supplied when not supported

- **1121** - the alternate card billing address details supplied are
   incomplete

- **1122** - no "start\_date" element has been supplied when required

- **1123** - the start date given is not valid

- **1124** - the users prefill data is not editable, and does not match
   the customer data supplied

- **1125** - a "card\_data" element has been supplied over a
   non-encrypted connection

The following codes are not errors in the normal way, but instead
indicate a failure to purchase the tickets due to some other cause.
Failures on this list are permanent, and the reservations are no longer
valid once one of these failures has occurred. They are differentiated
from normal errors by the fact that the element names are
"purchase\_fail\_code" and "purchase\_fail\_desc".

- **1** - the combination of customer and payment card details have
   matched a system fraud trigger and the purchase has not be allowed

- **2** - the payment card provided could not be authorised for the
   value of the transaction

- **3** - the attempt to authorise the payment card timed out with no
   response from the bank

- **4** - the reservation purchase has already been made successfully

- **5** - the reservation purchase has already been tried and failed

- **6** - the reservation purchase has been refused by the backend

- **7** - an unspecified systems error has occurred during purchase