Payment-method icon

Standalone Secured Fields

Learn how to collect a shopper's payment details on your own payment form.

We have replaced Secured Fields with the new Custom Card Web Component. We still support Secured Fields, but we only release new functionality for the Custom Card Component. You must implement the Custom Card Component to be compliant with co-badged card regulations.

If you currently use Secured Fields, we strongly recommend that you implement our Custom Card Web Component instead.

Before you can make a payment with our API integration, you need to collect any required payment details from your shopper. Here we describe how to do this by building your own payment form.

Building your own form gives you full control over the look and feel of your checkout. If you'd rather not build your own payment form, you can also collect the shopper's payment details using our pre-built JavaScript Components or with the Drop-in. These are available for many popular payment methods.

This guide assumes that you've already completed Step 1 of our API integration guide, and have presented a list of payment methods to the shopper.

To collect payment details from the shopper, your payment form can be either:

  • Hard-coded: After making a /paymentMethods call to determine the payment details you need to collect, you build a static form that collects them from the shopper.

    A hard-coded form is quicker to implement, but the payment details you need to collect from a shopper can change. You should regularly poll the  /paymentMethods endpoint to check for any updates to required payment details. We recommend this approach if you're only working with a small number of payment methods or countries.

  • Dynamically generated: For each transaction, you make a /paymentMethods call to determine the payment details you need to collect. Then use the response to generate a form that collects them from the shopper.

    This takes more time to implement, but ensures that the required payment details you collect from the shopper are up-to-date.

After you decide which form you will build, follow the steps below to:

  1. Determine which shopper details you need to collect in your form. These are different for each payment method.
  2. Integrate Secured Fields. Secured Fields is our JavaScript library that you can use to collect and encrypt sensitive credit card details.

Step 1: Determine required shopper details

To determine what payment details you need to collect from the shopper:

  1. Make  /paymentMethods call, providing:

    • countryCode: The shopper's country.
    • amount: The currency and value of the payment. 

    A list of available paymentMethods will be returned in the response. Most of these will have a details array. 

    {
      "paymentMethods":[
        {
          "details":[{
              "key":"encryptedCardNumber",
              "type":"cardToken"
            },{
              "key":"encryptedExpiryMonth",
              "type":"cardToken"
            },{
              "key":"encryptedExpiryYear",
              "type":"cardToken"
            },{
              "key":"encryptedSecurityCode",
              "type":"cardToken"
            }
          ],
          "name":"Credit Card",
          "type":"scheme"
        },{
          "details":[{
              "key":"sepa.ownerName",
              "type":"text"
            },{
              "key":"sepa.ibanNumber",
              "type":"text"
            }
          ],
          "name":"SEPA Direct Debit",
          "type":"sepadirectdebit"
        },
        ...
      ]
    }
  2. Use the details array of each payment method to determine what you need to collect from the shopper:

    • key: Shopper detail you need to collect using your payments form.
    • type: Input type for collecting the payment detail from the shopper:

      Type Description
      cardToken Value that represents encrypted card data. Generate these values using our Secured Fields JavaScript library.
      emailAddress Email address.
      radio Radio buttons displaying the options specified within the items array.
      select A list displaying the options specified within the items array. Present each name in this array to the shopper.
      tel Telephone number.
      text Generic string.

    If a payment method does not have a details array, you do not need to collect any shopper details in your form.

    In the example below, for SEPA Direct Debit, you'd use text fields to collect:

    • sepa.ownerName: Name on the shopper's bank account.

    • sepa.ibanNumber: IBAN number of this account.

Step 2: Collect shopper details with Secured Fields

Secured Fields is our JavaScript library that you can use to securely collect and encrypt your shopper's credit card details.

When the shopper enters their card details on your website, Secured Fields collects the sensitive data, and creates an encrypted version that you can safely transmit when you make the payment.

If you are fully PCI compliant you can alternatively collect and submit raw card data. See Collecting raw card data for more information.

