Ticketing

Notice: This integration method has been deprecated. We encourage developers to look at our other integration methods.

This method is no longer considered "Out Of Scope" for the new PCI 3.2 standard therefoe if you choose to utilize this method your servers are considered "in-scope" and you are required to complate a PCI Attestation of Compliance.
See https://www.pcisecuritystandards.org/pdfs/best_practices_securing_ecommerce.pdf for more info.

The ticketing integration method is a way of submitting transactions from your web site to our servers. In a nutshell, the process works by using JavaScript code to send the card data directly to our API servers. We respond back with a token. This token is stored and submitted by your servers to our API servers to complete a credit card transaction. By using this method, your servers will never touch or pass credit card data.

Below is a diagram of the request flow. The only step that involves credit card data is step #2, which bypasses your API servers.

Workflow

The Merchant website contains its typical form to accept credit card information.
The merchant attaches the form handler using the ticket() method with the required parameters.
After the client submits the form, the submit event becomes intercepted. The client submitted data will then be sent to the API server to the /v2/cardtickets endpoint and be processed for validation. This step happens in the background via AJAX requests.
If the information provided is valid, a token will be generated by the API server. This token is added to the credit card form as a hidden field.
The JavaScript then removes all the information that has been sent to the server from the form and then resumes the submit.
This method then allows the credit card to be replaced by the token when submitting a transaction to be processed by the API server.
MWS responds to Customer browser with “Thank You” page.

Note: The returned ticket can be used as card information holder for Transaction Actions.

PHP Example

Requirements

jQuery 1.0+
SHA-256 server algorithm
PHP 5 (for this example)

Installation

You can download a zip file with all of the necessary files for the PHP example here. There are two main files that are needed to get started:

api.jquery.js - This JS file will be referenced in your main form file to include all the necessary JavaScript.
example.php - This is an example php file that shows how a form can be setup to capture necessary credit card data.

There is an optional third file included if you wish utilize a USB card reader to get full track data.

card_reader.js - This JS file can be used to implement a USB card reader to get full track data for card transactions.

PHP

We need to generate a hash in PHP. There are 4 parameters that are required to generate a signature hash:

Ticket Hash Key: This is the ticket hash key provided by the API that is used to generate the signature hash. This key is secret and should not be shared with anyone.
Location Id: Provided by the API as your location identifier
Order Id: The order number for your order. If you don't have one, you can use a random number generated by PHP.
Timestamp: The current time when the page has been generated. it has an expire period of 5 minutes

The hash is generated using the location id, timestamp, and order id, in that specific order. Here is sample code of how to generate the signature:

<?php
// Define the secret ticket_hash_key used for hashing the variables
$ticket_hash_key = 'my_ticket_hash_key';
 
// Define variables for generating the required hash
$location_id = 'my_location_id';
$timestamp = time();
$order_id = mt_rand();
 
// Generate the secure hash, making sure the variables
// are in the proper sequence.
$data = $location_id . $timestamp . $order_id;
$key = hash_hmac('sha256', $data, $ticket_hash_key);

JavaScript

After generating the hash, you can now initialize the binding on the form page with this Javascript:

$(document).ready(function() {
	// This will setup the javascript variables based on data provided by the server
	$("#myform").ticket({
		timestamp : "<?= $timestamp ?>",
		authorization : "<?= $ticket_hash_key ?>",
		location_id : "<?= $location_id ?>",
		order_id : "<?= $order_id ?>",
		url: 'apiv2.sandbox.domain.com'
	});
});

If a USB card reader is being used, then make sure the following JavaScript is placed on the form page.

/* 
Make sure that the card_reader.js file is included before this code runs. 
<script src="js/card_reader.js"></script>
*/
$(document).ready(function() {
	$(function () {
		var reader = new CardReader();
		reader.observe(document);
		reader.cardError(function () {
			alert("A read error occurred");
		});
		reader.cardRead(function (value) {
			parseTrackData('card_number', 'exp_date','account_holder_name');
		});
	});
});

HTML

In this implementation, all elements that you do not want to be received by your system shall have a class named “ticketed”. This will submit them to get the ticket, then the ticket id will be used in place of the credit card information. Also, each element needs to have a data-ticket attribute to determine the name of it in the post data to be sent in to the server The required elements that need to be submitted to create a ticket are:

card_number
exp_date

<form method="POST" id="myform">
	<div class="errorSummary"></div>
	<label for="account_holder_name">Customer name: </label>
	<input type="text" name="account_holder_name" />
	<br />
	<label for="card_number">Credit card number: </label>
	<input type="text" name="card_number" class="ticketed" data-ticket="card_number" />
	<br />
	<label for="exp_date">Exp Date: </label>
	<input type="text" name="exp_date" class="ticketed" data-ticket="exp_date" />
	<br />
	<label for="zip">Zip: </label>
	<input type="text" name="zip" class="ticketed" data-ticket="billing_zip" />
	<br />
	<input type="submit" value="submit" />
</form>