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

MethodDescription
.create Use this method to instantiate the drop-in form.
.clearFormA 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.
.destroyUsing 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

MethodDefinition
cardTokenAuthThe auth token required from Zai Payments. On the server side, call Token Auth with token_type=card and the appropriate user_id
targetElementIdThe id of the container on this page that the iframe will be inserted into.
Example: #container
EnvironmentThe 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
cardAccountCreationCallbackThe 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:

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