To integrate Secured Fields in your payment form:

  1. Include the following script in the <head> of your payments page:

    <script type="text/javascript" src="https://checkoutshopper-test.adyen.com/checkoutshopper/assets/js/sdk/checkoutSecuredFields.1.5.0.min.js"></script>

    This will embed the Secured Fields library.

  2. Insert a <div> in the <body> of your payments page, with the following data-cse elements:

    • encryptedCardNumber: Card number.

    • For card expiration:

      • Collect as separate fields:

        • encryptedExpiryMonth: Card expiry month.

        • encryptedExpiryYear: Card expiry year.

      • Collect as a single field:

        • encryptedExpiryDate: Card expiry for both month and year.
    • encryptedSecurityCode: Card security code.

    <div class="cards-div">
    
        <div class="js-chckt-pm__pm-holder">
           <input type="hidden" name="txvariant" value="card" />
           <label>
               <span class="input-field" data-cse="encryptedCardNumber" />
           </label>
           <label>
               <span class="input-field" data-cse="encryptedExpiryMonth" />
           </label>
           <label>
               <span class="input-field" data-cse="encryptedExpiryYear" />
           </label>
           <label>
               <span class="input-field" data-cse="encryptedSecurityCode" />
           </label>
        </div>
    </div>

    These will render as iframes, where the shopper can securely enter their card details. 

  3. Add the following code to the bottom of the  <body>, specifying:

    <script type="text/javascript">
       var csfSetupObj = {
          rootNode: '.cards-div',
          configObject : {
            clientKey : "YOUR_CLIENT_KEY"
            }
       };
       var securedFields = csf(csfSetupObj);
      </script>

    You can also include additional configuration properties. For more information, see Configuring Secured Fields.

  4. When the shopper enters their card details, Secured Fields will perform validation on the card details. When the shopper submits the payment, their card details are replaced by encrypted values. These are added to hidden <input> fields in the <div> that holds the data-cse elements. 

    <div id="pmHolder" class="js-chckt-pm__pm-holder">
        <input type="hidden" name="txvariant" value="card">
        ...
        <input type="hidden" name="encryptedExpiryMonth" id="card-encrypted-month" value="adyenjs_0_1_18$MT6ppy0FAMVMLH...">
        ...
    </div>
  5. Loop through and collect the encrypted card details from the corresponding data-cse values. You'll use these to make the payment.

Configuring Secured Fields

Aside from the basic configuration to allow Secure Fields to collect and encrypt shopper information, you can also add styles and use callbacks.

  • Callbacks: Implement additional logic such as displaying error messages when onError is invoked.
  • Styling: Style your input fields.
  • Configuration: Modify default configuration for card brand recognition and for allowing DOM access.

The following is a sample Secured Fields code with styles and additional configuration properties. If you want to know more about styles and config options, check out the links in the list above.


    // Define style object
    var styleObject = {
      base: {
        color: 'black',
        fontSize: '16px',
        fontSmoothing: 'antialiased',
        fontFamily: 'Helvetica'
      },
      error: {
        color: 'red'
      },
      placeholder: {
        color: '#d8d8d8'
      },
      validated: {
        color: 'green'
      }
    }
    // Load the Secured Fields

    var securedFields = csf({
      configObject : {
        clientKey : "[RETRIEVE FROM CUSTOMER AREA]",
        cardGroupTypes: ['maestro','visa','amex'] // OPTIONAL
      },
      allowedDOMAccess: false,
      rootNode: '.cards-div',
      paymentMethods : {
        card : {
          sfStyles : styleObject,
          placeholders: {
            encryptedCardNumber : '4111 1111 1111 1111',
            encryptedExpiryDate : '08/18',
            encryptedSecurityCode : '737'
          }
        }
      }
    });

Secured Fields callbacks

Implement callbacks to handle events when using Secured Fields. Use these to customize your shopper's experience when specific events occur.

onAllValid

This callback is invoked when all secured fields have been filled, validated and encrypted.

securedFields.onAllValid ( function(allValidObject){
});

When this callback is invoked in version 1.2.0 and later, the allValidObject includes a parameter allValid set to true and a type parameter that returns the payment method type, for example card. In lower versions, txVariant is used instead of type

Version 1.2.0 and later:

allValidObject = {allValid : true, type : 'card'}

Version 1.1.4:

allValidObject = {allValid : true, txVariant : 'card'}

A field can become invalid after originally validating, for example if a value is changed. If so, the callback is invoked with allValid set to false.

onBinValue

This callback is supported from version 1.3.1 and later. To migrate to version 1.3.1, see Migrating to 1.3.0 and later.

This callback is invoked when a shopper types the BIN (first 6 digits) in the credit card number field.

securedFields.onBinValue ( function(valueObject){
});

Example valueObject:

{
  "binValue": "411111",
  "txVariant": "card"
}

onBrand

This callback is invoked when the card brand has been identified.  To use this callback for all your supported card brands, configure card types in the cardGroupTypes property.

