Developer Portal

Welcome to the Assembly Payments developer portal. Here you’ll find comprehensive guides and documentation to help you start working with Assembly as quickly as possible, as well as support if you get stuck. Let's get started!

Platforms & Marketplaces Point of Sale

Integrating Drop-in UI for Capturing a Credit Card

Overview

Capturing credit card details through the Assembly platform is a straightforward task, especially when using the drop-in UI. This solution allows you to capture card details securely while being PCI compliant.

End User Experience

Here are some use cases for the drop-in UI card capture:

  • As a user, I would like to provide my credit card to be charged monthly.
  • As a user, I would like to provide my credit card to be charged for a single transaction.
  • As a user, I would like to enter an updated credit 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 credit card details through the drop-in UI will mean data is securely sent to Assembly with minimal PCI compliance impact. When used properly, your servers will not be exposed to credit card numbers using this method of card capture. Using this solution should assist obtaining a PCI SAQ A compliance level.

Supported Cards

The drop-in UI currently support 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)

Customisations

At this stage the Drop-in UI 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 token is used to authorise the passing of credit card details through the client-side libraries. The generating of the card token occurs 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 token:

  • Capturing credit 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 credit card is added or after 2 hours.
  • Capturing credit card details for an anonymous or new user (using the Charge API). This will involve not passing the user_id parameter when generating the card token. This token will expire as soon as a valid credit card is added or after 2 hours.

Use Generate Token to generate the card token.

Step 2: Add the Drop-in UI by Referencing Assembly.js

The block of code below is the way you include the drop-in UI. This can be embedded into a page or referenced in a dedicated pop-up, depending on your customer flow.

<html>
<head>
    <title>Drop-In UI 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 Assembly 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 drop-in UI 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 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 credit 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
  • Credit 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 Drop-in UI 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 drop-in UI 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 Assembly Payments branding on the form, if that is necessary, you can use PromisePay.js instead.
  • As all card data is entered directly into an Assembly 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 drop-in UI. 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 drop-in UI.

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

Updated 2 months ago


Integrating Drop-in UI for Capturing a Credit Card


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.