Skip to main content

Secure Fields

Stitch provides Secure Fields within an SDK to enable merchants to collect sensitive card details for payment. This ensures sensitive data never reaches your server unencrypted, while still allowing for fully customisable checkout flows.

Key features of Stitch Secure Fields include:

  • Automatic input formatting and validation as customers type,
  • Responsive design to fit seamlessly on any screen size,
  • Custom styling rules to match the look and feel of your site, and
  • No PCI-DSS compliance requirement for the merchant.

Usage Overview​

The Secure Fields SDK will provide you with encrypted details (limiting PCI-DSS scope), which may be used as inputs when creating transactions within the following flows:

Follow the steps below to add Secure Fields to your web application to capture customer card data.

Installing SDK​

Install the SDK and component package applicable to your client-side framework: The @stitch-money/react package should be used for React applications, while the @stitch-money/web package should be used for non-React applications.

npm install @stitch-money/react

Rendering Secure Form and Fields​

The SDK consists of two components:

  • Stitch Secure Form: Contains shared logic and coordinates Stitch Secure Fields composed within the component. It must be placed high enough in your component tree to wrap all instances of <StitchSecureField>.
  • Stitch Secure Field: An individual field for capturing one aspect of the customer's card. You require at least two fields to capture the number and cvc.

Stitch Secure Form​

This component accepts the following properties:

NameDescription
clientIdThe client ID assigned to you by Stitch that you will be processing your transactions on.
onReadyA function for handling the ready event emitted when all secure fields have loaded successfully.
onChangeA function for handling change events emitted when the customer makes changes to any of the secure fields.
theme(Optional) A custom theme which changes the appearance of the secure fields, supports most CSS attributes.

An example of importing and rendering this component (depending on your JavaScript framework) is as follows:

import { StitchSecureForm } from '@stitch-money/react';

export function PaymentPage() {
  const handleSecureFormChange = ({ payload }) => {
    console.log(payload);

    if (payload.isComplete) {
      // This function should send the encrypted card data to your backend which would in turn send it to the Stitch Secure API
      sendEncryptedCardDataToBackend(payload);
    }
  };

  const handleSecureFormReady = () => {
    // This function could toggle a state variable to update the visibility of the loaded Secure Field components
    console.log('Secure Fields Loaded');
  };

  const theme = {
    styles: {
      ':root': {
        'color-scheme': 'dark',
      },
      // Style all field inputs
      '.field input': {
        marginTop: 8,
        padding: '8px 12px',
      },
    },
  };

  return (
    <div>
      <StitchSecureForm
        clientId="your Stitch client ID"
        onReady={handleSecureFormReady}
        onChange={handleSecureFormChange}
        theme={theme}
      >
        {/* add child secure field components */}
      </StitchSecureForm>
    </div>
  );
}

Stitch Secure Fields​

This component accepts the following properties / attributes:

NameDescription
fieldThe field that should be rendered, can be one of name, number, expiry, or cvc.
label(Optional) Custom label text for this input.

An example of rendering a form with secure fields (depending on your JavaScript framework) is as follows:

import { StitchSecureField, StitchSecureForm } from '@stitch-money/react';

export function PaymentPage() {
  // ... setup from previous step

  return (
    <div>
      <StitchSecureForm
        clientId="your Stitch client ID"
        onChange={handleSecureFormChange}
        theme={theme}
      >
        <div>
          <StitchSecureField field="name" label="Cardholder Name" />
          <StitchSecureField field="number" label="Card Number" />
          <StitchSecureField field="expiry" label="Expiry Date" />
          <StitchSecureField field="cvc" label="CVC" />
        </div>
      </StitchSecureForm>
    </div>
  );
}

The structure of the elements within <StitchSecureForm> is up to you - The only requirement is that all <StitchSecureField> elements are contained by a single <StitchSecureForm> element somewhere up the component tree.

Ready Event​

The onReady handler function is used to determine when all <StitchSecureField> elements have loaded successfully.

Below is an example of a handler function that toggles a loading state variable once the ready event has been fired:

const handleSecureFormReady = () => {
  // Here you could toggle your loading state variable to display the <StitchSecureForm> and <StitchSecureField> elements once they have loaded
  setIsStitchSecureFormLoading(false);
};

Change Events​

The onChange handler function (or stitch-secure-fields-change event listener) is used to determine when the customer has completed capturing card details and to receive those encrypted details. The payload that is supplied as an argument to your handler function is structured as follows:

