JS reference

Introduction

Shift4.js is a browser-side JavaScript library that can be used to securely collect sensitive payment information (like credit card numbers).

This documentation describes every object and method made available by the library.

Including Shift4.js

Shift4.js should be included on every page of your site where payment information will be collected. It should never be bundled or hosted on your website, but should always be loaded directly from https://js.dev.shift4.com. 


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

Initializing Shift4.js

To get started with Shift4.js, first, call the Shift4() method to create and configure a Shift4 object.

Shift4(publicKey)

Create a new Shift4 object and configure it.

Parameters

publicKey string
Public API key used to identify your account. Your account is identified by a public API key. Once logged in, you can find your API keys in your account settings.

Result

Shift4 object

EXAMPLE


var shift4 = Shift4("pu_test_WVMFC9GFuvm54b0uorifKkCh");

Shift4 object

Shift4 object is the main entry point to all Shift4.js functionalities.

createComponent(type, options = {})

Create a new component of the specified type.

Parameters

type string
Component type to be created. It could be a card - a single component to collect all card details
options object
Plain object with additional options.

Result

Component object

EXAMPLE


var card = shift4.createComponent("card");

createComponentGroup()

Create a new grouping object that will be used to create multiple related components, such as number, expiry and cvc components that will be used together to collect details for a single card.

Result

ComponentGroup object

EXAMPLE


var components = shift4.createComponentGroup();

createToken(component, data = {})

Tokenize card data from a given component or component group by sending it to the "create token" API method.

Parameters

component Component | ComponentGroup
A single component or a group of components from which sensitive card data will be tokenized.
data object
Additional data that will be included in the tokens API request. The "create token" API method lists all permitted keys. NOTE: For security reasons, this parameter cannot be used to send the following fields in the request: number, expMonth, expYear and cvc. Values of these fields must be collected using components.

Result

Promise object

EXAMPLE


var card = shift4.createComponent("card");

function onFormSubmit() {
	shift4.createToken(card)
			.then(tokenCreatedCallback)
			.catch(errorCallback);
}

verifyThreeDSecure(request)

Starts a 3D Secure process.

Depending on the card and the card's issuer, this may result in the 3D Secure challenge being displayed in an iframe or popup window.

Parameters

request object
The request object will be sent to the API. The following keys are allowed:
  • card (string) - a token identifier (generated by the createToken() method)or a card identifier (created using cards API).
  • amount (integer) - the amount in minor units of the given currency (for example, 10€ is represented as "1000" and 10¥ is represented as "10"), which must match the value that will be used to create a Charge using API
  • currency (string) - the currency, represented as a three-letter ISO currency code, must match the value later used to create a Charge using API
  • merchantAccountId (string, optional) - the merchant account identifier that will be used to complete the 3D Secure process

Result

Promise object

EXAMPLE


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

	shift4.verifyThreeDSecure(request)
		.then(threeDSecureCompletedCallback)
		.catch(errorCallback);
}

Component object

Component object is used to securely collect sensitive information (like card number or cvc).

mount(selector)

Mounts component to placeholder tag located by given selector.

Parameters

selector string | Element
Either CSS selector or DOM element that will be used as a mounting point.

Result

Component object on which this method was called

EXAMPLE


var components = shift4.createComponentGroup();
var number = components.createComponent("number").mount("#number");

clear()

Removes any current value from a component.

Result

Component object on which this method was called.

EXAMPLE


var card = shift4.createComponent("card");

card.clear();

ComponentGroup object

When multiple components are required to collect card details for a single card, the ComponentGroup object is used to group them.

automount(selector)

Automatically search all tags nested under the tag located by the given selector and create components on all tags with the data-shift4 attribute. The value of that attribute is used to determine the type of the component.

Parameters

selector string | Element
Either CSS selector or DOM element that will be used as a starting point when searching for tags with data-shift4 attribute.

Result

ComponentGroup object on which this method was called.

EXAMPLE


var components = shift4.createComponentGroup().automount("#payment-form");

createComponent(type, options = {})

Create a new component of a given type and assigns it to this component group.

Parameters

type string
Component type to create. It could be one of the following types:
  • number - used to collect card numbers
  • expiry - used to collect card expiration dates (both month and year)
  • cvc - used to collect card security code
  • expiryMonth - used to collect card expiration month
  • expiryYear - component for collecting the card’s expiration year
options object
Plain object with additional options.

Result

Component object

EXAMPLE


var components = shift4.createComponentGroup();

var number = components.createComponent("number");