Menu

Taking Card Details Using Your Own Form

This guide describes how to take card details using your own form.


We recommend this method if you are either:

Otherwise we recommend you use thetemplate formto take card details.

Overview

When you use your own payment form you must ensure that you include a script which replaces sensitive card data with a Worldpay token.

In order to take card details using your own form, it needs to include a script in your payment form which replaces sensitive card data with a Worldpay token.

Let's look at a typical payment form:

Copied!
<form action="/complete" id="paymentForm" method="post">
   <span id="paymentErrors"></span>
   <div class="form-row">
      <label>Name on Card</label>
      <input data-worldpay="name" name="name" type="text" />
   </div>
   <div class="form-row">
      <label>Card Number</label>
      <input data-worldpay="number" size="20" type="text" />
   </div>
   <div class="form-row">
      <label>Expiration (MM/YYYY)</label> 
      <input data-worldpay="exp-month" size="2" type="text" /> 
      <label> / </label>
      <input data-worldpay="exp-year" size="4" type="text" />
   </div>
   <div class="form-row">
      <label>CVC</label>
      <input data-worldpay="cvc" size="4" type="text" />
   </div>
   <input type="submit" value="Place Order" />
</form>

Fields representing sensitive card data (card number, CVC, expiration month and year) do not have a name attribute, meaning that they will not be submitted to your server. They do however have a data-worldpay attribute, ensuring that these fields are stored on the Worldpay servers.

We recommend that you include the Card Security Code (also known as CVC, CVV or CV2). This field, however, is only mandatory when you have the Card Security Code Checks switched on in your risk settings.

The Name on Card has both a name and a data-worldpay attribute. This means it will be submitted both to Worldpay and to your server, as it is needed in both areas.

You can set-up this form by taking the following steps:

  • Include Worldpay.js in your page.
  • Create a payment form with the relevant attributes
  • Set your client key
  • Decide whether you want to make one-off or multiple charges to the card
  • Attach Worldpay.js to your payment form

1. Include Worldpay.js in your page

The first step is to ensure that the Worldpay.js library gets included when your payment form is loaded. This only needs to be done on the page which you use to collect the payment details.

Copied!
<script src="https://cdn.worldpay.com/v1/worldpay.js"></script >

The list of browsers that are supported by Worldpay.js can be foundhere.

2. Create a payment form with the relevant attributes

At this stage you need to add data-worldpay attributes to all card related fields, as demonstrated in the example at the top of this page.

The minimum required fields are name, number, exp-month and exp-year. You can also capture a CVC, which is recommended but not required unless you have Card Security Code Checks switched on in your risk settings.

Note: You should remove the name attribute from all of these fields to prevent them being sent to your server. The only exception to this is the name on the card which is not sensitive information: you can optionally retain the name attribute here for your server, but must include the data-worldpay attribute in order for this information to be sent to the Worldpay server.

3. Set your Client Key

Setting the client key allows worldpay.js to identify the messages it sends back to our server as coming from you. You can find your client key here.

4. Decide whether you want to make one-off or multiple charges to the card

Worldpay allows you to store card details so you can charge a card multiple times. You can use this to offer your customerscard-on-filepayment orrecurring paymentoptions.

You need to indicate whether the card details are for single or multiple use when initially taking them. For multiple use you should set the reusable flag:

Copied!
reusable: true

For single use, either set reusable to false or omit it – the default option is false.

5. Attach Worldpay.js to your form

In this final step, Worldpay.js is executed as soon as the user clicks on "Place Order".

Copied!
var form = document.getElementById('paymentForm');
Worldpay.useOwnForm({
   'clientKey': 'your-test-client-key',
   'form': form,
   'reusable': false,
   'callback': function(status, response) {
      document.getElementById('paymentErrors').innerHTML = '';
      if (response.error) {
         Worldpay.handleError(form, document.getElementById('paymentErrors'), response.error);
      } else {
         var token = response.token;
         Worldpay.formBuilder(form, 'input', 'hidden', 'token', token);
         form.submit();
      }
   }
});

Before the form is submitted to you, Worldpay.useOwnForm() sends card details to the Worldpay server for storage and to create a token. All fields with the attribute data-worldpay are submitted at this point. This function takes two arguments: the HTML form's document reference and the callback function. The callback function will be called once tokenisation is complete.

If the Worldpay server returns errors, you can optionally use Worldpay.handleError() to display an error message back to the user, as shown in this example.

If there are no errors, you can retrieve the token. This token is used instead of the card details to make a payment from your server.

Finally, in Worldpay.formBuilder() all sensitive card data is removed from the form, replaced with the token and only then is the form submitted back to your server. This function takes six arguments:

  1. The HTML form's document reference
  2. The element type(e.g. input)
  3. The type attribute of the element (e.g. hidden)
  4. The name of the element
  5. The value of the element
  6. An optional ID of the element that defaults to the name of the element if not specified

Also, the Worldpay.formBuilder() method only appears to append a new element based on the function arguments and does not change anything else on the form or submit it.

Putting it all together

Here you can see an example of the completed process:

Note: in this example we want to charge the card multiple times, so reusable is set to true. If you only want to use the token once you can leave out reusable because the default is false.

Copied!
<!DOCTYPE html>
<html>
   <head>
      <title></title>
      <meta charset="UTF-8" />
      <script src="https://cdn.worldpay.com/v1/worldpay.js"></script&gt;
   </head>
   <body>
      <form action="/complete" id="paymentForm" method="post">
         <span id="paymentErrors"></span>
         <div class="form-row">
            <label>Name on Card</label>
            <input data-worldpay="name" name="name" type="text" />
         </div>
         <div class="form-row">
            <label>Card Number</label>
            <input data-worldpay="number" size="20" type="text" />
         </div>
         <div class="form-row">
            <label>Expiration (MM/YYYY)</label>
            <input data-worldpay="exp-month" size="2" type="text" />
            <label> / </label>
            <input data-worldpay="exp-year" size="4" type="text" />
         </div>
         <div class="form-row">
            <label>CVC</label>
            <input data-worldpay="cvc" size="4" type="text" />
         </div>
         <input type="submit" value="Place Order" />
      </form>
      <script type="text/javascript">
         var form = document.getElementById('paymentForm');
         Worldpay.useOwnForm({
           'clientKey': 'your-test-client-key',
           'form': form,
           'reusable': false,
           'callback': function(status, response) {
             document.getElementById('paymentErrors').innerHTML = '';
             if (response.error) {               Worldpay.handleError(form, document.getElementById('paymentErrors'), response.error); 
             } else {
               var token = response.token;
               Worldpay.formBuilder(form, 'input', 'hidden', 'token', token);
               form.submit();
             }
           }
         });
      </script>
   </body>
</html>

At this point you have stored your customer’s card details securely with Worldpay but have not yet charged the customer any money.

Charging the customer needs to be done from your server, and the process is explained in the next guide,Making Payments.

Retrieving card types

The callback response also contains other valuable information such as card types.
For a full list of returned object properties, take a look at theTokens API Reference

Suggested next steps: