SecureFields JS is a hosted field (payment, PII) solution that helps developers provide additional security to a merchant’s website. They are plug-in fields in your platform's "end-user" interface that provide an easy way to securely implement data collection without needing to pass through your systems. SecureFields JS fields are customizable, secure, input elements. When a user enters secure data in these fields, the data is converted into a token/s. The token/s can be used to send the sensitive data to the specified destination.
If you are looking for specific commands or options, please see the reference to the developer API specs provided from within your partner portal
Advantages of using SecureFields JS
Instantly create customized forms that adhere to PCI and other PII requirements. Our servers intercept the sensitive data before it hits your servers and replaces it with aliased version, while securing the original data in our vault.
The following example shows a rendered payments form using the SecureFields JS to serve the card holder name, card number, expiration date and CVV fields.
Before you begin
You will need your public and private keys from your partner console account.
Implementing SecureField JS
1. Add SecureFields JS to your checkout page
There are two ways to load SecureFields JS
a. Option #1 - To add SecureFields JS to your checkout page, include our JavaScript library in your host page:
b. Option #2 - Alternatively, to load only the SecureField JS library without the web components, include the following JavaScript library in your host page:
This will create a very simple (and unstyled) payment form. However, the payment form will not yet contain the fields nor will it be functional. It must first be configured before it can successfully tokenize your payment methods.
Important:
For credit card form, the field ids must match exactly the pre-defined field ids by our system in order for us to tokenize the appropriate data. card-name, card-number, card-expiry, card-cvc
For general PII data any IDs can be utilized.
2. Initialization
Once the host form is on the page, the fields are initialized with the SecureFields JS module.
Place the below snippet in a new script tag on the bottom of your checkout page, swapping out the example environment key with your own:
Note:
Note
If the merchant enters the credit card information, set the parameter manuallyEntered to true. And on the other hand, if you enter the credit card information, set the parameter manuallyEntered to false
To link the created card to a specific merchant, pass the corresponding PayEngine merchant_id in the merchant_id parameter. The card will then be restricted to that merchant's use only.
Capturing cardholder's billing address fields
There are two ways to capture address fields and send to PayEngine
Capture address fields within the secure fields
Capture address fields outside of the secure fields, in your own form and pass these address fields via createCard
2a. Capture address fields within the secure fields
Following sections are only applicable if you're tokenizing card data for payments. For general PII information, please refer to Using tokens .
3. Tokenize payment details
Depending on your account configuration, your tokenized card info can be made available as global or merchant specific.
Note from the example code above that SecureFields JS doesn’t automatically hook into any form events. Instead, you must explicitly tell it when you want to send the collected card data for tokenization.
As shown in the example above, the most straightforward approach is to create a form onSubmit handler or an element eventListener that serves as a trigger to delegate to SecureFields JS createCard() method. This method will in turn return the tokenized card object that you can safely store within your system.
4. Executing an auth transaction
After the SecureFields JS tokenizes your payment method, it is up to you to execute the actual transaction from your backend server environment. This is necessary because the browser is not a secure environment and should never contain your access secret (which is required to invoke the transactional portion of our API).
When the checkout form is submitted, extract the token parameter and use it to execute an auth and capture using the direct APIs:
The above call will authorize a payment method to be charged a specific amount and return an authorization id. No funds are taken with an auth – a follow-up capture transaction is required to actually move the funds.
5. Executing a capture transaction
To capture the amount, you must next call the capture API endpoint
Listen to events that's related to the whole form state
Parameter
Type
Description
event
string
Event type. Supported events are readyand enterPress
callback
function
A function to execute each time the event is triggered
function onEnterPress() {
// submit form
}
form.on("ready", function() {
// hide loading state
});
form.on("enterPress", onEnterPress);
form.off(event, callback)
Unsubscribe from the form event listeners
Parameter
Type
Description
event
string
Event type. Supported events are readyand enterPress
callback
function
A function to execute each time the event is triggered
form.off("enterPress", onEnterPress);
form.reset()
Reset the form state and its values
form.reset()
Cardholder's address fields - address_line1 , address_line2 , address_state, address_country , address_zip if you are planning to capture address fields as part of secure fields.
But these fields can be captured outside of secure fields too and in that case, these fields should not be included in the above form. Refer to this on more details
Visa 3D Secure Update: Action Required
Partners must collect cardholder's mobile number OR email address during payment processing by January 20, 2025. Update existing tokens with this information before use (refer step 3 below for tokenizing payment details)
See for details. Contact PayEngine support with any questions you have.
When automatic is activated on your account, any PAN data associated with it will automatically use a token provided by the card brand network.
