Integration Libraries

Quick Find

Go straight to the section you need.

1.0 Gateway Integration →

1.1 Introduction

1.2 Terminology

1.3 Integration Methods

1.4 Integration Libraries

1.5 Security and Compliance

1.6 Prerequisites

1.7 Integration Details

1.8 Authentication

1.9 Supported Actions

2.0 New Transactions →

2.1 Request Fields

2.2 Response Fields

3.0 Management Requests →

3.1 Request Fields

3.2 Response Fields

4.0 AVS/CV2 Checking →

4.1 Background

4.2 Benefits and Limitations

4.3 Request Fields

4.4 Response Fields

5.0 3-D Secure Authentication →

5.1 Background

5.2 Benefits and Limitations

5.3 Hosted Implementation

5.4 Direct Implementation

5.5 Request Fields

5.6 Response Fields

5.7 Advanced Features

11 Receipts and Notifications →

11.1 Background

11.2 Customer Email Receipts

11.3 Request Fields

11.4 Response Fields

17 Advanced Data →

17.1 Customer Request Fields

17.2 Merchant Request Fields

17.3 Supplier Request Fields

17.4 Delivery Request Fields

17.5 Receiver Request Fields

17.6 Shipping Request Fields

17.7 Device Information Fields

 

19 Gateway Wallet → 

19.1 Background

19.2 Benefits and Limitation

19.3 Hosted

19.4 Direct Implentation

19.5 Request Fields

19.6 Response Fields

 

26 Digital Wallet Transactions →

26.1 Background

26.2 Benefits and Limitations

26.3 Configuration

26.4 Hosted Implementation

26.5 Direct Implementation

26.6 Request Fields

26.7 Response Fields

26.8 Digital Wallet Tokens

Appendix

A-1 Response Codes

A-1.1 Authorisation Response Codes

A-1.2 Gateway Response Codes

A-2 AVS / CV2 Check Response Codes

A-3 3-D Secure Enrolment/Authentication Codes

A-4 3-D Secure Enrolment/Authentication Only

A-9 Duplicate Transaction Checking

A-10 Capture Delay

A-11 Card Identification

A-12 Integration Testing

12.1 Test Amounts

12.2 Test Cards

12.3 3-D Secure Testing

 

A-13 Sample Signature Calculation

A-14 Transaction Life cycle

A-14.1 Authorise, Capture and Settlement

A-14.2 Transaction States

A-15 Transaction types

A-15.1 E-commerce (ECOM)

A-15.2 Mail Order/Telephone Order (MOTO)

A-15.3 Continuous Authority (CA)

 

A-16 Payment Tokenisation

A-16.1 PREAUTH, SALE, REFUND, VERIFY requests

A-16.2 REFUND_SALE requests

A-16.3 CANCEL or CAPTURE requests

A-16.4 QUERY requests

A-16.5 SALE or REFUND Referred Authorisation requests

 

A-18 PSD2 SCA Compliance

A-18.1 Obtaining Strong Customer Authentication

A-18.2 Exemptions to Strong Customer Authentication

A-18.3 SCA Using 3-D Secure

 

A-19 Hosted Payment Page Options

A-20 Integration Libraries

A-20.1 Gateway Integration Library

A-20.2 Hosted Payment Page Library

A-20.3 Hosted Payment Fields Library

 

A-21 Example HTTP Requests

A-21.1 Hosted Integration

A-21.2 Direct Integration

A-21.3 Batch Integration

 

A-22 Example Integration Code

A-22.1 Hosted Integration

A-22.2 Direct Integration

A-22.3 Batch Integration

 

A-23 Example Library Code

A-23.1 Gateway Integration Library

A-23.2 Hosted Payment Page Library

A-23.3 Hosted Payment Fields Library

A-20 Integration Libraries

We can provide a range of libraries to help you to integrate with the Gateway.

These libraries include simple sever-side classes in many popular programming languages through to client-side scripts to help with the integration of the Hosted Payment Page or Hosted Payment Fields. 

The server-side libraries can be obtained by contacting customer support. 

The client-side libraries can be downloaded directly from the Gateway server.

A-20.1 Gateway Integration Library

A simple server-side integration library is available to simplify the preparation and transmission of Hosted and Direct Integration requests.

The library is available in many popular programming languages and is based around a single class: the Gateway class.

The Gateway integration library does not currently support the preparation and transmission of Batch Integration requests.

A-20.1.1 Library Namespace 

To avoid polluting the global namespace, the library uses the ‘P3/SDK’ namespace where supported by the language. 

 

A-20.1.2 Gateway Configuration 

Before you can use the Gateway class, you will need to configure the following properties to match your integration parameters explained in section 1.6 and authentication parameters documented in section 1.8.