securedFields.onBrand ( function(brandObject){
});

Example brandObject:

{
  "brandImage": "visa@2x.png",
  "brand": "visa",
  "brandText": "CVV",
  "markerNode": div#pmHolder.js-chckt-pm__pm-holder,// Ref to HTML node for this payment method
}

onConfigSuccess

This callback is invoked when all the loaded iframes have run their setup code and are ready to be used.

If onConfigSuccess doesn't follow onLoad  promptly then something has gone wrong.

securedFields.onConfigSuccess ( function(configSuccessObject){
});

When this callback is invoked, the configSuccessObject includes a parameter iframesConfigured set to true.

onError

This callback is invoked when a shopper triggers an error. For example, an invalid card number, invalid expiry date, or incomplete field.

securedFields.onError ( function(errorObject){
});

Example errorObject

{
  "markerNode": div#pmHolder.js-chckt-pm__pm-holder,// Ref to HTML node for this payment method,
  "fieldType": "encryptedExpiryDate",
  "error": "validateExpiryDate: card too old"
}

If multiple errors occur, you will receive separate onError callbacks with a different value for error.

If no error occurred, the callback is invoked with an empty string as the value of error:

{
  "markerNode": div#pmHolder.js-chckt-pm__pm-holder,// Ref to HTML node for this payment method,
  "fieldType": "encryptedExpiryDate",
  "error": ""
}

onFieldValid

This callback is invoked as a specific field is validated and encrypted.

securedFields.onFieldValid (function(fieldObject){
});

The endDigits property is included for type:encryptedCardNumber from version 1.5.2 and later:

{
   "blob":adyenjs_0_1_22$IGaNbdJNru...,
   "encryptedFieldName":"encryptedCardNumber",
   "fieldType":"encryptedCardNumber",
   "uid":"card-encrypted-encryptedCardNumber",
   "valid":true,
   "txVariant":"card",
   "endDigits":1111,
   "markerNode":div#pmHolder.js-chckt-pm__pm-holder,
   "type":"encryptedCardNumber"
}

Examples of passing an encrypted expiry month in a fieldObject:

Version 1.3.0 and later:

{
   "blob":adyenjs_0_1_22$IGaNbdJNru...,
   "encryptedFieldName":"encryptedExpiryMonth",
   "fieldType":"encryptedExpiryDate",
   "uid":card-encrypted-month,
   "valid":true,
   "txVariant":"card",
   "markerNode":div#pmHolder.js-chckt-pm__pm-holder,
   "type":"month"
}

Versions 1.2.0 and 1.2.1:

{
   "blob":adyenjs_0_1_22$IGaNbdJNru...,
   "encryptedFieldName":"encryptedExpiryMonth",
   "fieldType":"encryptedExpiryDate",
   "uid":card-encrypted-month,
   "valid":true,
   "type":"card",
   "markerNode":div#pmHolder.js-chckt-pm__pm-holder,
   "originalFieldType":"month"
}

Version 1.1.4:

{
  "singleField": true,
  "fieldType": "hostedExpiryDateField",
  "status": "valid",
  "type": "card",
  "markerNode": :div#pmHolder.js-chckt-pm__pm-holder,
  "originalFieldType": "month"
}

A field can become invalid after originally validating, for example if a shopper changes the input to an invalid value. If so, the valid parameter of the fieldObject is set to false in version 1.2.0 and later. In lower versions, the status parameter is set to invalid.

Example fieldObject when a field becomes invalid:

Version 1.3.0 and later:

{
   "blob":adyenjs_0_1_22$IGaNbdJNru...,
   "encryptedFieldName":"encryptedExpiryMonth",
   "fieldType":"encryptedExpiryDate",
   "uid":card-encrypted-month,
   "valid":false,
   "txVariant":"card",
   "markerNode":div#pmHolder.js-chckt-pm__pm-holder,
   "type":"month"
}

Versions 1.2.0 and 1.2.1:

{
   "blob":adyenjs_0_1_22$IGaNbdJNru...,
   "encryptedFieldName":"encryptedExpiryMonth",
   "fieldType":"encryptedExpiryDate",
   "uid":card-encrypted-month,
   "valid":false,
   "type":"card",
   "markerNode":div#pmHolder.js-chckt-pm__pm-holder,
   "originalFieldType":"month"
}

Version 1.1.4:

