Menu

TemplateForm Advanced Usage

This guide illustrates advanced usage forTemplateFormusing WorldpayJS.


WorldpayJSis the javascript library behindOwnFormandTemplateForm, occassionally you may need to use some of the more advanced options that it provides or override some defaults.

Remove the "Save Card" button from the inline template form

The 'inline' template form has a "Save Card" button inside the iFrame (seeherefor a screenshot).

If you would like to hide this button and trigger it directly from your parent form, you can use the following example code:

Copied!
<!DOCTYPE html>
<html>
   <head>
      <title></title>
      <script src='https://cdn.worldpay.com/v1/worldpay.js'></script&gt;
   </head>
   <body>
      <form id='paymentForm' method='post' action='/complete'>
         <div id='myPaymentSection'></div>
         <input type='button' onclick='Worldpay.submitTemplateForm()' value='Place Order' />
      </form>
      <script type='text/javascript'>
         window.onload = function() {
           Worldpay.useTemplateForm({
             'clientKey':'your-test-client-key',
             'saveButton':false,
             'form':'paymentForm',
             'paymentSection':'myPaymentSection',
             'display':'inline',
             'reusable':true,
             'type':'card',
             'callback': function(obj) {
               if (obj && obj.token) {
                 var _el = document.createElement('input');
                 _el.value = obj.token;
                 _el.type = 'hidden';
                 _el.name = 'token';
                 document.getElementById('demoForm').appendChild(_el);
                 document.getElementById('demoForm').submit();
               }
             }
           });
         }
      </script>
   </body>
</html>

In the above code example, Worldpay.submitTemplateForm() is directly called to submit both forms in order.

Note: The SAVE CARD button cannot be removed in the modal template setup.

Use the callback handler to take control back from the template form

A callback is a custom function that is called when a tokenisation request is complete. You can use this to take control back from the template form after tokenisation has completed.

To make use of this functionality, you have to specify a fourth optional parameter "callback" in the useTemplate method:

Copied!
<script type='text/javascript'>
   window.onload = function() {
     Worldpay.useTemplateForm({
       'clientKey':'your-test-client-key',
       'saveButton':false,
       'form':'paymentForm',
       'paymentSection':'myPaymentSection',
       'display':'inline',
       'reusable':true,
       'type':'card',
       'callback': function(obj) {
         if (obj && obj.token) {
           var _el = document.createElement('input');
           _el.value = obj.token;
           _el.type = 'hidden';
           _el.name = 'token';
           document.getElementById('demoForm').appendChild(_el);
           document.getElementById('demoForm').submit();
         } else {
           // Handle any errors returned from the API
           // console.log(obj);
         }
       },
       'beforeSubmit': function() {
         // if you would like to disable your submit button
         // document.getElementById('btn').disabled = true;
         return true;
       },
       'validationError': function(obj) {
         // re-enable your submit button on validation failure
         // document.getElementById('btn').disabled = null;
       }
     });
   }
</script>

For a full list of returned object properties, take a look at theTokens API Referencesection.

Use the templateCode to invoke another template than the 'default'

The template form will usually display the 'default' form associated with your Client Key (either TEST or LIVE).

To display another template form, you can associate a "templateCode" with a specific form you want to use. This can be done by selecting the template form you want to use in the Template Builder and specifying the templateCode under 'Template Properties" on the left hand side of the screen.

You then invoke the form using Worldpay.setTemplate('template-code');

Copied!
<!DOCTYPE html>
<html>
   <head>
      <title></title>
      <script src='https://cdn.worldpay.com/v1/worldpay.js'></script&gt;
   </head>
   <body>
      <form id='paymentForm' method='post' action='/complete'>
         <div id='myPaymentSection'></div>
         <input type='button' onclick='Worldpay.submitTemplateForm()' value='Place Order' />
      </form>
      <script type='text/javascript'>
         window.onload = function() {
           Worldpay.useTemplateForm({
             'clientKey':'your-test-client-key',
             'saveButton':false,
             'form':'paymentForm',
             'paymentSection':'myPaymentSection',
             'display':'inline',
             'reusable':true,
             'type':'card',
             'code':'your-template-code',
             'callback': function(obj) {
               if (obj && obj.token) {
                 var _el = document.createElement('input');
                 _el.value = obj.token;
                 _el.type = 'hidden';
                 _el.name = 'token';
                 document.getElementById('demoForm').appendChild(_el);
                 document.getElementById('demoForm').submit();
               }
             }
           });
         }
      </script>
   </body>
</html>

Hide logos shown on the template form

It is possible to disable imagery using the Worldpay.setTemplateOptions() function.

Copied!
<!DOCTYPE html>
<html>
   <head>
      <title></title>
      <meta charset="UTF-8" />
      <script src='https://cdn.worldpay.com/v1/worldpay.js'></script&gt;
      <script type='text/javascript'>
         window.onload = function() {
           Worldpay.useTemplateForm({
             'clientKey':'your-test-client-key',
             'form':'paymentForm',
             'paymentSection':'myPaymentSection',
             'display':'inline',
             'reusable':true,
             'type':'card',
             'templateOptions': {images:{enabled:false}},
             'callback': function(obj) {
               if (obj && obj.token) {
                 var _el = document.createElement('input');
                 _el.value = obj.token;
                 _el.type = 'hidden';
                 _el.name = 'token';
                 document.getElementById('demoForm').appendChild(_el);
                 document.getElementById('demoForm').submit();
               }
             }
           });
         }
      </script>
   </head>
   <body>
      <form id='paymentForm' method='post' action='/complete'>
         <div id='myPaymentSection'></div>
         <div><input type="submit" value="Place Order" /></div>
      </form>
   </body>
