Using Components

This tutorial will show you how to:

• create Custom Form
• collect card information and request card token
• (optionally) process 3D Secure authentication
• receive card token and send it to your server

Step 1: Custom Form

First, we will need to create a payment form:

<form action="" method="post" id="payment-form">
	<span id="payment-error"></span>
	
	<div class="form-group">
		<label>Card Number</label>
		<div data-shift4="number"></div>
	</div>

	<div class="form-group">
		<label>Expiration</label>
		<div data-shift4="expiry"></div>
	</div>

	<div class="form-group">
		<label>CVC</label>
		<div data-shift4="cvc"></div>
	</div>

	<button type="submit">Pay</button>
</form>

The important thing to note here is that all card-related fields are not created as <input> tags but as empty placeholders that will be later converted to secure components using our Shift4.jslibrary. This approach will ensure that no sensitive card data can be stolen, even if malicious code is injected into your website.

In this example, we don't have any extra fields in our form - however, there is no problem with adding them if necessary. If you need an e-mail address field or some field to select a product type - you may add them according to your needs.

Step 2: Collecting card data and requesting card token

To collect card data, we need to include and configure the Shift4.js library:

<script type="text/javascript" src="https://js.dev.shift4.com/shift4.js"></script>

<script type="text/javascript">
	// Initialize Shift4 object with your public key
	var shift4 = Shift4("pu_test_WVMFC9GFuvm54b0uorifKkCh");

	// Create components to securely collect sensitive payment data
	var components = shift4.createComponentGroup().automount("#payment-form");
</script>

The automount() method used here will look for tags with the data-shift4 attribute and automatically create components with type-matching values from that attribute.

Next, we need to override the default behavior of form submit:

<script type="text/javascript">
	// Intercept payment form submit
	var $form = $('#payment-form');
	$form.submit(paymentFormSubmit);

	function paymentFormSubmit(e) {
		// Prevent the form from submitting default action
		e.preventDefault();

		// Disable form submit button to prevent repeatable submits
		$form.find('button').prop('disabled', true);

		// Send card data to Shift4
		shift4.createToken(components)
			.then(tokenCreatedCallback)
			.catch(errorCallback);
	}
</script>

In this code, we call components.createToken() to create a card token from data collected by secure components. The return value of that method is the standard Promise object. The result can be processed by providing a callback to the then() method. Error handling can be done by providing a callback to the catch() method.

Suppose you collected any additional data from a user that you want to include in the created token (like cardholder name or billing address). In that case, you can pass that data as the first argument of the createToken() method.

Note that we are using jQuery to simplify things in this example, but this is not required. Shift4.js has no external dependencies, and you can easily use it without jQuery.

Simple error handling can be done by displaying an error message and re-enabling the form submit button:

function errorCallback(error) {
	// Display error message
	$('#payment-error').text(error.message);

	// Re-enable form submit button
	$form.find('button').prop('disabled', false);
}

Step 3: Receiving card token and sending it to your server

Now that we have code that will create a card token - the last thing that we need to do is send that token to your server. In our example, we do this in the tokenCreatedCallback function:

function tokenCreatedCallback(token) {
	// Append token to the form so that it will be send to server
	$form.append($('<input type="hidden" name="token" />').val(token.id));

	// Submit the form with its default action
	$form.unbind();
	$form.submit();
}

If the request was successful, we received a card token. We append it to the form and submit it with its default action. This will result in form data (together with the card token but without sensitive card details) to be sent as an HTTP POST request to the URL defined in the form's action attribute.

Now that the card token has been sent to your server, you can use it to charge the user's card for the money. Read more about this in charging cards tutorial.

3D Secure

To enable 3D Secure support in your Components, you need to make an additional call to shift4.verifyThreeDSecure() method after successfully receiving a card token. Calling that method will open the frame with the 3D Secure process, and the result of that process will be appended to the card token.

To do this, we need to modify the tokenCreatedCallback function:

function tokenCreatedCallback(token) {
	var request = {
		amount: 2499,
		currency: 'USD',
		card: token.id
	};

	// Open frame with 3-D Secure process
	shift4.verifyThreeDSecure(request)
		.then(threeDSecureCompletedCallback)
		.catch(errorCallback);
}

And then code responsible for sending a token to your server have to be moved to the threeDSecureCompletedCallback function:

function threeDSecureCompletedCallback(token) {
	// Append token to the form so that it will be send to server
	$form.append($('<input type="hidden" name="token" />').val(token.id));

	// Submit the form with its default action
	$form.unbind();
	$form.submit();
}

Now that the card token has been sent to your server, you can use it to charge the user's card for the money. Read more about this in the charging cards tutorial or take a look at a live example.