{
  "singleField": true,
  "fieldType": "hostedExpiryDateField",
  "status": "invalid",
  "type": "card",
  "markerNode": :div#pmHolder.js-chckt-pm__pm-holder,
  "originalFieldType": "month"
}

The  uid  parameter in version 1.2.0 and later is a unique identifier created from combining the  txVariant  with the string "encrypted" and  type. So, for example, card-encrypted-month, where card is the txVariant, and month is the type.

It is used as the  id  attribute for the hidden input that is added to the DOM and allows the field to be shown or hidden if invalid.

onFocus

This callback is invoked when the iframe is focused (focus event) or loses focus (blur event).

securedFields.onFocus ( function(focusObject){
});

Example focusObject:

Version 1.2.0 and later:

{
  "action": "focus",
  "focus": true,
  "fieldType": "encryptedExpiryDate",
  "markerNode": div#pmHolder.js-chckt-pm__pm-holder,// Ref to HTML node for this payment method,
  "txVariant": "card"
}

Version 1.1.4:

{
  "action": "focus",
  "focus": true,
  "fieldType": "hostedExpiryDateField",
  "cseKey": "encryptedExpiryDate",
  "markerNode": div#pmHolder.js-chckt-pm__pm-holder,// Ref to HTML node for this payment method,
  "txVariant": "card"
}

When the field loses focus the property focus will have the value  false.

onLoad

This callback is invoked when all the iframes that hold secured fields have been created and have loaded their resources.

securedFields.onLoad = function(loadObject){
};

When this callback is invoked, the loadObject includes a parameter iframesLoaded set to true.

Styling Secured Fields

All card payment method input fields on the Secured Fields form are represented as iframe elements, which securely capture payment data from your shoppers. Use JavaScript to style the fields:

  1. Create an object and set the following CSS values: 

    You can provide styling for the following:

    • base: Base styling applied to the iframe. All styling extends from this style.
    • error: Styling applied when a field fails validation.
    • placeholder: Styling applied to the field's placeholder values.
    • validated: Styling applied once a field passes validation.

    Here is an example style object:

    // Define style object
    var styleObject = {
      base: {
        color: 'black',
        fontSize: '16px',
        fontSmoothing: 'antialiased',
        fontFamily: 'Helvetica'
      },
      error: {
        color: 'red'
      },
      placeholder: {
        color: '#d8d8d8'
      },
      validated: {
        color: 'green'
      }
    };
  2. Style the elements with the following properties. These properties map to CSS properties and accept allowed CSS values:

    JavaScriptCSS

    background

    background

    color

    color

    displaydisplay

    font

    font

    fontFamily

    font-family

    fontSize

    font-size

    fontSizeAdjust

    font-size-adjust

    fontSmoothing

    font-smoothing

    fontStretch

    font-stretch

    fontStyle

    font-style

    fontVariant

    font-variant

    fontVariantAlternates

    font-variant-alternates

    fontVariantCaps

    font-variant-caps

    fontVariantEastAsian

    font-variant-east-asian

    fontVariantLigatures

    font-variant-ligatures

    fontVariantNumeric

    font-variant-numeric

    fontWeight

    font-weight

    letterSpacing

    letter-spacing

    lineHeight

    line-height

    mozOsxFontSmoothing

    moz-osx-font-smoothing

    mozTransition

    moz-transition

    outline

    outline

    opacity

    opacity

    padding

    padding

    textAlign

    text-align

    textShadow

    text-shadow

    transition

    transition

    webkitFontSmoothing

    webkit-font-smoothing

    webkitTransition

    webkit-transition

Configuration object

Add optional properties in the configuration at the bottom of the <body> of your payments page.

  <script type="text/javascript">
   var csfSetupObj = {
      rootNode: '.cards-div',
      configObject : {
        clientKey : "YOUR_CLIENT_KEY",
        cardGroupTypes: ['maestro','visa','amex'] // OPTIONAL
        },
      allowedDOMAccess : false, // OPTIONAL  - Defaults to true
   };
   var securedFields = csf(csfSetupObj);
  </script>
  • cardGroupTypes: Optional. Configure supported card types to facilitate brand recognition used in the onBrand callback. Defaults to ['mc','visa','amex']. See list of available card types. If a shopper enters a card type not specified in the cardGroupTypes configuration, the onBrand callback will not be invoked.
  • allowedDOMAccess: Optional. Enables or disables adding encrypted values to hidden <input> fields in the <div> that holds the data-cse elements. Defaults to true for a standalone implementation, false for Secured Fields Component. If you do not want Secured Fields to automatically add hidden input fields, set allowedDOMAccess to false. To get the encrypted card details when allowedDOMAccess is set to false, use the values from the blob property on the onFieldValid callback object. This callback is invoked as a specific field is validated and encrypted.
    For more information, see Secured Fields callbacks.

