Templates

The template feature exists to make configuring ShieldConex Tokenization iFrames as simple as possible. This guide covers basic setup as well as detailing the capabilities and limitations of the iFrame.

Navigating to the Template Editor

Step 1: Login

Keep in mind that you will want to first test your integration with our certification environment. You can use the following links to log in to either environment.

Certification Environment: https://portal-cert.shieldconex.com/login

Production Environment: https://portal.shieldconex.com/login

Step 2: Navigate to Manage Templates

Once you log in, finding the templates is easy. Navigate to Manage in the top banner, and then Templates from the left navigation pane.

Step 3: Create or Select a Template

Once on the Manage Templates page, you’ll see a list of existing templates and above it, a button to Create Template. You can either use this button to create a new template from scratch or you can click the edit icon at the left of an existing template to edit it.

You can change the sort order (ascending / descending) by clicking a column heading. To mark a template as a favorite, click the star to the right of the template.

Filtering

You can filter existing templates by organization (depending on access level) and published status as well as search by name using the search box in the upper right hand part of the page. You can change the sort order (ascending / descending) by clicking a column heading.

To mark a template as a favorite, click the star to the right of the template.

Exporting

Next to the search box, you also have buttons that allow you to export a detailed list of templates in either PDF or CSV format.

Pre-Built Templates

Let’s take a closer look at the Create Template button. The main function of the button is to create a template with no existing setup, but if you look at the right-hand side of the button you’ll see a dropdown that displays options to create partially configured templates. The intent is to simplify integration with PayConex. Which template you use will depend on your settings and PayConex. If you aren’t sure which to use, please contact your integration specialist or send us an email at [email protected].

PayConex Token Payments Template
This template includes Card Information (number, cvv, & expert), ACH Payment Information, Name and Address fields.

PayConex Tokenization Template
This template includes Card Information (number, cvv, & expert) & ACH Payment Information.

Template Setup

Our secure iFrames offer a lot of flexibility. Consequently, it may seem like there’s a lot of setup involved, but don’t worry — the template editor is designed to make it easy. We’ll walk you through each step and explain your options as we go.

General Template Settings

Before you begin building out your iFrame you should configure the core template settings. Those are the settings shown within the “Template” section of the editor. Settings may vary based on your user role, but you will find all of the options below.

3D Secure Payment Options

3D Secure (3DS) is an e-commerce security standard that spans three domains - the interoperability domain (processor), the issuing bank, and the acquiring bank. These three entities work together to verify the cardholder’s identity using web authentication, as well as share robust data relevant to the transaction. 3D Secure may only be available to certain users.

There are several fields that need to be configured for 3DS to be enabled. This is where you can select your Authentication and Challenge Options, configure Shipping & Delivery, as well as specify transactions as Reorder or New Order. Please see below for a detailed guide to setting up each field.

Fields

This section helps you set up the fields that will show up in your iFrame. When you create a new template, there won’t be anything in this section but the Click to add new field button.

Field Types

There are 9 field types that you can add to your template. In this section, we’ll go over the basics of each field type, but if you’re looking for more details on the field setup process, please check out the Field Setup section further down in the guide.

iFrame Options

Domain Whitelist

Optional. As an added security measure, you can enable domain whitelisting in your ShieldConex Templates. When enabled, the form will only load when embedded in the given domain. This prevents any bad actors from hosting your iFrame elsewhere on the web.

If you decide to use domain whitelisting, make sure to include all sites where your iFrame is hosted. Please refer to the user guide for more information on how to set up domains and subdomains.

Custom StyleSheet (CSS)

Optional. There are 2 methods to set style your iFrame - Custom Style File and Custom Styles.

Custom Style File

You can provide the path for a CSS file that’s hosted online. Your file could be hosted in your own domain, or it could be hosted on a platform like Github. As long as the file is public, it can be referenced by the iFrame.

Example. If your file is hosted on Github and has been published, copy the public link and paste it in this field. The URL should look something like this:

https://raw.githubusercontent.com/your-project/assets/main/yourcssfile.css

Custom Styles

This is where you can enter any additional styles to override the default appearance of your iFrame. You use the same syntax here as you would in a Custom StyleSheet.

Example.

div {
    font-family: Arial;
    font-size: 14px;
    }
    div.field-group-expiration_date {
    width: 49%;
    float: left;
    }
    div.field-group-cvv {
    width: 49%;
    float: right;
    }
    footer { display: none;}
    [for="cvv"]{ display: none;}
    [for="card_expiration"]{ display: none;}

Publishing, Cloning, Previewing and Saving