Property Name
hostedURL
Type
string
Description
Absolute URL provided for the Hosted Integration.
Property Name
directURL
Type
string
Description
Absolute URL provided for the Direct Integration.
Property Name
merchantID
Type
string
Description
Your unique Merchant ID to be passed in the merchantID integration field.
Property Name
merchantPwd
Type
string
Description
Any password configured on your Merchant Account as per section 1.8.1.
Property Name
merchantSecret
Type
string
Description
Any secret configured on your Merchant Account as per section 1.8.2.
Property Name
proxyUrl
Type
string
Description
Absolute URL to any proxy required for connections. (eg https://www.proxy.com:3128)
Property Name
debug
Type
boolean
Description
True to enable debugging output.

A-20.1.3 Gateway Methods

The follow methods are made available by the Gateway class: 

 

string hostedRequest(mixed[] request, string[] options) 

Return an HTML fragment that can be included in your webpage to render a <form> which will send the provided request data to the Gateway’s Hosted Integration when submitted.

The request parameter should be an associative array containing the request fields required to be sent. The request fields are not validated.

The following class properties are used unless alternative values are provided in the request array: directUrl, merchantID, merchantPwd, merchantSecret.

The options parameter is an optional associative array containing options that can be used to modify the returned HTML fragment as follows: 

  • • formAttrs – string containing additional attributes to include in the form tag. 
  • submitAttrs – string containing additional attributes to include in the submit button tag. 
  • • submitImage – string containing the URL to use as the submit button. 
  • • submitHtml – string containing HTML to use as the label on the submit <button>. 
  • submitText – string containing text to use as the label on the submit <input>. 

The submitImage, submitHtml and submitText options are mutually exclusive and will be checked for in that order. If none is provided, then a submitText value of ‘Pay Now’ is assumed. 

If a merchantSecret is provided, then the method will add the correct signature field to the request. 

An exception is thrown if the HTML fragment cannot be composed. 

The verifyResponse() method can be used to validate and decode any response POSTed back to your website.

Please refer to appendix A-23.1.1 for an example of how to use this method.

 Returns a string containing the HTML fragment if successful; throws an exception otherwise.

mixed[] directRequest(mixed[] request, string[] options)

Return the response received when sending the provided request to the Gateway’s Direct Integration. 

The request parameter should be an associative array containing the request fields required to be sent. The request fields are not validated. 

The following class properties are used unless alternative values are provided in the request array: directUrl, merchantID, merchantPwd, merchantSecret

The options parameter is not used and reserved for future use. 

If a merchantSecret is provided, then the method will add the correct signature field to the request and check the signature field on the response. 

An exception is thrown if the request cannot be sent; or the response cannot be received; or if the response’s signature is incorrect. 

Please refer to appendix A-23.1.2 for an example of how to use this method. 

Returns an associative array containing the received response fields; otherwise, throws an exception.

 

void prepareRequest(mixed[] &request, string[] &options, string &secret, string &direct_url, string &hosted_url)

Prepare a request for sending to the Gateway’s Direct Integration. 

The request parameter should be a reference to an associative array containing the request fields required to be sent. The request fields are not validated. 

The merchantSecret, directUrl and hostedUrl configuration properties will be returned in the secret, direct_url and hosted_url method parameters. These properties can be overridden by providing them in the request, in which case they will be extracted and removed from the request. 

The merchantID and merchantPwd configuration properties will be added to the request.

A few known Gateway response fields will be removed from the request, if present, to avoid confusion, notably the responseCode, responseMessage, responseStatus, state fields.

An exception will be thrown if the request does not contain an action element or a merchantID element (and none could be inserted). 

 

void verifyResponse(mixed[] &response, string secret) 

Verify a response received from the Gateway’s Hosted or Direct Integration. 

The response parameter should be a reference to an associative array containing the response received from the Gateway, either from the Direct Integration or as POSTed from the Hosted Integration. 

The secret parameter should be any Merchant secret to use when checking the response’s signature element. If not provided, then the value of the merchantSecret property is used. 

Any signature element is removed from the response

An exception is thrown if the response is not valid, does not contain a responseCode element or its signature is incorrect. 

Please refer to appendix A-23.1.1 for an example of how to use this method. 

 

string sign(mixed[] request, string secret, mixed partial = false)

Return the signature for the provided request data.

The request parameter should be a reference to an associative array containing the request fields required to be sent. The request fields are not validated. 

The secret parameter should be the Merchant secret to use when signing the request.

The partial parameter should be either the boolean false or comma separated string; or an array of strings containing the names of the request elements to sign.

Returns a string containing the correct signature for the request.

A-20.2 Hosted Payment Page Library

A simple client-side script is available to simplify the displaying of the Hosted Payment Page in a lightbox overlaying your website. 

The library is available as a JavaScript script and is based around a single class: the Form class. The script is compatible with most modern web browsers. 

The script can be loaded directly from our Gateway server as follows 1

 

  1. <script src=“https://gateway.swipen.co.uk/sdk/web/v1/js/hostedforms.min.js”></script> 

 

If the script detects the presence of the jQuery API, then it will extend the jQuery object with its own plugin method. However, jQuery is not needed in order to use the script.

 

 

A-20.2.1 Hosted Payment Pages

Hosted Payment Pages are a prebuilt webpage residing on our server that you can use to collect sensitive payment details without those details’ touching your server. The standard Hosted Payment Page is designed so that it can be displayed in a transparent overlay over your website, thus making the Customer feel as though they never left your shopping cart. 

The standard Hosted Integration examples redirect the Customer’s browser to the Hosted Payment Page, resulting it appearing on a new browser page and not overlaying your website. The Hosted Payment Page library provides the scripting necessary to result in the redirection, causing the Hosted Payment Page to appear in an overlay and not a new browser page, without your having to make any modifications to your website. The library can also simplify the creation of the Hosted Integration redirection FORM if required. 

 

A-20.2.2 Library Namespace

To avoid polluting the global namespace, the library extends the global window object with a hostedForms object containing the following properties: 

  • forms – array containing all the instantiated Form objects. 
  • classes – array containing all the instantiable classes. 

o form – Form class prototype. 

 

1 Please use the correct hostname as explained in section 1.6.  

A-20.2.3 Form Construction 

The construction method can be used to build and prepare a HTML FORM element for use with the modal Hosted Payment Page; or to prepare an existing element. The method signature is as follows: 

Form(element, data) 

The element parameter should be either the id or DOM node of an existing FORM or DIV DOM element. 

If the element is a DIV node, then the data is used to create a new FORM node within the element

If the element is a FORM node, then the data is used to modify the existing FORM element

The data parameter should be an object containing construction details and can contain the following optional properties: 

  • id – string containing the value to use as the FORM tag’s id attribute. 
  • url – string containing the URL to use as the FORM tag’s src attribute. 
  • attrs – object whose properties are added as additional attributes on the FORM tag. 
  • modal – boolean indicating that the HPP should open in a modal overlay. 
  • data – object whose properties are added as hidden input elements in the FORM. 
  • submit – object containing details for a submit button that should be added to the FORM. o type – type of submit button, either ‘auto’, ‘image’, ‘button’, ‘input’ 

o id – string containing the value to use as the submit button’s id attribute.
o attrs – object whose properties are added as additional attributes on the submit button.
label – string containing button label (or ‘alt’ attribute for ‘image’ buttons)
o src – string containing image URL for ‘image’ buttons. 

The constructor will submit the FORM immediately after preparation if the data.submit.type property is ‘auto’; or if the existing FORM element has a data-hostedform-autosubmit attribute. Otherwise, an event handler will be attached to the submit button to disable it automatically when clicked, to help prevent your Customer from clicking it twice. 

The constructor will prepare the FORM so that the Hosted Payment Page (HPP) will be opened in a modal overlay if the data.modal property is true; or if the existing FORM element has a data-hostedform-modal attribute; or has an action attribute containing the string ‘modal/’ or ending in the string ‘modal’.

The modal overlay is automatically created as a semi-opaque IFRAME element that fills the browser display. The Hosted Payment Page is then loaded into this IFRAME and being semi-opaque, your shopping cart will remain visible beneath, but greyed out and noninteractive. When the Customer closes the Hosted Payment Page, then their browser will be redirected to the URL you provided using the redirectURL parameter. This will cause the original page and IFRAME to be replaced by your new page. 

A-20.2.4 Form Methods 

The follow methods are made available by the Form class:

 void destroy() 

Destroys the Form, reverting its element back to its original state. 

A-20.2.5 jQuery Plugin 

If the jQuery API has been loaded into the browser before the script, then it will extend the jQuery object with its own plugin method. 

Construction and destruction can then be done as follows:

 

$(element).hostedForm(data); 

$(element).hostedForm(‘destroy’);

A-20.3 Hosted Payment Fields Library

A simple client-side script is available to support the displaying of Hosted Payment Fields in your payment form.

The library is available as a JavaScript script and is based around two classes: the Form and Field classes. The script is compatible with most modern web browsers.

The script can be loaded directly from our Gateway server as follows1: 

 

  1. <script src=“https://gateway.swipen.com/sdk/web/v1/js/hostedfields.min.js”></script> 

 

The script requires the jQuery API, which must be loaded prior to the script.

 

A-20.3.1 Hosted Payment Fields

Hosted Payment Fields are a set of prebuilt JavaScript UI components that can be used by your website’s HTML payment form to collect sensitive payment details without those details touching your server. They provide you with the PCI benefits of using a Hosted Payment Page, while allowing you the ability to design and implement your own payment forms. 

There are 6 predefined Hosted Payment Fields available as follows: 

  • cardNumber – collects the card number. 
  • cardCVV – collects the card cvv. 
  • cardExpiryDate – collects the card expiry month and year. 
  • cardStartDate – collects the card start/issue month and year. 
  • cardIssueNumber – collects the card issue number. 
  • cardDetails – collects the card number, expiry date and cvv in a single field. 

The cardNumber field is designed to collect a card number, including an icon used to display the card type. The field will only accept digits and spaces and validate that any entered value is a correctly formatted card number and insert spaces at the correct positions for the card type as the number is typed. 

The cardCVV field is designed to collect a card CVV. The field will only accept digits and will validate that any entered value is a correctly formatted CVV, taking into account the card type as determined by an associated cardNumber field. 

The cardExpiryDate and cardStartDate fields are designed to collect a card expiry date and card issue date respectively. The fields can render as a pair of select controls containing the months and a suitable range of years; or as an input control that will only allow digits to be entered and automatically formatted as a month / year entry. The field will validate that any entered value is a valid month and year combination.

The cardIssueNumber field is designed to collect a card issue number. The field will only accept digits and will validate that any entered value is a correctly formatted issue number. 

1 Please use the correct hostname as explained in section 1.6.  

The cardDetails field is designed to collect all of the essential card details. It combines the cardNumber, cardExpiryDate and cardCVV fields into a single line compound field design to allow easy entry of the card details and to complement the look of your checkout. 

These hosted fields can be used on your payment form alongside any standard HTML form fields, for example, any collecting the Cardholder’s billing or delivery addresses and any other order information you require. 

The field type is either: passed as the value of the type option the Field construction, provided by the HTML element’s meta data; or provided via the HTML element’s type attribute (prefixed with the ‘hostedfield:’ name space). 

The following example shows all three approaches to specifying the field type:

 

  1. <input type=“hostedfield:cardNumber” name=“card-number”
  2. <div class=“hostedfield” data-hostedfield-type=“cardExpiryDate”></div> 
  3. <input data-hostedfield=‘{“type”:”cardCVV”}’

 

It is highly recommended that you adopt a single approach as above and don’t mix and match. 

Each field type has its own additional configuration options, as detailed in section A-20.3.6. 

 

A-20.3.2 Library Namespace

To avoid polluting the global namespace, the library extends the global window object with a hostedFields object containing the following properties: 

  • forms – array containing all the instantiated Form objects. 
  • classes – array containing all the instantiable classes. o form – Form class prototype.

 

A-20.3.3 Form Construction

The construction method can be used to prepare a HTML FORM for use with Hosted Payment Field components. The method signature is as follows:

 

Form(element, options) 

 

The element parameter should be the DOM node of an existing FORM tag.

The options parameter should be object containing one of more of the following optional properties: 

  • autoSetup – boolean indicating whether setup should be handled automatically. 
  • autoSubmit – boolean indicating whether submission should be handled automatically. 
  • merchantID – string containing the merchantID the payment request is for. 
  • stylesheet – string containing DOM selector for any stylesheets to be used. 
  • tokenise – string/array/object specifying fields whose values should be tokenised. 
  • fields – object containing field configuration by field type. 
  • locale – string containing the desired locale. 
  • classes – object containing names of extra CSS classes to use. 
  • submitOnEnter – boolean indicating whether the enter key should cause the form to submit. 
  • nativeEvents – boolean indicating that native browser events should be fired. 

Any options parameter will be merged with those provided via meta data supplied, using data-hostedfield and/or data-hostedfield-<option> attributes; or via existing attributes or properties of the element

The autoSetup option can be used to disable the automatic creation of Field objects for the FORM child controls by calling the autoSetup() method during the Form construction. If automatic setup is disabled, then you must manually instantiate Field objects and attach them to the Form as required, using the addField() method. This option or manually calling the autoSetup() method minimises the amount of JavaScript you have to write. Automatic operation is good if you don’t need to customise the operation or can’t customise it by reacting to the Form or Field events. The option defaults to true and cannot be changed once the Form has been created. 

The autoSubmit option can be used to disable the automatic handling of the FORM submission via the autoSubmit() method. If automatic submission is disabled, then you must manually retrieve the sensitive payment details by calling getPaymentDetails() and include them in the form submission data. This option or manually calling the autoSubmit() method minimises the amount of JavaScript you have to write. Automatic operation is good if you don’t need to customise the operation or can’t customise it by reacting to the Form or Field events. The option defaults to true and cannot be changed once the Form has been created. 

The merchantID option can be used to specify the merchantID with which the final paymentToken will be used. The option defaults to the value of any child INPUT node whose name is ‘merchantID’ and can be changed at runtime by calling the setMerchantID() method or by altering the options using the jQuery hostedForm() plugin method. 

The stylesheet option can be used to specify a DOM selector used to locate stylesheets that should be parsed for styles related to the Hosted Payment Fields. Refer to section A-20.3.10 for how to style the Hosted Payment Fields using CSS stylesheets. The option defaults to the DOM selector string ‘link.hostedfield[rel=stylesheet], style.hostedfield’ and can be changed at runtime by calling the setStylesheet() method; or by altering the options using the jQuery hostedForm() plugin method. 

The tokenise option can be used to specify addition FORM controls whose values, as returned by the jQuery.val() method, should be included in the final paymentToken

The option’s value must be either: 

  • A string containing a DOM selector used to select one or more controls. 
  • An array containing values used to jQuery.filter() down to one or more controls. 
  • An object whose properties are the name of fields to tokenise and whose values are objects containing a selector property used to select a control. 

For the first two, the tokenised field’s name will be taken from the controls data-hostedfield-tokenise attribute or name attribute. For the third, the name is property name in the tokenise object. If the field’s name is of the format ‘paymentToken[<name>]’, then only the ‘<name>’ part is used. The option defaults to the DOM selector string ‘INPUT.hostedfield-tokenise:not(:disabled),INPUT[data-hostedfield-tokenise]:not(:disabled, INPUT[name^=”paymentToken[“]:not(:disabled)’ and cannot be changed once the Form has been created. 

The fields options can be used to specify default options for the different types of Hosted Payment Fields. The option’s value should be an object whose properties are the fields type or the wildcard type ‘any’ and whose values are objects whose properties are the default options for fields of that type. The values can also contain a selector property containing a DOM selector that is used during the automatic setup stage to select a FORM’s child element to add as a Field of the specified type automatically. The option has no default value and cannot be changed once the Form has been created. 

The locale option can be used to specify the language that should be used by the Hosted Payment Fields attached to this Form. The option defaults to the value provided by any lang attribute on the element or closest ancestor and cannot be changed once the Form has been created.

The classes options can be used to specify additional CSS class names to add in addition to the default classes documented in section A-20.3.9. The value is an object whose properties are the default class name and whose values are a string containing the additional class name(s) to use. The option has no default and cannot be changed once the Form has been created. 

The submitOnEnter option can be used to specify if pressing the enter key when typing a Field value should cause the Form to submit. The option defaults to false and cannot be changed once the Form has been created. 

The nativeEvents option can be used to specify that any associated native event should be fired when a ‘hostedField:’ prefixed Field event is fired (as documented in section A-20.3.8). For example, when enabled, if the ‘hostedfield:mouseover’ event is fired, then the native ‘mouseover’ event is also fired. The option defaults to false and cannot be changed once the Form has been created.

If not explicitly constructed, a Form object will be automatically instantiated and attached to the FORM DOM node as soon as any Field object is instantiated on a child DOM node. 

Example Form construction is as follows: 

  1. var form = new window.hostedFields.classes.Form(document.forms[0],{ 
  2. // Auto setup the form creating all hosted fields (default) 
  3. autoSetup: true
  4. // Auto validate, tokenise and submit the form (default) 
  5. autoSubmit: true
  6. // Additional fields to tokenise 
  7. tokenise: ‘.add-to-token’
  8. // Stylesheet selection 
  9. stylesheets: ‘#hostedfield-stylesheet’
  10. // Optional field configuration (by type) 
  11. fields: { 
  12. any: { 
  13. nativeEvents: true 
  14. }, 
  15. cardNumber: { 
  16. selector: $(‘#form2-card-number’), 
  17. stylesheet: $(‘style.hostedform, style.hostedform-card-number’
  18. }, 
  19. // Additional CSS classes 
  20. classes: { 
  21. invalid: ‘error’ 
  22. }); 

 

Or using meta data on the HTML FORM element: 

  1. <form data-hostedfields=‘{“autoSetup”:true,”autoSubmit”:true,”tokenise”:”.add-to-token”,”stylesheets”:”#hostedfield-stylesheet”,”fields”:{“any”:{“nativeEvents”:true},”cardNumber”:{“selector”:”#form2-card-number”,”stylesheet”:”style.hostedform, style.hostedform-card-number”}},”classes”:{“invalid”:”error”}}’ method=“post” novalidate=“novalidate” lang=“en”
  2. <script> 
  3. var form = new window.hostedFields.classes.Form{document.forms[0]); 
  4. </script> 

 

A-20.3.4 Form Methods

The follow methods are made available by the Form class: 

 

void autoSetup()

Automatically setup the form by scanning the Form element for child nodes to control as Hosted Payment Fields. Child nodes are selected if they: 

  • have a type attribute with a hostedfield:<type> value (INPUT nodes only)
  • have a data attribute with a hostedfield.<type> property. 
  • match a DOM selector provided by the fields.<type>.selector option. 

If multiple selection criteria are present, then they must all specify the same Field type or an exception is thrown. 

This method is called during the Form construction unless the autoSetup option is false.

 

void autoSubmit() 

 

Automatically handles any attempted FORM submission by checking the FORM’s controls are valid by calling the validate() method; and then requesting the paymentToken using the getPaymentDetails() method; and finally adding the token to the forms fields using the addPaymentToken() method. Failure to validate or request the payment token will cause the form submission to be stopped.

You can affect the automatic submission stages by listening for events and preventing their default actions. The full list of events is documented in section A-20.3.5. 

This method is attached to the FORM submit event during the Form construction unless the autoSubmit option is false, or the autoSubmit option is null and the autoSetup option is false.

If automatic submission is disabled, then you must react to the FORM’s submit event and then request the paymentToken using the getPaymentDetails() method and ensure that the token is sent as part of the form’s data. 

 

boolean addField(Field f) 

Add a hosted Field to the Form. 

Returns true if successful, false otherwise. 

 

boolean delField(Field f) 

Remove a hosted Field from the Form

Returns true if successful, false otherwise. 

 

promise validate(boolean submitting) 

Validate all Field values on the Form, either during submission or not. 

Returns a promise that will be resolved when the validation is complete.

 

object[] getInvalidElements() 

Get details about all invalid FORM controls (not just invalid hosted Field elements).

 

  • Returns an array of objects containing the following properties:
    element – DOM element. 
  • message – DOM elements validationMessage property or ‘Invalid value’. 
  • label – associated LABEL text. 
  • field – Field instance (if DOM element is a hosted Field). 

 

object getValidationErrors() 

 

Get the validation errors for all invalid FORM controls (not just invalid hosted Field elements). 

Returns an object whose properties are the associated labels, names or id of the invalid FORM controls and whose values are the error message for that control.

promise getPaymentDetails(object tokenData, boolean validate) 

Gets the payment details, generating a paymentToken containing the hosted Field values; any values specified by the tokenise option; and any passed tokenData. The Form will be validated first if required. 

Returns a promise that will be resolved when the payment details have been obtained, passing the details as an object containing the following properties: 

  • success – boolean true if successful, false otherwise. 
  • message – string containing message to display if not successful. 
  • errors – object containing details about invalid payment data. 
  • invalid – object as returned by getValidationErrors() method. 
  • paymentToken – string containing generated paymentToken

 

void addPaymentToken(string token)

 Add the payment token as the value of a Form child INPUT whose name is ‘paymentToken’, creating the control if needed. Any created control will be given a type of ‘hidden’. 

 

void setMerchantID(string merchantID) 

Set the merchantID used by the payment form. 

 

void setStylesheet(string selector) 

Set the DOM selector used to select the stylesheet(s) used by the Form.

 

object defaultFieldOptions(string type) 

Get any default field options specified via the fields option, resulting from the merger of its optional any and <type> properties.

 

Returns an object whose properties are the default options. 

 

void forceSubmit() 

Forcefully submit the FORM element as if a child submit button had been clicked. 

 

void reset() 

Reset all the Form, setting all Field values back to their initial values. 

 

void destroy() 

Destroys the Form, reverting its element back to its original state.

 

A-20.3.5 Form Events 

The following events may be fired by the Form object and you can use these to hook into and modify the object’s behaviour: 

Event Name 1
create
Description
Fired when a Form has been created.
Event Name 1
destroy
Description
Fired when a Form has been destroyed.
Event Name 1
presubmit
Description
Fired by the autoSubmit() method prior to handling the submission. You can prevent the handling of the submission and handle it yourself by calling the Events preventDefault() method.
Event Name 1
valid
Description
Fired by the autoSubmit() method if the FORM contains valid data prior to requesting the payment details. You can prevent the continued handling of the submission and handle it yourself by calling the Events preventDefault() method or by invalidating the FORM.
Event Name 1
submit-invalid
Description
Fired by the autoSubmit() method if the FORM contains invalid data prior to displaying the validity using the DOM reportValidity() method. You can prevent the reportValidity() call and display the validity yourself by calling the Events preventDefault() method.
Event Name 1
submit
Description
Fired by the autoSubmit() method prior to submitting the FORM. You can prevent the FORM from submitting by calling the Events preventDefault() method.
Event Name 1
error
Description
Fired by the autoSubmit() method if an exception is caught prior to displaying the error, using the JavaScript alert() function. You can prevent the alert() call and display the error yourself by calling the Events preventDefault() method.

1 Event names are prefixed with the ‘hostedform:’ namespace not shown in the table. 

 

The presubmit, valid, submit-invalid, submit and error events fired by the autoSubmit() method the payload is an object with the following properties: 

  • success – boolean false. 
  • message – error message if error otherwise null. 
  • invalid – result of getValidationErrors() method if Form invalid. 
  • submitting – boolean true. 

 

A-20.3.6 Field Construction

 

The construction method can be used to prepare a HTML INPUT control as a Hosted Payment Field or to create a new field in HTML DIV container. The method signature is as follows:

 

Field(element, options) 

 

The element parameter should be the DOM node of an existing INPUT or DIV tag.

 

The options parameter should be object containing one of more of the following optional properties: 

  • type – string containing the desired field type. 
  • value – string containing the initial value. 
  • placeholder – string containing any placeholder text. 
  • style – string containing any inline CSS styles. 
  • stylesheet – string containing DOM selector for any stylesheets to be used. 
  • disabled – boolean indicating if initially disabled. 
  • required – boolean indicating if the value is required. 
  • readOnly – boolean indicating if initially read only. 
  • validity – boolean or string indicating the initial validity. 
  • locale – string containing the desired locale. 
  • classes – object containing names of extra CSS classes to use. 
  • submitOnEnter – boolean indicating if the enter key should cause the form to submit. 
  • nativeEvents – boolean indicating that native browser events should be fired. 
  • validationMessages – object containing alternative validation messages.
    o required – string containing validation message to use when a value is required.
    o invalid – string containing validation message to use when a value is invalid. 
  • format – string containing select option format for date fields. 
  • minYear – integer containing minimum year (relative to current year) for date fields. 
  • maxYear – integer containing maximum year (relative to current year) for date fields. 

 

Any options parameter will be merged with those provided via meta data supplied using data-hostedfield and/or data-hostedfield-<option> attributes, or via existing attributes or properties of the element or provided via the getDefaultOptions() method of the parent Form.

 

The type option can be used to specify the type of Hosted Payment Field required. It defaults to the value provided by any type attribute on the element (prefixed with the ‘hostedfield:’ namespace). The option cannot be changed once the Field has been created. Valid types are cardDetails, cardNumber, cardCVV, cardExpiryDate, cardStartDate, cardIssueNumber

 

The value option can be used to specify any initial value that should be used by the Field. It defaults to the value provided by any value attribute or property on the element. Obviously, due to the purpose of the Hosted Payment Fields, any initial value is not wise for card number and CVV fields. The option can be changed at runtime by calling the setValue() method.

 

The placeholder option can be used to specify any initial text that should be used as a placeholder by the Field. It defaults to the value provided by any placeholder attribute or property on the element. When used with the CardDetails type Field the placeholder contains three parts separated by a pipe character, the first part contains the cardNumber placeholder, the second part contains the cardExpiry placeholder, and the third part contains the cardCVV placeholder. The option can be changed at runtime by calling the setPlaceholder() method or by altering the options using the jQuery hostedForm() plugin method. 

 

The style option can be used to specify any initial inline CSS style that should be used by the Field. It defaults to the value provided by any style attribute or property on the element. The option can be changed at runtime by calling the setStyle() method or by altering the options using the jQuery hostedForm() plugin method. 

 

The stylesheet option can be used to specify a DOM selector used to locate stylesheets that should be parsed for styles related to this Field. Refer to the section on styling fields. The option can be changed at runtime by calling the setStylesheet() method or by altering the options using the jQuery hostedForm() plugin method. 

 

The disabled option can be used to specify if the Field should be initially disabled. It defaults to the value provided by any disabled attribute or property on the element. The option can be changed at runtime by calling the setDisabled() method or by altering the options using the jQuery hostedForm() plugin method. 

 

The required option can be used to specify if the Field value is required. It defaults to the value provided by any required attribute or property on the element. The option can be changed at runtime by calling the setRequired() method or by altering the options using the jQuery hostedForm() plugin method. 

 

The readOnly option can be used to specify if the Field should be initially read-only. It defaults to the value provided by any readOnly attribute or property on the element. The option can be changed at runtime by calling the setReadOnly() method or by altering the options using the jQuery hostedForm() plugin method.

 

The validity option can be used to specify if the Field should be initially marked as invalid. It defaults to the value provided by any validity property on the element. The option can be changed at runtime by calling the setValidity() method or by altering the options using the jQuery hostedForm() plugin method.

 

The locale option can be used to specify the language that should be used by the Field. It defaults to the value provided by any lang attribute or property on the element or closest ancestor. The option cannot be changed once the Field has been created. 

 

The classes options can be used to specify additional CSS class names to add in addition to the default classes documented in section A-20.3.9. The value is an object whose properties are the default class name and whose values are a string containing the additional class name(s) to use. This option will be merged with any classes option provided to the Form constructor. The option cannot be changed once the Form has been created.

 

The submitOnEnter option can be used to specify if pressing the enter key when typing the Field value should cause the Form to submit. The option defaults to false and cannot be changed once the Field has been created. 

 

The nativeEvents option can be used to specify that any associated native event should be fired when a ‘hostedfield:’ prefixed event is fired. Events are documented in section A-20.3.8. For example, when enabled if the ‘hostedfield:mouseover’ event is fired then the native ‘mouseover’ event is also fired. The option defaults to false and cannot be changed once the Field has been created. 

 

The validationMessages option can be used to specify alternative validation messages that should be displayed when a value is required or invalid. The option defaults to suitable messages depending on the locale and cannot be changed once the Field has been created. 

 

The dropdown option can be used to specify that a cardStartDate or cardExpiryDate Field should be displayed as a pair of select controls to select the month and year, otherwise the month and year are entered via a formatted input box instead. The option defaults to false and cannot be changed once the Field has been created. 

 

The format option can be used in conjunction with the dropdown option to specify the format used to display the month and year in the dropdowns. The month and year parts of the format are separated by a pipe character. The option defaults to ‘N – M | Y’ (eg ‘01 – January | 2020’) and cannot be changed once the Field has been created. 

 

The following formatting characters are understood: 

  • n – month number (no zero prefixing). 
  • N – month number (zero prefixed to two digits when required). 
  • m – short month name (eg Jan, Feb, Mar) 
  • M – long month name (eg January, February, March) 
  • y – two digit year number. 
  • Y – four digit year number. 

 

The minYear and maxYear options can be used in conjunction with the dropdown option to specify the minimum and maximum years that are included in the year dropdown. The option defaults to minus 20 to zero for a cardStartDate Field or zero to plus 20 for a cardExpiryDate Field and cannot be changed once the Field has been created.

 

Example Field construction is as follows: 

  1. var field = new window.hostedFields.classes.Field(document.forms[0].elements[0], { 
  2. // Field type 
  3. type: ‘cardNumber’
  4. // Stylesheet selection 
  5. stylesheets: ‘#hostedfield-stylesheet’
  6. // Additional CSS classes 
  7. classes: { 
  8. invalid: ‘error’ 
  9. }); 

 

Or using meta data on the HTML INPUT element: 

  1. <input type=“hostedfield:cardNumber” data-hostedfields=‘{“stylesheet”:”style.hostedform, style.hostedform-card-number”}},”classes”:{“invalid”:”error”}}’
  2. <script> 
  3. var field = new window.hostedFields.classes.Field(document.forms[0].elements[0]); 
  4. </script> 

 

A-20.3.7 Field Methods

 

The follow methods are made available by the Field class: 

 

promise validate() 

 

Validate the Field value. This will normally be called automatically when the Field loses focus or the form is submitted, or when an invalid value is modified.

 

Returns a promise that will be resolved when the validation is complete.

 

boolean isEmpty()

 Check if the Field has a value. 

Returns true if the field has a value, false otherwise. 

 

boolean isComplete() 

Check if the Field has a complete, but not necessarily valid, value. This is mainly used by compound fields such as cardDetails, cardExpiryDate, cardStartDate, which contain multiple input controls and are deemed complete when all their required input controls have values. 

Returns true if the value is complete, false otherwise. 

 

void setStyle() / string getStyle() 

Set or gets the field’s inline CSS style data. 

Returns void when setting, or a CSS style string when getting. 

 

void setStylesheet(string selector) / string getStylesheet() 

Sets or gets the DOM selector used to select the stylesheet(s) used by the Field. When setting, the stylesheets are parsed and applied to the Field

Returns void when setting, or a DOM selector string when getting. 

 

void setPlaceholder(string text) / string getPlaceholder() 

Sets or gets the placeholder text to be shown when the Field has no value. 

 

When used with the CardDetails type Field the placeholder contains three parts separated by a pipe character, the first part contains the cardNumber placeholder, the second part contains the cardExpiry placeholder, and the third part contains the cardCVV placeholder. 

 

Returns void when setting, or a text string when getting. 

 

void setDisabled(boolean disabled) / string getDisabled() 

Sets or gets the disabled state of the Field. When disabled, the field will be greyed out and not be focusable and thus will not react to any input events. 

 

A disabled Field will have the ‘hf-disabled’ class added otherwise the ‘hf-enabled’ class is added. 

 

Returns void when setting, or a boolean representing the state when getting. 

 

void setRequired(boolean required) / string getRequired() 

Sets or gets the required state of the Field. When required, the field will be invalid if it contains no value or a blank value. 

 

A required Field will have the ‘hf-required’ class added otherwise the ‘hf-optional’ class is added. 

 

Returns void when setting, or a boolean representing the state when getting. 

 

void setReadOnly(boolean read_only) / string getRequired() 

Sets or gets the read-only state of the Field. When read-only, the field will not be focusable and thus will not react to any input events. 

 

A read-only Field will have the ‘hf-readonly’ class added otherwise the ‘hf-readwrite’ class is added. 

 

Returns void when setting, or a boolean representing the state when getting. 

 

void setFocused(boolean focused) 

Moves the browser’s focus to the Field. When focused, the field will react input events. 

 

A focused Field will have the ‘hf-focus’ class added otherwise the ‘hf-blur’ class is added. 

 

Returns void when setting, or a boolean representing the state when getting. 

 

void setValidity(string validity) / string getValidity() 

Sets or gets the validity of the Field. When valid, the validity will be true or a blank string. When invalid, the validity will be an error message explaining the reason the value is invalid. 

 

When used with the CardDetails type Field the error message contains three parts separated by a pipe character, the first part contains the cardNumber value, the second part contains the cardExpiry value, and the third part contains the cardCVV value. 

 

A valid Field will have the ‘hf-valid’ and ‘hf-user-valid’ classes added otherwise the ‘hf-invalid’ and ‘hf-user-invalid’ classes are added. 

 

Returns void when setting, or an error message string when getting. 

 

void setValue() / string getValue() 

Set or get the Field value. Because Hosted Payment Fields are designed for the entry of sensitive payment details, then these methods are not normally used. There is no means to retrieve the actual sensitive data and so any returned value will be an empty string if the field has no value or a single asterisk if the field has a value. 

 

When used with the CardDetails type Field the value contains three parts separated by a pipe character, the first part contains the cardNumber value, the second part contains the cardExpiry value, and the third part contains the cardCVV value. 

 

Returns void when setting, or a mask string when getting. 

 

void getState() 

Get the current state of the Field as an object with the following boolean properties: 

  • isReady – the Field has been created, initialised and is ready for use. 
  • isValid – the value is valid (refer to the setValidity() method). 
  • isEmpty – the value is empty (refer to the isEmpty() method). 
  • isComplete – the value is complete (refer to the isComplete() method). 
  • isDisabled – the value is complete (refer to the setDisabled() method). 
  • isRequired – the value is complete (refer to the setRequired() method). 
  • isReadOnly – the value is complete (refer to the setReadOnly() method). 

 

Returns an object containing the states. 

 

void reset() 

Reset Field value back to the initial value. 

 

void destroy() 

Destroys the Form, reverting its element back to its original state. 

 

Note: A field’s options or properties cannot be changed while a field is initialising, that is between construction and firing of the ‘ready’ event. Attempts to change field options or properties before this will be ignored.

 

A-20.3.8 Field Events 

The following events may be fired by the Field object, and you can use these to hook into and modify the object’s behaviour:

Event Name 1
create
Description
Fired when a Field has been created.
Event Name 1
destroy
Description
Fired when a Field has been destroyed.
Event Name 1
ready
Description
Fired when a Field style is has finished initialising and is ready.
Event Name 1
style
Description
Fired when a Field style is changed.
Event Name 1
autofill
Description
Fired when a Field has a value auto filled by the browser.
Event Name 1
autofillcancel
Description
Fired when a Field has an auto filled value removed.
Event Name 1
valid
Description
Fired when a Field is checked for validity and passes the check.
Event Name 1
invalid
Description
Fired when a Field is checked for validity and fails the check.
Event Name 1
uservalid
Description
Fired when the valid event is fired but only after user interaction has occurred, such as focusing a Field, leaving a Field or attempting to submit a Form.
Event Name 1
userinvalid
Description
Fired when the invalid event is fired but only after user interaction has occurred, such as focusing a Field, leaving a Field or attempting to submit a Form.
Event Name 1
disabled
Description
Fired when a Field changes to disabled.
Event Name 1
enabled
Description
Fired when a Field changes from disabled.
Event Name 1
required
Description
Fired when a Field changes to required.
Event Name 1
optional
Description
Fired when a Field changes from required.
Event Name 1
readonly
Description
Fired when a Field changes to read-only.
Event Name 1
readwrite
Description
Fired when a Field changed from read-only.
Event Name 1
focus
Description
Fired when a Field receives focus.
Event Name 1
blur
Description
Fired when a Field loses focus.
Event Name 1
mouseenter
Description
Fired when a pointing device is moved into the Field.
Event Name 1
mouseleave
Description
Fired when a pointing device is moved out of the Field.
Event Name 1
mouseover
Description
Fired when a pointing device is moved into the Field.
Event Name 1
mouseout
Description
Fired when a pointing device is moved out of the Field.
Event Name 1
mousemove
Description
Fired when a pointing device is moved over the Field.
Event Name 1
keydown
Description
Fired when a key is pressed in the Field.
Event Name 1
keyup
Description
Fired when a key is released in a Field.
Event Name 1
keypress
Description
Fired when a key except Shift, Fn, CapsLock is in a pressed position in a Field.
Event Name 1
change
Description
Fired when an alteration to the value of a Field is committed by the user.
Event Name 1
input
Description
Fired when the value of a Field is changed.
1 Event names are prefixed with the ‘hostedfield:’ namespace not shown in the table.  

 

A-20.3.9 Field CSS Classes 

The following CSS class names will be added to a Field object depending on its state and you can use these to style the object as required:

Event Name
hostedfield
Description
Present on all Field elements.
Event Name
hf-autofill
Description
Present when the value was auto filled by the browser.
Event Name
hf-invalid
Description
Present when in the invalid state.
Event Name
hf-valid
Description
Present when in the valid state.
Event Name
hf-user-invalid
Description
Present when in the invalid state and user interaction has occurred, such as focusing a Field, leaving a Field or attempting to submit a Form.
Event Name
hf-user-valid
Description
Present when in the valid state and user interaction has occurred, such as focusing a Field, leaving a Field or attempting to submit a Form.
Event Name
hf-disabled
Description
Present when in the disabled state.
Event Name
hf-enabled
Description
Present when not in the disabled state.
Event Name
hf-required
Description
Present when in the required state.
Event Name
hf-optional
Description
Present when not in the required state.
Event Name
hf-readonly
Description
Present when in the read-only state.
Event Name
hf-readwrite
Description
Present when not in the read-only state.
Event Name
hf-focus
Description
Present when in the focused state.
Event Name
hf-blur
Description
Present when not in the focused state.
Event Name
hf-empty
Description
Present when in the empty state.
Event Name
hf-complete
Description
Present when in the complete state.
Event Name
hf-hover
Description
Present when a pointing device is over the Field.
Event Name
hf-placeholder-shown
Description
Present when the placeholder text is displayed.

In addition to these class names, the Field will add any corresponding class names provided by the classes option provided when the Field is constructed. 

 

For example, if the Field is constructed with a classes option as follows ‘{disabled: ‘text-blur text-grey’, enabled: ‘text-normal’}’, then the ‘text-blur’ and ‘text-grey’ class names will be present whenever the ‘hf-disabled’ class is present and the ‘text-normal’ class name will be present whenever the ‘hf-enabled’ class name is present.

 

A-20.3.10 Field Styling

 

The Hosted Payment Fields are styled using CSS as normal. 

 

However, styles have to be transferred from your website to the controls served from our website, therefore styles must be isolated and easily identifiable. To aid with identification, all styles intended for a Field must contain the ‘hostedfield’ class name in their selector or ‘-hostedfield’ extension on any id in the selector.

 

As a website may contain lots of stylesheets, a Field cannot be expected to parse every stylesheet present on the page and therefore it only parses those selected using the stylesheets construction option or using the setStylesheet() method. By default, this is any stylesheet referenced via a <link> tag or <style> tag with the ‘hostedfield’ class name: ie any HTML node that matches the following DOM selector ‘link.hostedfield[rel=stylesheet], style.hostedfield’.

 

CSS styles using the Field state classes, pseudo classes and pseudo elements are supported as follows: 

 

  • :focus 
  • .hf-focus 
  • :hover 
  • .hf-hover 
  • :enabled 
  • .hf-enabled 
  • :disabled 
  • .hf-disabled 
  • :valid 
  • .hf-valid 
  • :invalid 
  • .hf-invalid 
  • :user-valid 
  • .hf-user-valid 
  • :user-invalid 
  • .hf-user-invalid 
  • :required 
  • .hf-required 
  • :optional 
  • .hf-optional 
  • :empty 
  • .hf-empty 
  • :complete 
  • .hf-complete 
  • :autofill 
  • .hf-autofill 
  • :placeholder-shown 
  • .hf-placeholder-shown 
  • :readonly 
  • .hf-readonly 
  • :readwrite 
  • .hf-readwrite 
  • :-webkit-auto-fill 
  • .hf-icon 
  • ::placeholder 
  • ::-moz-placeholder 
  • ::-webkit-input-placeholder 
  • ::-ms-input-placeholder 

The styles can contain any valid CSS rules and will be used to style both the public elements and internal private elements. For security only, styles that relate to the textual representation of the Field are passed to the internal private elements. This includes styles such as colours, font weights and text decorations. At present, it is not possible to specify custom fonts as they would require the font files to be available on our servers. 

The following styles can be used to style the Field internal private elements: 

  • caret-color 
  • color 
  • cursor 
  • direction 
  • fill 
  • filter 
  • font 
  • font-family 
  • font-feature-settings 
  • font-kerning 
  • font-language-override 
  • font-size 
  • font-size-adjust 
  • font-smooth 
  • font-stretch 
  • font-style 
  • font-synthesis 
  • font-variant 
  • font-variant-alternates 
  • font-variant-caps 
  • font-variant-east-asian 
  • font-variant-ligatures 
  • font-variant-numeric 
  • font-variant-position 
  • font-weight 
  • letter-spacing 
  • line-height 
  • stroke 
  • text-align 
  • text-decoration 
  • text-decoration-color 
  • text-decoration-line 
  • text-decoration-style
  • text-emphasis 
  • text-emphasis-color 
  • text-emphasis-position 
  • text-emphasis-style 
  • text-indent 
  • text-rendering 
  • text-shadow 
  • text-transform 
  • text-underline-position 
  • -moz-osx-font-smoothing 
  • -webkit-font-smoothing 
  • -webkit-text-fill-color 

 

The ‘.hf-icon’ class name can be used to target the icon sub element in a cardDetails Field

 

Individual controls can be targeted by using DOM ids, which will have a ‘-hostedfield’ extension added to the DOM id of the original element

 

It is advisable to keep CSS selectors and rules as simple as possible to avoid styling errors caused by a failure to parse and filter the rules.

 

The following list are the best web safe fonts for use with any ‘font’ or ‘font-family’ style as these fonts should be available on most web browsers: 

  • Arial (sans-serif) 
  • Verdana (sans-serif) 
  • Helvetica (sans-serif) 
  • Tahoma (sans-serif) 
  • Trebuchet MS (sans-serif) 
  • Times New Roman (serif) 
  • Georgia (serif) 
  • Garamond (serif) 
  • Courier New (monospace) 
  • Brush Script MT (cursive)

 

Example stylesheet: 

  1. <style class=“hostedfield”
  2. /* 
  3. * Style hosted field internals 
  4. * – only accept font, foreground and background styling 
  5. */ 
  6. /* Copy of Bootstrap styles */ 
  7. .hostedfield:disabled { 
  8. cursor: not-allowed; 
  9. background-color: #eee; 
  10. opacity: 1; 
  11. /* Change text to red when invalid */ 
  12. .form-control:invalid, 
  13. .hostedfield:invalid { 
  14. border-color: #a94442 !important; 
  15. color: #a94442 !important; 
  16. /* Change text to light grey when readonly */ 
  17. .form-control:readonly, 
  18. .hostedfield:readonly { 
  19. color: lightgrey !important; 
  20. /* Emulate webkit auto fill style */ 
  21. .form-control.hf-autofill, 
  22. .hostedfield.hf-autofill { 
  23. background-color: rgb(250, 255, 189) !important; 
  24. background-image: none !important; 
  25. color: rgb(0, 0, 0) !important; 
  26. /* Add pink placeholder */ 
  27. .form-control::placeholder, 
  28. .hostedfield::placeholder { 
  29. color: pink; 
  30. /* Show hovering over the control */ 
  31. .form-control.hf-hover, 
  32. .hostedfield.hf-hover { 
  33. font-style: italic; 
  34. /* Style by id (hosted field will have ‘-hostedfield’ appended to the id) */ 
  35. #form1-card-details.hostedfield, #form1-card-details-hostedfield { 
  36. color: blue; 
  37. </style> 

 

A-20.3.11 jQuery Plugin 

 

The script will extend the jQuery object with its own plugin methods to allow easy access to Form and Field objects attached to an element as follows:

 

$(element).hostedForm(options); 

$(element).hostedForm(‘instance’); 

$(element).hostedForm(‘options’, options); 

$(element).hostedForm(method, parameters); 

$(element).hostedForm(‘destroy’);

 

$(element).hostedField(options); 

$(element).hostedField(‘instance’); 

$(element).hostedField(‘options’, options); 

$(element).hostedField(method, parameters); 

$(element).hostedField(‘destroy’); 

 

The script will also add a ‘:hostedfield’ pseudo selector allowing Field elements to be selected using the following example notation: 

 

$(‘INPUT:hostedfield’) 

Integrated Payments - connecting your till to your terminal

Integrated payments - connecting your EPOS till to your card terminal - enables your business to process payments faster and increase your profits.

There are many benefits to an integrated solution for almost all business types, most importantly, the removal of human error, giving you accurate reporting from all tills and terminals.

At Swipen, we offer Integrated Payments free of charge and you can use our Pay at Table or Pay at Counter software, or both if it suits your business:

Pay at Table

A software design with restaurants in mind:

Split the bill at the table

Automatic table closing

Integrated gratuity & reporting

Turn tables faster

More efficient payment

Pay at Counter

Suitable for most businesses, offering:

Faster payments

Shorter queues

Better conversion

Greater profits

COVID secure

Discover which terminal type is best for your business

Portable

Restaurants

Pubs

Cafes

Countertop

Bars

Clubs

Takeaways

Retail & Shops

Take your payments to the next level

E-Commerce Payment Solutions

With the arrival of Covid-19 into all our lives, online only payments are looking to have a bright future that’s here to stay.

At Swipen, we want to bust the myth that taking payments online is complicated, and help you
adapt to this changing world.

We offer two types of E-Commerce payment solution either directly integrated with your website or a hosted payment page.

Directly Integrated

Integrated into your own website

Completely customisable

Branded to your business

Customers stay on your website

150 currencies supported

Shopping carts

No long-term contract

Alternative payment methods, including: Alipay, Apple Pay, Google Pay, WeChatPay

Hosted Payment Page

Easy to set up

Take payments in minutes

Swipen branded

Data processed by Swipen

150 currencies supported

Shopping carts

No long-term contract

Alternative payment methods, including: Alipay, Apple Pay, Google Pay, WeChatPay

Take your payments to the next level

Virtual Terminal - Taking Payments over the Phone

Many businesses find it useful to take payments over the phone, whether you’re a travel agent
needing to take deposits, a mobile tradesperson, travelling salesperson, you have a call centre, or you don’t have a website to take payments online.

Swipen’s Virtual Terminal allows you to take card payments over the phone quickly and securely.

Our solution is a web portal that can be used on a desktop, tablet or mobile device.

Virtual Terminal Key Features

More secure than a card terminal - Completing the payment over the phone with full customer details reduces the risk of chargebacks or fraud.

Pay By Link - Send a payment link to complete the purchase or pay a balance. This is also a useful feature for customers who prefer to not give their details over the phone.

Capture Customer Details - The Virtual Terminal allows you to capture all the customer details you will need for your CRM or Booking Systems reducing the need for double inputting.

Control Permissions - Restrict user access to only certain functionality so you can control what your staff can process and see.

Take Payments anywhere - The Virtual Terminal is compatible to all devices and allows you to take payments from anywhere - office, home or on the move in a safe and secure way.

Ideal for call centres, travel agents, travelling salespeople, mobile tradespeople, restaurants for pre-bookings and parties, hotels for rooms and events, or any business that doesn’t have a website that customers can pay through.

Take your payments to the next level

Web & App Solutions - Order and Pay-at-Table Platform

With COVID regulations in force across the country, restaurants and pubs are adjusting the way they work to reduce the spread of this virus.

Swipen are also adapting to these changing times, and working with our expert partners, we can now offer order and pay-at-table platforms, allowing you to benefit from cashless and cardless payment options.

Our solutions can be either Web or App based and we provide the choice between
a ‘Simple Solution’ and a ‘Bespoke Solution’, depending on the size of your business

Bespoke Solution

The best option for individual pubs and restaurants, small chains, or if location offers a different menu:

Use your own branding

At table QR code or WiFi login

Bespoke rates and fees

Links to your EPOS till *

*Depending on the EPOS company

Simple Solution

Ideal for larger chains where every location requires exactly the same functionality and offers the same menu:

Custom built to fit your business

Customers can access the way you want

Links to both your till and kitchen

No training required

Working with Pizza Hut

Swipen have helped create a bespoke value-for money solution for Pizza Hut, and we could do the same for you.

Get in contact to find out more.

Take your payments to the next level

Tip Per Tap -Contactless Tipping System

With the dawn of cashless and touchless checkouts along with app ordering systems and pay online methods, many restaurants, bars, cafés and hotels are finding that their waiting staff are no longer able to receive cash or card tips.

Swipen has the perfect solution: the new ‘Tip Per Tap’ Contactless Tipping System

Directly Integrated

A dedicated terminal is placed in a prominent location in your restaurant.

The terminal is set to ‘donation’ and the debit amount is set at a specific figure. e.g. £2

Your happy customers simply tap their card, phone or watch against the terminal to leave a £2 tip.

They can tap multiple times to leave a larger amount

Works automatically without the need for a member of staff to supervise.

End-of-day report is separate, making it quicker and easier to share the total tips received between staff members.

How about a little Tip Per Tap

Read our blog all about our new Tip Per Tap Contactless Tipping System.

Get in contact to find out more.

Take your payments to the next level