NameDescription
card.nameThe card holder's name.
card.numberThe encrypted card number (PAN). This will only be present if the number is valid.
card.brandThe network that issued the card.
card.lastFourThe last four digits of the card number. This will only be present if the number is valid.
card.binThe Bank Identification Number (BIN) for the card. This will only be present if the number is valid.
card.expiry.monthThe month of the card expiration date.
card.expiry.yearThe year of the card expiration date.
card.cvcThe encrypted card CVC.
card.issuerThe financial institution that issued the card. This will only be present for a subset of issuers.
errorsValidation errors scoped by field.
isValidWhether or not there are any validation errors currently on any of the fields.
isCompleteWhether or not all of the fields have been successfully filled out with valid values.
fingerprintContains data used to identify the user's device. This must be forwarded to your server and included in a Stitch API request

You can access these values within your change handler function:

const handleSecureFormChange = ({ payload }) => {
  if (!payload.isValid) {
    // Here, we know values the customer has entered are invalid - Show validation error
    showErrorStateToCustomer(payload.errors.number); // Contains the validation error associated with the card number field.
  }

  if (payload.isComplete) {
    // Here we know the customer has completed filling out the fields, and the associated values are valid - Send to backend for processing.
    sendEncryptedCardDataToBackend({
      name: payload.card.name,
      pan: payload.card.number,
      expiryMonth: payload.card.expiry.month,
      expiryYear: payload.card.expiry.year,
      cvc: payload.card.cvc,
      fingerprint: payload.fingerprint,
    });
  }
};
note

These details must be submitted to your backend, and can be included as inputs for the Once-off or Tokenization API calls.

Custom Styling​

By default the secure fields will be rendered with a simple appearance that should fit into most applications. If you want to customise the appearance of the fields and their associated validation error messages you can supply a theme object to the <StitchSecureForm> component. The keys of the object are CSS selectors and the values are the same values you would use when writing CSS for the respective selector.

Currently only custom fonts from Google Fonts are supported.

Examples​

To set styles that affect every part of all fields you can use the :root selector:

const theme = {
  styles: {
    ':root': {
      'color-scheme': 'dark', // dark mode
    },
  },
};

To apply styles to all secure field label elements use the label selector:

const theme = {
  styles: {
    label: {
      fontWeight: 500,
      textTransform: 'uppercase',
    },
  },
};

To apply styles to all secure field input elements use the .field input selector:

const theme = {
    styles: {
        '.field input': {
            marginTop: 4,
            padding: 8px 12px,
        }
    }
}

To apply styles to the secure field input element that currently has focus use the .field:focus-within input selector:

const theme = {
  styles: {
    '.field:focus-within input': {
      borderColor: '#5F19E2',
    },
  },
};

To apply styles to the secure field validation messages use the .error selector:

const theme = {
  styles: {
    '.error': {
      display: 'none', // Hide built-in validation error messages
    },
  },
};

To apply styles to a specific secure field input use the .field[ev-name=<field name here>] selector:

const theme = {
  styles: {
    '.field[ev-name=number]': {
      // Style only the card number input
      'font-size': '24px',
    },
  },
};

To load custom fonts, provide the Google Font links in the fonts array and specify the corresponding fontFamily value within the selectors for the target elements:

const theme = {
  // This will load the font from Google Fonts
  fonts: ['https://fonts.googleapis.com/css2?family=Comic+Neue'],
  styles: {
    // This will apply the font to the field labels
    '.field label': {
      fontFamily: "'Comic Neue'",
    },
    // This will apply the font to the error text
    '.error': {
      fontFamily: "'Comic Neue'",
    },
  },
};

Incorporating StitchPass​

StitchPass provides a more seamless way for returning users to pay, with on-device remembrance of payment methods. If StitchPass is enabled on your client configuration, using this only requires minor additions to the above integration.

To enable StitchPass functionality whereby a user's method may be added, or used for returning payments, a button should be added to your checkout journey. This is provided with the <StitchPassButton> and may be used in place of your custom 'Add Card' or 'Pay with Card' button.

When using this button component, a payerId must be included. This is the unique payer ID on your system, and must correspond to the payerId provided within any PayerInformation of transactions that are processed.

As an example of this usage is:

import { StitchPassButton } from '@stitch-money/react';

export function PaymentPage() {
  // ... payment page setup

  return (
    <div>
      <StitchPassButton
        clientId="your Stitch client ID"
        payerId="unique ID of user viewing your checkout"
      ></StitchPassButton>
    </div>
  );
}

Note that this will automatically be styled according to your branding, with your brand's logo and colours (Stitch will assist with configuring this against your client ID).