Custom Payscreens Templates

Feature Overview

The Payscreen Templates feature is an advanced way to customize the Smart Screens payment method’s billing/summery pages, to accommodate merchant’s more advanced layout/presentation needs.

As a merchant, you can easily create & upload custom layout templates to replace wording &/or add your own custom HTML code to those pages. This lets you customize the look/feel of those pages to better suite your particular custom checkout layout needs.

Features Include:

Augment Smart Screens Layout - Allows merchants to easily adjust wording within the Smart Screens billing/summery pages &/or insert your own HTML code into said pages.

Multiple Templates - Allows merchant to manage multiple template & to easily select a specific language’s template for given transaction.

Simple Interface - Easily import/delete templates from the admin area.

Consolidated Template Format - Only those fields/sections you wish to augment needs to be included in the template. This keeps the templates very small & simply formatted.

Fully Integrated - No special integration with your web site is required. Merchants upload their templates using our secure admin area & then add 2 hidden parameters to the data they are already supplying us.

Free To Merchants - This template feature is part of the core payment gateway service & does not incur additional fees for its usage. (Normal authorization fees still apply to your transactions.)

How It Works

Merchant uploads 1 or more payscreen templates into their payment gateway administration area.

Merchant adds 2 extra parameters to the data they are already sending to our Smart Screens payment method, from their order forms &/or shipping cart solution. This tells us the name of the custom payscreen template to use & which language group the template belongs to.

Then whenever a customer uses that order form or shipping cart solution to place an order, they will presented with the augmented wording &/or HTML code within the Smart Screens billing/summery page at time of checkout.

Feature Setup

To setup:

Step #1: Merchant would need to upload 1 or more payscreen templates into the “Template Options” feature, within the “Account Settings” section of their merchant admin area. (See below for how to create a template file & what special substitutions/tags can be used within your template.)

Step #2: Merchant would need to know the name they assigned the custom payscreen template(s) they uploaded to us & what language group it belongs to. This information will be displayed within the “Template Options” feature, within the “Account Settings” section of the merchant admin area; should you need to look it up.

Step #3: when using Smart Screens payment method, merchant would need to tell us when to use a specific custom transition page for a given payscreen template & what language group the template belongs to. This is done by including the following hidden field within the data you are sending to our Smart Screens payment method.

These are the fields you would need to include within the data you send:
Variable Required Max Size Value Notes
paytemplate (See Note 1) Mandatory n/a [enter name of the template] Sets name of the payscreen template you want used.i.e. This tells us to use payscreen template named ‘abc135’.
lang (See Note 2) Mandatory 2 “en” = English, “sp” = Spanish, “fr” = French Sets which language group the payscreen template belongs.i.e. This tells us to select the payscreen template from the english language group.

Notes:

  1. when the ‘paytemplate’ field is not provided, blank or when the template name does not exist, we will use our default payscreen template.

  2. when the ’lang’ field is not provided or is blank, we will not assume an language group

Template Layout

The layout of payscreen template files are very straight forward.

The template files are basic text files, which contain small chunks of HTML code (NOT A COMPLETE WEB PAGE) that define only the sections of the Smart Screens billing/summery pages you want to augment.

Naming Your Template File

You may name your payscreen template upload files anything you like, but they must follow these basic naming rules:

  • The upload file’s extension must be “.txt”.

  • The uploaded file’s name on your PC can contain letters [a-z and A-Z], numbers [0-9], hyphen [’-’] or underscore [’_’] characters. (No spaces or other punctuation are permitted within the file’s name)

  • You if you attempt to upload a template file not named in the above matter, your template file will be rejected at time of upload or we will receive a blank file.

How To Format Template File

Each special section tag has an opening & closing named tag. Its very similar to how you would have an opening & closing tag in HTML. Each of the opening & closing special section tags must be on their own line. (Please see further down in this document, for a complete list of all the special section tags that may be defined with your templates)

For example, if you were adjusting the TAIL section, it could look something like this

Simply insert your extra info between the special & tags to make your HTML code appear within that given section. You can include as much HTML code as you like between the special & tags for each section.

Please <a href="https://pay1.plugnpay.com/new_docs/payscreen_sample.txt">click here to see a basic PayScreen Template sample file. This should give you a better idea on how the file is structured.

The following special substitution is also available, which displays the value of a specific field name within your custom HTML code.

[pnp_fieldname] = inserts the value of a specific response ‘fieldname’.

For Example:

