20. 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 (The new purchase_reservation_part_one method and The new purchase_reservation_part_two method)

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.

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

20.1.1. Example input

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

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

20.2.1. Example output

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

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