These functions can all be found at the bottom of the editor.

Publish

The most important thing to note about publishing is that you cannot modify the template after saving it in the published state. This change is also permanent. To publish, select the Publish checkbox at the bottom of the page.

The template will only be set to ‘published’ once you click the save button.

Clone

This button creates a copy of the current template. After you click ‘Clone’ a dialog will pop up prompting you to name the copy. The copy will be identical in every way except for the following:

1. The TemplateRef will be different
2. The name will change based on what you specified in the dialog
3. The template will be unpublished

Since you can’t modify published templates, this feature is useful for safely updating an existing implementation or speeding up the creation of new templates based on the ones you already have.

Preview

When you click preview, it opens a pop-up dialog where your iFrame is automatically hosted. The preview function is useful for reviewing the appearance of the iFrame as you work on it. Note that in order to view your most recent changes, you must click Apply. Also keep in mind that this tool helps you test the aesthetics and composition of the iFrame, but is not meant to test iFrame functionality.

Sample & Beginning Your Implementation

The sample function is a little different than the Preview. Whereas preview is meant to help you take a quick look at the iFrame, sample is an actual mock integration with a submit button included. Here, you can test tokenizations using the iFrame as well as copy the iFrame element from the Page Source.

Data Setup Reference

This reference section is meant to help you understand the different configuration settings for creating or editing iFrame input fields. Configuration options may vary by field type.

Field Type

Selecting a field type, is the first step when adding a new field. There are 9 types in total:

1. Card Information
2. Bank Account Number
3. Routing Number
4. Date
5. Address
6. Phone Number
7. Email Address
8. Tax ID
9. Custom

The first 8 cover common use cases and have some built in validations based on length and allowed characters. The custom field type comes without pre-built validation and is meant to accomodate any use cases that the first 8 field types do not.

Display Name

The Display Name is the name that appears above the input in the iFrame. For a Field Group, this Display Name appears at the top of the group container.

Data Protection Method

There are 2 ways you can protect data — Format Preserving Encryption (FPE) & Format Preserving Tokenization (FPT). Encryption is an algorithmic transformation of data and does not support idempotency. Tokenization is a process that replaces data with a non-sensitive substitute.Both allow you to implement data security without changes

System Name

The variable name that represents the field in JSON requests and responses with the ShieldConex API. The System Name also impacts the tags you use to reference a specific field in CSS. Example. If your system name is first_name1, then you would refer to the field's containing div using field-group-first_name`.

Placeholder Text

The text that appears within an input box before the user begins to enter a value into the field. The default text color is gray. The style of of the placeholder text can be controlled using the following CSS tags:

• ::placeholder for Chrome, Firefox, Opera, Safari 10.1+
• :-ms-input-placeholder for Internet Explorer 10-11
• ::-ms-input-placeholder for Microsoft Edge

Non-Idempotent Tokens

Idempotency means that the same result will be returned given the same input. When this option is selected a unique token will be returned even if the same data is tokenized.

Group Id

The Group ID impacts idempotent tokens. Tokenizing the same value with the same Group ID will produce identical tokens, however changing the Group ID will produce a different, but still idempotent token.

Label

Unique to field groups. If you would like for individual fields within groups like Card Information and Address to additionally have a display name, you can configure one using this input.

Width

The width of the field within the iFrame. Options are 25%, 50%, 75%, and 100%. Sequential fields that can fit on the same row will be adjacent by default. For example, if I have 2 fields set to 50% and they are adjacent in the field order, they will occupy the same row.

Min Length

The minimum input length the user must reach before the value is considered to be of valid length. Must be less than or equal to maximum length.

Max Length

The maximum input length. If the user exceeds this number of characters, the input will not be accepted as valid. Must be greater than or equal to max length.

Input Type

The options for this setting are Input, Dropdown or Password. Input is a standard alphanumeric field that can be completed by typing characters. Dropdown fields offer the user one of a limited set of possible values from a dropdown input. If you choose Dropdown, you will be prompted to enter possible values. Password is similar to Input, however characters in this fields will be hidden.

Pattern

The Pattern. input accepts regular expressions, or regex for short. A regular expression is a string of characters that define a format or structure of ASCII characters. Using this, you can define any set of rules for a valid input for the given field.

Pattern Message

The message shown to the user if the pattern is not matched. This setting is useful if you would like to present the user with a custom error message when the form is submitted with a value that does not match the regular expression.

3DS Field Type

3DS Field Type determines how this information is packaged in the 3DS authentication request. The value you pick should match the input you expect from a user.