What are Hosted Fields?
DNA Payments Hosted Fields solution allows merchants to be eligible for the simpliest level of PCI compliance (SAQ A) whilst maintaining control over the look and feel of the checkout process. The sensitive data fields, such as PAN, CSC etc. are hosted on the DNA Payments platform but located and styled on the page by the merchant.
To utilise the Hosted Fields integration method, there are four main tasks that need to be completed:
- Include the DNA Payments hosted fields SDK
- Obtain the authorization token
- Create Hosted Fields UI markup
- Use Hosted Fields API to process the transaction
To assist the development process DNA Payments have created the following page. On this page it is possible to see the solution in action, make changes to formats and styles and even perform test transactions.
Include the DNA Payments Hosted Fields SDK
Add the following code in the head part of your webpage (this URL is subject to change). The URL is a script for creating Hosted Fields on your webpage.
Obtain the Authorization Token
Authentication follows the same process for all our online tools. Details of this process can be found in our Checkout Integration Guide
You should use the
payment integration_seamless for this request.
Ensure that you have the endpoint for obtaining the authorization token. The authentication must take place before calling any of the Hosted Fields functions. The object returned will be in the following format:
The key field in this object is the
access_token is used in the transaction request.
Add the Hosted Fields UI Markup
The look and feel of the Payment Form will need to be set to fit best with the website that it is located on. In this form you provide HTML container elements for payment fields and Three D secure form. In these container elements, the Hosted Fields iFrame will be rendered.
In the test example in codepen site, we use boostrap to style the form. Here is an example code snippet for the
cardholderName payment field:
The following snippet code shows how we set container HTML elements in variables to use in Hosted Fields API in the codepen example.
Hosted Fields API
After the including DNA Payments hosted fields SDK, access is available to the global object
window.dnaPayments.hostedFields. It has an asynchronous create method which return Hosted Fields instance. The create method accepts an object as argument with the following fields:
|Field Name||State||Data Type||Description|
|isTest||Optional||Boolean||Default: false. Governs which endpoints (test or live) are used to process.|
|accessToken||Mandatory||String||The access_token field returned during the authentication process.|
|styles||Optional||Object||The styles you want to give payment field inputs which will be rendered in Iframes.|
|threeDSecure||Mandatory||Object||An object with container property, whose value must be HTML element in which the 3D Secure iFrame will be rendered.|
|fields||Mandatory||Object||Object containing the below payment fields:|
The following code snippet shows how to use create method:
As mentioned previously, the create method returns Hosted fields instance. This is an object containing the following methods:
|on(event, handler)||Subscribes a handler function to a named event. The following events are available:|
The properties of state object are:
|submit(data)||Submits payment data to trigger payment. Below shows an example using submit method. You can read about Payment Data in detail at this link https://developer.dnapayments.com/payment-page#4321-payment-request|
|clear()||Clears all payment field input values and their current states.|
|destroy()||Removes all inserted Hosted Fields iFrames and unsubscribes all event handlers.|
|getState()||Returns the current state object with the following properties:|
Errors in detail
|Errors that can occur when creating the Hosted Fields.|
|HOSTED_FIELDS_TIMEOUT||Hosted Fields timed out when attempting to set up.|
|THREE_D_SECURE_TIMEOUT||ThreeDSecure timed out.|
|DUPLICATE_FIELD||fieldKey field is already initialized.|
|NOT_ALLOWED_FIELD||fieldKey field is NOT an allowed hosted field.|
|MISSING_REQUIRED_FIELD||fieldKey required field is NOT provided.|
|CLIENT_INITIALIZE_ERROR||Could not initialize the Client object. Maybe an invalid accessToken.|
|Errors that can occur when submitting the Payment Data.|
|INVALID_CARD_DATA||Invalid card data.|
|THREE_D_SECURE_ERROR||3D Secure error.|