Nicely Pointed Mandibles

    @gr4vy/secure-fields
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.0 • Public • Published

    Secure Fields

    NPM Version GitHub license

    Add Secure Fields to your Node app.

    Use @gr4vy/secure-fields-react in a React application or @gr4vy/secure-fields-cdn in non-Node web application.

    Usage

    Via the command line, install this package as follows.

    npm install @gr4vy/secure-fields --save-prod
    # yarn add @gr4vy/secure-fields --save

    Get started

    To use Secure Fields, you need some placeholder elements to attach the secure fields on to. Each of these elements will be replaced by a secure field. These elements can be <input> but do not need to be.

    <label for="cc-number">Card Number</label>
    <input id="cc-number" />
    
    <label for="cc-cvv">Security code</label>
    <input id="cc-cvv" />
    
    <label for="cc-expiry">Expiry date</label>
    <input id="cc-expiry" />
    
    <button id="cc-button">Submit</button>

    To use Secure Fields, call the new SecureFields() method with a configuration object that includes the environment (sandbox or production), your gr4vyId and a sessionId obtained from calling the Checkout Sessions API.

    Then, add the fields and event listeners needed to handle the form submission.

    const { SecureFields } = require('@gr4vy/secure-fields')
    
    // Alternatively
    // import { SecureFields } from '@gr4vy/secure-fields'
    
    const secureFields = new SecureFields({
      gr4vyId: '[GR4VY_ID]',
      environment: 'sandbox',
      sessionId: '[SESSION_ID]',
    })
    
    secureFields.addFont('Lato')
    
    const styles = {
      color: 'black',
      fontSize: '18px',
      fontFamily: 'Lato',
      ':focus': {
        color: 'blue',
      },
    }
    
    const number = secureFields.addCardNumberField('#cc-number', { styles })
    const expiry = secureFields.addExpiryDateField('#cc-expiry', { styles })
    const cvv = secureFields.addSecurityCodeField('#cc-cvv', { styles })
    
    secureFields.addEventListener(SecureFields.Events.CARD_VAULT_SUCCESS, () =>
      console.log('Card tokenized successfully')
    )
    
    secureFields.addEventListener(SecureFields.Events.CARD_VAULT_FAILURE, () =>
      console.log('Card tokenization failed')
    )
    
    number.addEventListener('input', (data) => {
      console.warn('Input changed', data) // data.schema, data.codeLabel...
    })
    
    const button = document.querySelector('#cc-button')
    button.addEventListener('click', () => {
      secureFields.submit()
    })

    Note: Replace [GR4VY_ID] with your Gr4vy ID and [SESSION_ID] with a valid checkout session id.

    This will initialize Secure Fields and replace each of the inputs with a corresponding secure element. On submit, it will store the card data securely with Gr4vy, after which you can create a transaction or vault the card for later use.

    For more information please refer to the Secure Fields get started guide.

    Styles

    The outer styling of every Secure Field is completely in your control by applying your own CSS to the following class names.

    /* Applied to each field */
    .secure-fields__input {
    }
    /* Applied to the card number field */
    .secure-fields__input--number {
    }
    /* Applied to the expiry date field */
    .secure-fields__input--expiry-date {
    }
    /* Applied to the security code field */
    .secure-fields__input--security-code {
    }
    /* Applied to a focused field */
    .secure-fields__input[data-secure-fields-focused] {
    }
    /* Applied to an invalid field */
    .secure-fields__input[data-secure-fields-invalid] {
    }

    To set the CSS of the content of a field an object of CSS rules can be passed to the addCardNumberField, addExpiryDateField and addSecurityCodeField methods.

    const styles = {
      // Default styles applied to field
      color: "#66666",
      fontSize: "1.3em",
      // ...etc
    
      // Applied when field has a value autofilled by browser/extension
      ':autofill': { ... },
      // Applied when field is hovered
      ':hover': { ... },
      // Applied when field is focused
      ':focus': { ... },
      // Applied when field is disabled
      ':disabled': { ... },
      // Applied when field is valid
      ':valid': { ... },
      // Applied when field is invalid
      ':invalid': { ... },
      // Applied to field placeholder
      '::placeholder': { ... },
    }

    Not all CSS properties can be set. The currently supported list is as follows.

    backgroundColor
    boxShadow
    caretColor
    color
    colorScheme
    cursor
    font
    fontFamily
    fontFeatureSettings
    fontKerning
    fontSize
    fontSizeAdjust
    fontStretch
    fontStyle
    fontVariant
    fontVariantAlternates
    fontVariantCaps
    fontVariantEastAsian
    fontVariantLigatures
    fontVariantNumeric
    fontVariationSettings
    fontWeight
    letterSpacing
    lineHeight
    opacity
    padding
    textAlign
    textShadow
    textRendering
    transition
    MozOsxFontSmoothing
    WebkitFontSmoothing
    

    Events

    Global events

    The following events can be listened to by attaching an event handler to the SecureFields instance using the addEventListener method.

    Name Description Example
    CARD_VAULT_SUCCESS Triggered when the card is successfully vaulted. secureFields.addEventListener(SecureFields.Events.CARD_VAULT_SUCCESS, () => { console.log('Card has been tokenized successfully!') })
    CARD_VAULT_FAILURE Triggered when the card vaulting fails. secureFields.addEventListener(SecureFields.Events.CARD_VAULT_FAILURE, () => { console.log('Couldn\'t tokenize the card') })
    READY Triggered when Secure Fields is loaded and ready to be used. secureFields.addEventListener(SecureFields.READY, () => { console.log('Secure fields loaded') })

    Field events

    The following events can be listened to by attaching an event handler to a field (returned by the addCardNumberField, addExpiryDateField and addSecurityCodeField methods) using the addEventListener method.

    Some of these provide additional useful data like the card BIN, validation status, and scheme. For example, the input event on a card number field might include { schema: 'visa', codeLabel: 'CVV', valid: true, ... }.

    Name Description Example
    blur Triggered when the field loses focus. cardNumberField.addEventListener('blur', (data) => { console.log(data) /* { type: 'number' } */ })
    focus Triggered when the field gains focus. cardNumberField.addEventListener('focus', (data) => { console.log(data) /* { type: 'number' } */ })
    input Triggered when the field value has been changed. cardNumberField.addEventListener('input', (data) => { console.log(data) /* { type: 'number', schema: 'visa', codeLabel: 'CVV', valid: true } */

    API reference

    Getters

    Name Description
    Events Gives access to the supported events.

    SecureFields.Events.READY
    version Returns the current version of the instance.

    SecureFields.version

    Methods

    Name Description
    constructor Instantiates SecureFields with a configuration object include environment, gr4vyId and a session id.

    new SecureFields({...})
    addCardNumberField Injects a secure field of type number.

    secureFields.addCardNumberField('#cc-number', { placeholder: 'Enter card number', ... })
    addSecurityCodeField Injects a secure field of type securityCode.

    secureFields.addSecurityCodeField('#cc-security-code', { placeholder: 'Enter security code', ... })
    addExpiryDateField Injects a secure field of type expiryDate.

    secureFields.addExpiryDateField('#cc-expiry-date', { placeholder: 'Enter expiry date', ... })
    addEventListener Attaches an event handler to the SecureFields instance or to a secure field in order to listen to specific events. Requires one of the events supported and a callback.

    secureFields.addEventListener(SecureFields.Events.READY, (data) => { ... })

    cardNumberField.addEventListener('input', (data) => { ... })
    removeEventListener Removes a previously attached event handler.
    submit Calls the Vault API to tokenize and store the card data.

    secureFields.submit()
    setDebug Enable / disable debug mode. When the debug mode is enabled, SecureFields logs information to the console.

    secureFields.setDebug(true)
    addFont Load a custom font from Google Fonts to be used inside inputs. You can define the font family as well as styles or weights as a string (e.g. "Lato:400,600"). To use the loaded font, add the correct fontFamily property to the styles object when creating fields.

    secureFields.addFont('Lato')

    Keywords

    none

    Install

    npm i @gr4vy/secure-fields

    Homepage

    gr4vy.com

    DownloadsWeekly Downloads

    4

    Version

    1.0.0

    License

    MIT

    Unpacked Size

    40.1 kB

    Total Files

    17

    Last publish

    Collaborators

    • luca-gr4vy
    • gr4vy!
    • douglaseggleton
    • cbetta