Standalone Secured Fields

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.

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.

     /paymentMethods response

     {
     "paymentMethods":[
     ...
       {
       "details":[{
           "key":"sepa.ownerName",
           "type":"text"
         },{
           "key":"sepa.ibanNumber",
           "type":"text"
         }
       ],
       "name":"SEPA Direct Debit",
       "type":"sepadirectdebit"
     },
     ...
     ]
     }

     https://docs.adyen.com/payment-methods/cards/secured-fields-standalone#-paymentmethods-response

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.

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:

   • clientKey: a public key linked to your API credential, used for client-side authentication.

   <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 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:

   JavaScript	CSS
   background	background
   color	color
   display	display
   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.