Integrating Hosted Form for Capturing a Card

Overview

Capturing card details through the Zai platform is a straightforward task, especially when using the Hosted Form. This solution allows you to capture card details securely while being PCI compliant.

📘
Naming change
Our Drop-In UI has been renamed to Hosted Form

End User Experience

Here are some use cases for the Hosted Form card capture:

As a user, I would like to provide my card to be charged monthly.
As a user, I would like to provide my card to be charged for a single transaction.
As a user, I would like to enter an updated card to attach to my account.

Each case has a different charge scenario, but the same card capture process is required in each case.

Features

PCI Compliance

Capturing card data through the Hosted Form will mean data is securely sent to Zai with minimal PCI compliance impact. When used properly, your servers will not be exposed to sensitive card information. Using this solution should assist you in obtaining a PCI SAQ-A compliance level.

Supported Cards

The Hosted Form currently supports VISA, Mastercard and American Express cards.

Supported Browsers

This is the list of supported browsers that we have tested against:

Edge: 17 and higher versions
Firefox: 60 and higher versions
Chrome: 67 and higher versions
Safari: 11.1 and higher versions
Internet Explorer: 11 and higher versions

Note: The solution should work on lower versions from a functionality standpoint however the user experience in terms of look and feel might have some minor issues (such as colours and placement of icons, labels and fields...etc)

Customisation

At this stage the Hosted Form solution is not customisable.
We are looking at providing this feature in the near future.

Implementation Details

Step 1: Generating a Card Auth Token

A card auth token is used to authorise the passing of card details through the client-side libraries. The generating of the card auth token occurs on the server-side, so that the generated token can be passed into the client-side for authentication. There are two use cases for generating a card auth token:

Capturing card details of an existing user. This will involve passing the user_id parameter when generating the card token. This token will expire as soon as a valid card is added or after 2 hours.
Capturing card details for an anonymous or new user. This will involve not passing the user_id parameter when generating the card token. This token will expire as soon as a valid card is added or after 2 hours.

To generate the card token, use: Generate Token.

Step 2: Add the Hosted Form by Referencing Assembly.js

Use the block of code below to include the Hosted Form. This can be embedded into a page or referenced in a dedicated pop-up, depending on your customer flow.

<html>
<head>
	<title>Hosted Form test page</title>
	<meta http-equiv="refresh" content="1800"/>
	<meta name="viewport" content="width=device-width, initial-scale=1" />
	<style type="text/css">	
		body {
			font-family: Arial, Helvetica, sans-serif;
			font-size: 13px;
		}
		#container {
			max-width: 400px;
			border: 0.5px solid #bdbdbd;
		}	
	</style>
</head>
<body>
	<div id="container"></div>
	<script src="https://hosted.assemblypay.com/assembly.js"></script>
	<script>    
		let dropinHandler = Dropin.create({        
			cardTokenAuth: '%s',
			environment: 'prelive',        
			targetElementId: '#container',
			cardAccountCreationCallback: function(cardAccountResult) { 
				alert(` + "`Card Account ID received: ${cardAccountResult.id}`" + `)
			}
		}, function (error, instance) {        
			if(error) { 
				alert(` + "`Error: ${error}`" + `);
			}    
		});
	</script>
</body>
</html>

Object Methods on DropIn

Method	Description
.create	Use this method to instantiate the drop-in form.
.clearForm	A successful submission of the card by the end-user will automatically clear the form. However, if needed, you can clear the form directly using this method.
.destroy	Using this method will ensure the object is destroyed to eliminate any concerns about the object persisting when it is no longer required. Recommended once a successful callback is received. The object CANNOT be used to capture a second card since the auth token is only valid once.

Required Parameters to .create

Method	Definition
cardTokenAuth	The auth token required from Zai Payments. On the server side, call Token Auth with `token_type=card` and the appropriate `user_id`
targetElementId	The id of the container on this page that the iframe will be inserted into. Example: `#container`
Environment	The environment that this should run again, `prelive` for testing in the sandbox and `production` when deploying to a production environment. Possible values: `prelive` \| `production` Example: `prelive`
cardAccountCreationCallback	The function called when the Hosted Form successfully captures a valid card. The token returned can be used when calling APIs like Make Payment as the `account_id` parameter. Example: function(token) { console.log(`Token received: ${token}`)}

The card auth token for authorisation is generated on the server side and referenced in the script as shown above.
NOTE: This cannot be hard coded, it must be dynamically generated each time.

The token does expire, so it is recommended that some mechanism is implemented to avoid having the end user try to enter a card with an expired auth token. The example HTML below can be used to specify a refreshed

<meta http-equiv="refresh" content="1800"/>

The form that appears to the user does not indicate how much will be charged or whether a charge will be made. That information must be provided by the containing page so the user knows how their card will be used.

Once the user completes the process successfully you can continue the user flow and send the card account id back to the server for further processing.
If an error is passed back, no card was captured. See Error Handling below for more details.

The Form

The form will only prompt the end user to enter:

Full name
Card number
Expiration date
CVV/CVC

The card type is detected as they type to assist in verifying the card.

Any other information that must be collected from the user must be done in a separate form that is not part of our Hosted Form solution and is to be implemented by your platform.

Recommended experiences

Embedded

This works well if the form is referenced inside an existing pop-up, so you don’t want another pop-up in your flow. The div can be hidden/shown based on user action as needed.

Pop-up

This is the recommended approach if the user is clicking a button from a page and that should make the card capture form appear, capture the card, and then close on completion. The Hosted Form should work on most mobile viewport sizes as well as laptops and desktops.

If a charge will be made, providing information to the user about the amount in the pop-up is recommended.

NOTE: In either case, any charges to the captured card must be made on the server side.

Store or Charge

If the card capture is successful, you will receive a callback to the provided javascript function, just as if you had created the card using the Create Card Account method.

This will provide a card account id which can be used to make a payment or stored for future use.
This account ID can also be fetched using the Show Card Account method in the API.

Key notes

A div is required but can be placed anywhere you want the card capture form to appear. It can have any ID, just provide it when calling DropIn.create
The form is responsive even though it is in an iFrame and should not result in scroll bars regardless of viewport - try it out!
You cannot remove the Zai branding on the form, if that is necessary, please contact us.
As all card data is entered directly into a Zai Hosted solution, we believe you are able to complete a SAQ-A scope. But as there may be other factors in your environment, we suggest you obtain QSA validation

Error Handling

All card number verification is done by the Hosted Form. So the page that references Assembly.js will not receive a callback for an error, only for successful card capture.

However, it is essential to check for the following error conditions when instantiating the Hosted Form.

The following errors should be caught and handled:

Error	Solution
cardTokenAuth is required	Ensure a valid cardTokenAuth has been generated and referenced when calling the DropIn.create method
targetElementId is required	Ensure that a targetElementId is provided when calling the DropIn.create method
targetElementId does not exist	Ensure that the referenced targetElementId is in the DOM at the time DropIn.create is called
cardAccountCreationCallback is required	Ensure there is a valid javascript function provided to receive the callback on success. It should expect a

Overview

📘Naming change

End User Experience

Features

PCI Compliance

Supported Cards

Supported Browsers

Customisation

Implementation Details

Step 1: Generating a Card Auth Token

Step 2: Add the Hosted Form by Referencing Assembly.js

Object Methods on DropIn

Required Parameters to .create

The Form

Recommended experiences

Embedded

Pop-up

Store or Charge

Key notes

Error Handling

📘
Naming change