Supported card types

Use the values in this list when specifying card types in the brands array. If card types are not provided, the configuration defaults to ['mc','visa','amex']

Card Type Description
amex Amex
argencard Argencard
bcmc Bancontact/Mister Cash
bijcard de Bijenkorf Card
cabal Cabal
cartebancaire Carte Bancaires
codensa Codensa
cup China Union Pay
dankort Dankort
diners Diners Club
discover Discover
elo ELO
forbrugsforeningen Forbrugsforeningen
hiper HiperCard
hipercard HiperCard
jcb JCB
karenmillen Karen Millen GiftCard
laser Laser
maestro Maestro
maestrouk Maestro UK
mc Mastercard
mcalphabankbonus Alpha Bank Mastercard Bonus
mir MIR
naranja Naranja
oasis Oasis GiftCard
shopping Tarjeta Shopping
solo Solo
troy Troy
uatp UATP
visa Visa
visaalphabankbonus Alpha Bank Visa Bonus
visadankort Visa Dankort
warehouse Warehouse GiftCard

Release notes

The Custom Card Web Component replaces all older versions of Secured Fields (versions 1.x.x).

Secured Fields 1.5.2 (March 18, 2019)

This release includes:

  • Fixes for issues with device fingerprinting: for when there are multiple cards configured in Secured Fields and for the errors generated when initializing Secured Fields the second time.
  • Fix for the missing 4-digit placeholder when using American Express saved card details. 
  • Support for propagating the last 4 digits of a card number in the endDigits property of  onFieldValid  callback object.

Secured Fields 1.5.1 (January 28, 2019)

This release includes:

  • Fix for an issue in iOS Safari where the numerical keyboard won't retract.
  • Fix that allows setting a blank placeholder.

Secured Fields 1.5.0 (January 7, 2019)

This release includes the fix that allows shoppers with Kaspersky Internet Security and SafeMoney enabled in their browsers to proceed with entering their card details in the input fields.

We added an iframe that will trigger Kaspersky Internet Security to prompt shoppers to authorize loading iframes from Adyen. If the shopper allows iframes to load or the shopper does not have Kaspersky installed, the normal iframe will be loaded.

Secured Fields 1.3.4 (December 3, 2018)

This release includes:

  • Support for device fingerprinting within Secured Fields resulting to improved performance compared to the CSE implementation.
  • Improved tabbing navigation on Firefox.
  • New aria-placeholder  and aria-label attributes.
  • Fix to now allow deleting spaces between card numbers.
  • Additional supported card types for onBrand callback: naranja, cabal, shopping, argencard, troy, forbrugsforeningen

Secured Fields 1.3.3 (October 15, 2018)

This release includes:

  • A bug fix to prevent the error message briefly shown on iOS Safari when typing a 13-digit Visa number.
  • Support for styling validated fields.

Secured Fields 1.3.2 (October 8, 2018)

This release includes new error handling when a shopper types a wrong card number into a single branded card field. For example, SF will generate an error after typing 7 digits Visa number into a BCMC field.

Secured Fields 1.3.1 (October 1, 2018)

This release includes the new Secured Fields callbacks callback and showWarnings property in the configuration object.

Secured Fields 1.3.0

This release includes: 

New

  • Support for dynamically setting CVC placeholder length based on card brand.

Fixes

  • A bug fix for iOS Safari blur event that was not firing and was causing card validation errors for BCMC.

Improvements

  • Changes in property names for onFieldValid callback object.

  • Improved formatting of card numbers for single branded cards.

Secured Fields 1.2.1

This release includes the fix for issues on blur and focus events on iOS Safari causing unexpected behavior in input fields.

Secured Fields 1.2.0

This release includes: 

New

  • Support for allowedDOMAccess property in the configuration object.

  • Support for 19-digit Visa numbers. 

  • Replaced data-hosted-id with data-cse attributes.

Improvements

  • Support for placeholder styling on IE and Firefox. 
  • Downgraded postMessage event origin mismatch messages from error to warning. 
  • New properties on onFieldValid and onFocus callback objects.

Secured Fields 1.1.4

This release includes improved expiry date validation and sending the resulting error message to the onError callback.