[pnp_card-amount] - would insert value of the “card-amount” field
[pnp_orderID] - would inserts value of the “orderID” field (i.e. 200905081201304500000)

This field value substitution is the same as usage within Email Management’s confirmation email templates.

For example:

Section Tags

These are the special section tags in the payscreen template files:
Variable Notes
DOCTYPE This HTML code would appear just before the normal tag at the very top of the billing/summery pages.  Its normally used to sent custom document type HTML code
LANGUAGE (See Note 1) This section is used to define substitution text for the wording/text we use in the billing/summery pages. Each line should be a single substitution.  Each line is in a 2 column tab delimited format. As such you would enter the language fieldname, a hard tab, then followed by the substitution text you want applied.
HEAD This HTML code would appear between the normal & tags at the top of the billing/summery pages.
TOP This HTML code would appear just after the opening tag at the top of the billing/summery pages.
TAIL This HTML code would appear just before the normal tag at the bottom of the billing/summery pages.
TABLE (See Note 2) This section is used to define substitution values for the itemized product table at the top of the billing/summery pages. (i.e. when ’easycart’ field is set to ‘1’).  Each line should be a single substitution.  Each line is in a 2 column tab delimited format.  Enter the table attribute’s fieldname, a hard tab, followed by the substitution value.
SUBMTPG1 NOT ACTIVELY IMPLEMENTED (intended for HTML code to replace the submit button at the bottom of the billing page.)
SUBMTPG2 This HTML code replaces the submit button at the bottom of the summery page.
INPUTCHECK NOT ACTIVELY IMPLEMENTED (intended to filter/validate custom data, while we normally validate other data between the billing & summery pages.)
SHIPPING NOT ACTIVELY IMPLEMENTED (intended for HTML code to be inserted above the shipping address section on the billing page.)
DISPLAYAMT This HTML code would replace our normal display amount text, which appears when not showing itemized product table. (i.e. when ’easycart’ field is set to ‘0’).  You can place [displayamt] into your HTML code, for where you want the order total $ amount to appear.
BODY_…. There are many <BODY_xxxx> tags.  Each of them let you place chunks of HTML code into a different parts of the page body, at specific page locations & only under certain conditions.  Below are the currently available special <BODY_xxxx> payscreen template section tags.
BODY_ASKAMT This HTML code would appear just before the ask amount field on the billing page. (i.e. only when ‘askamtflg’ field is set to ‘1’)
BODY_CARDINFO This HTML code would appear before where the billing address is collected. (i.e. only when ‘paymethod’ is not set to ‘swipe’)

Notes:

  1. Please let us know what exact text from the billing/summery page you want to change & we’ll be glad tell you what language fieldname to use for that particular text.

  2. Possible table attribute fieldnames:
    overall_width = set overall table width greater then 400px (default: 600px)
    lborder_width = set left border width greater then 10px (default: 50px)
    label_width = set product table column label width greater then 75px (default: 125px)
    field_width = set product table fields width greater then 75px (default: 425px)
    cellspacing = set product table cellspacing between 0 & 10 (default: 0)
    cellpadding = set product table cellpadding between 0 & 10 (default: 1)

Template Upload Guide

Follow these steps to upload your completed payscreen template files into your payment gateway account.

  1. Login to your Merchant Administration Area.
    (https://{your-secure-payment-server-domain}/admin)

  2. Click on the “Account Settings” link

  3. Scroll down to the ‘Template Options’ section

  4. Use ‘Upload Template’ feature with the following settings:

    Type: PayScreen Language
    File: [select the template file from your hard drive]
    Template Name: [enter a name for your payscreen template]
    Language: [select the language group the template will belong to]

  5. Click on the “Upload File” button.

  6. If your file was accepted, you will receive a conformation on screen.

When you return to the ‘Account Setting’ section, you will soon see your uploaded payscreen templates listed under the ‘Current Templates’ section. (Please note it may take a few minutes to show up here, from when you uploaded your file.)

If you uploaded 2 templates, under the english language group, with template names ‘abc123’ & ‘def456’, you would see something like this:

PayScreen Templates: 2

  • en - abc123 [X]

  • en - def456 [X]

This tells you how many PayScreen templates you have uploaded into your account (2 in this example). Additionally it displays each of those templates uploaded, by language & pay screen template name. These are the values you would need to use for the ’lang’ & ‘paytemplate’ fields, if you wanted to use that particular payscreen template.

You can click on the particular template name, if you want to see what you uploaded for that given template. You click on the [X] link, if you wish to delete the template from your account.