</html>

Retrieving card types

It is possible to retrieve more information about the card once it has been tokenised. In the below example we will show what is returned via the console.

Copied!
<script type='text/javascript'>
   window.onload = function() {
     Worldpay.useTemplateForm({
       'clientKey':'your-test-client-key',
       'form':'paymentForm',
       'paymentSection':'myPaymentSection',
       'display':'inline',
       'reusable':true,
       'type':'card',
       'callback':function(obj){
         if (obj && obj.paymentMethod) {
           console.log(obj.paymentMethod);
         }
         // Retrieve the token from obj.token before submitting the form
       }
     });
   }
</script>

For a full list of returned object properties, take a look at theTokens API Referencesection.

Copied!
{
   "type": "ObfuscatedCard",
   "name": "name",
   "expiryMonth": 2,
   "expiryYear": 2015,
   "issueNumber": 1,
   "startMonth": 2,
   "startYear": 2013,
   "cardType": "VISA_CREDIT",
   "maskedCardNumber": "xxxx xxxx xxxx 1111",
   "cardSchemeType": "consumer",
   "cardSchemeName": "VISA CREDIT",
   "cardIssuer": "LLOYDS BANK PLC",
   "countryCode": "GB",
   "cardClass": "credit",
   "prepaid": "false"
}

In order to demonstrate controlling the process if only a particular card type is matched, we can do the following:

Copied!
<script type='text/javascript'>
   window.onload = function() {
     Worldpay.useTemplateForm({
       'clientKey':'your-test-client-key',
       'form':'paymentForm',
       'paymentSection':'myPaymentSection',
       'display':'inline',
       'reusable':true,
       'type':'card',
       'callback':function(obj){
         if (obj && obj.paymentMethod) {
           if (obj.paymentMethod.cardType && obj.paymentMethod.cardType=='VISA_CREDIT') {
             // We now know that the card is of type Visa Credit
             // Retrieve the token from obj.token before submitting the form
           }
         }
       }
     });
   }
</script>

CVC Templates

For card-on-file payments with CVC on, you can use the CVC template to update your customer's CVC details. This can be done once you have a reusable token from a standard template form response. <!DOCTYPE html> <html> <head> <title></title> <meta charset="UTF-8" /> <script src= "https://cdn.worldpay.com/v1/worldpay.js"></script&gt; <script type='text/javascript'> window.onload = function() { Worldpay.useTemplateForm({ 'clientKey':'your-test-client-key', 'token':'your-reusable-token', 'form':'paymentForm', 'paymentSection':'myPaymentSection', 'display':'inline', 'reusable':true, 'type':'cvc', 'callback': function(obj) { console.log(obj); return false; } }); }; </script> </head> <body> <form id="paymentForm" method="POST" action="/complete"> <div id='myPaymentSection'></div> <div> <input type="button" onclick='Worldpay.submitTemplateForm()' value="Update CVC" /> </div> </form> </body> </html>

Copied!

Full list of settings that can be changed

Below you will find a full list of settings that can be changed:

Token Template:

Copied!
Worldpay.useTemplateForm({
  'clientKey':'your-test-client-key',
  'form':'paymentForm',
  'paymentSection':'myPaymentSection',
  'display':'inline',
  'type':'card',
  'reusable':true,
  'saveButton':false,
  'templateOptions':[Template Options Object],
  'code':'your-template-code',
  'callback':function(obj){
    console.log(obj);
  }
});

CVC Template:

Copied!
Worldpay.useTemplateForm({
  'clientKey':'your-test-client-key',
  'token':'your-reusable-token',
  'form':'paymentForm',
  'paymentSection':'myPaymentSection',
  'display':'inline',
  'reusable':true,
  'type':'cvc',
  'callback': function(obj) {
    console.log(obj);
  }
});

Template Options Object:

Copied!
{
  addedText: "Payment details added",
  addedTextCVC: "CVC added",
  enterCardDetailsButton: "Enter card details",
  iframeOverlay: 'position: absolute;top: 0px;bottom: 0px;left: 0px;right: 0px;background-color: #000;-ms-filter: "progid:DXImageTransform.Microsoft.Alpha(Opacity=80)";filter: alpha(opacity=80);-moz-opacity: 0.8;-khtml-opacity: 0.8;opacity: 0.8;',
  iframeHolderInline: 'position: relative;top: 0px;background-color: #fff;border:none;',
  iframeHolderModal: 'position: absolute;top: 100px;left: -350px;background-color: #fff;width: 220px;height: 220px;margin-left: 50%;border:none;',
  dimensions: {
      width:false,
      height:false
  },
  images: {
    enabled: true
  }
}

Suggested next steps