Secure Fields

Create custom checkout flows with prebuilt or fully customisable Secure Fields from Stitch.

Stitch Secure Fields offers a set of prebuilt UI components designed for building checkout flows. Secure Fields is an SDK that enable merchants to collect sensitive payment details within a Secure Field element, ensuring that sensitive data never touches a merchants server unencrypted but 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
Handling 3D Secure (3DS) authentication and redirection URLs
Custom styling rules to match the look and feel of your site
Less PCI compliance scope

Usage of Secure Fields in your integration

The Secure Fields SDK will provide you with encrypted details, limiting PCI scope, which may be used as inputs with other Secure API queries. For example:

sequenceDiagram participant SF as Secure Fields SDK participant User as Client checkout page participant Client as Client backend participant API as Stitch API Client ->> User: 1. Begin payment flow User ->> SF: 2. Initialise SDK User ->> SF: 3. Create Secure Fields inputs User ->> User: 4. Fill in card details SF ->> User: 5. Encrypted PAN and CVV User ->> Client: 6. Encrypted PAN and CVV Client ->> API: 7. Once-off payment or tokenization API -->> Client: 8. Continue with relevant flow

Adding Secure Fields to your web application

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

Currently only React is supported but other frontend frameworks will be added soon.

Install

Install the package from npm using your package manager of choice:

npm install @stitch-money/react

Render Stitch Secure Form and Fields

The SDK consists of two components:

<StitchSecureForm> - contains shared logic and coordinates Stitch Secure Fields within it, must be placed high enough in your component tree that it wraps all instances of <StitchSecureField>.
<StitchSecureField> - this is an individual field for capturing one aspect of the customer's card, you will need at least 2 of these to capture number and cvc.

`<StitchSecureForm>`

This component accepts the following properties:

Name	Description
clientId	The client ID assigned to you by Stitch that you will be processing your transactions on.
onReady	A function for handling the ready event emitted when all secure fields have loaded successfully.
onChange	A 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.

You can import and render this component 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 make the now loaded Secure Field components visible
    console.log("Secure Fields Loaded");
  };

  const theme = {
    styles: {
      ":root": {
        // Dark mode
        "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}
      >
        {/* child components go here */}
      </StitchSecureForm>
    </div>
  );
}

`<StitchSecureField>`

This component accepts the following properties:

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

You can import and render this component as follows:

import { StitchSecureField } 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="number" label="Your card number" />
          <StitchSecureField field="expiry" />
          <StitchSecureField field="cvc" label="Your security code" />
        </div>
      </StitchSecureForm>
    </div>
  );
}

note

Only the number and cvc fields are required to be captured and encrypted using a Stitch Secure Field. You will also need to capture the card holder name and the card expiry. This can be done using your own inputs or you can use the respective fields provided by our SDK.

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.

Listen for 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);
};

Listen for Change Events

The onChange handler function 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:

Name	Description
card.name	The card holder's name.
card.number	The encrypted card number (PAN). This will only be present if the number is valid.
card.brand	The network that issued the card.
card.lastFour	The last four digits of the card number. This will only be present if the number is valid.
card.bin	The Bank Identification Number (BIN) for the card. This will only be present if the number is valid.
card.expiry.month	The month of the card expiration date.
card.expiry.year	The year of the card expiration date.
card.cvc	The encrypted card CVC.
card.issuer	The financial institution that issued the card. This will only be present for a subset of issuers.
errors	Validation errors scoped by field.
isValid	Whether or not there are any validation errors currently on any of the fields.
isComplete	Whether or not all of the fields have been successfully filled out with valid values.
fingerprint	Contains 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 the values the customer has entered are currently invalid
    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.
    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'",
    },
  },
};

Secure Fields

Usage of Secure Fields in your integration​

Adding Secure Fields to your web application​

Install​

Render Stitch Secure Form and Fields​

<StitchSecureForm>​

<StitchSecureField>​

Listen for Ready Event​

Listen for Change Events​

Custom Styling​

Examples​