> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mattildapayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Step 3: Add secure fields

The next step to is to add **Secure Fields** to your checkout experience.

## Install Secure Fields

There are a few ways to install **Secure Fields**, either as a React component,
Node library, or straight off our CDN.

<CodeGroup>
  ```bash React theme={"dark"}
  npm install @gr4vy/secure-fields-react --save
  # or: yarn add @gr4vy/secure-fields-react
  ```

  ```bash Node theme={"dark"}
  npm install @gr4vy/secure-fields --save
  # or: yarn add @gr4vy/secure-fields
  ```

  ```html CDN theme={"dark"}
  <script src="https://cdn.mattildapayments.com/secure-fields/latest/secure-fields.js"></script>
  <link
    rel="stylesheet"
    href="https://cdn.mattildapayments.com/secure-fields/latest/secure-fields.css"
  />
  ```
</CodeGroup>

<Note>
  When using the CDN the latest version of the library is always pulled straight
  from the server for every request.
</Note>

## Initializing secure fields

With **Secure Fields** installed it's now possible to initialize the connection
to your instance.

**Secure Fields** expects the ID of your instance (`gr4vyId`), the
environment, and a checkout session ID.

<CodeGroup>
  ```jsx React theme={"dark"}
  import '@gr4vy/secure-fields-react/lib/style.css'
  import { SecureFields } from "@gr4vy/secure-fields-react";

  const App = () => {
    return (
      <SecureFields
        // set up the environment
        gr4vyId="mattilda"
        environment="sandbox"
        sessionId={sessionId} // created in step 2
        // enable debugging
        debug
        // attach event handlers
        onReady={(data) => console.warn("Secure Fields loaded", data)}
        onCardVaultSuccess={() =>
          console.warn("Card has been tokenized successfully!")
        }
        onCardVaultFailure={() => console.error("Failed to tokenize card data")}
      >
        {/* Form to be added next */}
        <Form />
      </SecureFields>
    );
  };
  ```

  ```js Node theme={"dark"}
  import SecureFields from "@gr4vy/secure-fields";

  // set up the environment
  const gr4vyId = "mattilda";
  const environment = "sandbox";
  const sessionId = "..."; // created in step 2
  // initialize the SDK
  const secureFields = new SecureFields({
    gr4vyId,
    environment,
    sessionId,
  });
  // enable debugging
  secureFields.setDebug(true);
  ```

  ```js CDN theme={"dark"}
  // set up the environment
  const gr4vyId = "mattilda";
  const environment = "sandbox";
  const sessionId = "...";
  // initialize the SDK
  const secureFields = new SecureFields({
    gr4vyId,
    environment,
    sessionId,
  });
  // enable debugging
  secureFields.setDebug(true);
  ```
</CodeGroup>

## Adding each of the individual fields

Next, you can add any of the 3 individual fields to your form. You can mix and
match these with your own forms, and you can add your own labels.

<CodeGroup>
  ```jsx React theme={"dark"}
  import {
    CardNumber,
    ExpiryDate,
    SecurityCode,
  } from '@gr4vy/secure-fields-react'

  const Form = () => {
    return (
      // You can add your own fields as well as secure fields
      <label htmlFor="cc-holder-name">Cardholder Name</label>
      <input
        id="cc-holder-name"
        placeholder="Name on the card"
      />

      // These are secure fields
      <label htmlFor="cc-number">Card Number</label>
      <CardNumber placeholder="Enter card number" />

      <label htmlFor="cc-expiry-date">Expiry Date</label>
      <ExpiryDate placeholder="Enter expiry date" />

      <label htmlFor="cc-security-code">Security Code</label>
      <SecurityCode placeholder="Enter security code" />

      <button id='cc-button'>Store card data</button>
    )
  }
  ```

  ```html Node theme={"dark"}
  {/* You can add your own fields as well as secure fields */}
  <label for="cc-holder-name">Name</label>
  <input id="cc-holder-name" placeholder="Name on the card" />

  {/* These are secure fields */}
  <label for="cc-number">Card Number</label>
  <input id="cc-number" />

  <label for="cc-security-code">Security Code</label>
  <input id="cc-security-code" />

  <label for="cc-expiry-date">Expiry date</label>
  <input id="cc-expiry-date" />

  <button id="cc-button">Store</button>

  <script>
    // Add fields via the addField method
    const cardNumberField = secureFields.addCardNumberField("#cc-number", {
      placeholder: "Enter card number",
    });

    const securityCodeField = secureFields.addSecurityCodeField(
      "#cc-security-code",
      {
        placeholder: "Enter security code",
      }
    );

    // Alternatively an HTML element can be passed directly
    const expiryDateField = secureFields.addExpiryDateField(
      document.querySelector("#cc-expiry-date"),
      {
        placeholder: "Enter expiry date",
      }
    );
  </script>
  ```

  ```html CDN theme={"dark"}
  {/* You can add your own fields as well as secure fields */}
  <label for="cc-holder-name">Name</label>
  <input id="cc-holder-name" placeholder="Name on the card" />

  {/* These are secure fields */}
  <label for="cc-number">Card Number</label>
  <input id="cc-number" />

  <label for="cc-security-code">Security Code</label>
  <input id="cc-security-code" />

  <label for="cc-expiry-date">Expiry date</label>
  <input id="cc-expiry-date" />

  <button id="cc-button">Store</button>

  <script>
    // Add fields via the addField method
    const cardNumberField = secureFields.addCardNumberField("#cc-number", {
      placeholder: "Enter card number",
    });

    const securityCodeField = secureFields.addSecurityCodeField(
      "#cc-security-code",
      {
        placeholder: "Enter security code",
      }
    );

    // Alternatively an HTML element can be passed directly
    const expiryDateField = secureFields.addExpiryDateField(
      document.querySelector("#cc-expiry-date"),
      {
        placeholder: "Enter expiry date",
      }
    );
  </script>
  ```
</CodeGroup>

<Info>
  Unless you are using our React SDK, every field Embed needs to be attached to an HTML element.
  In this case, we attached the fields to `<input>` fields. The fields can be attached to
  any element using a `querySelector`-compatible query.
</Info>

You should now see each secure field loaded on your page. Please see our more
extensive guides on how to add [event listeners](/guides/payments/secure-fields/events) and
your own [styles](/guides/payments/secure-fields/theming) to **Secure Fields**.

## Vaulting the card data

**Secure Fields** handles the PCI-compliant submission of all the card data to
our servers. Once your form is ready, use the submit functionality of
**Secure Fields** to vault the data. A callback will notify you when the data
has been submitted successfully.

<CodeGroup>
  ```jsx React theme={"dark"}
  import { useSecureFields } from "@gr4vy/secure-fields-react";

  const Form = () => {
    const { secureFields } = useSecureFields();

    const onClick = () => {
      secureFields.submit();
    };
  };
  ```

  ```js Node theme={"dark"}
  secureFields.addEventListener(SecureFields.Events.CARD_VAULT_SUCCESS, () => {
    console.log("Card successfully tokenized");
  });
  secureFields.addEventListener(SecureFields.Events.CARD_VAULT_FAILURE, () => {
    console.log("Card tokenization failed");
  });

  document.querySelector("#cc-button").addEventListener("click", () => {
    secureFields.submit();
  });
  ```

  ```js CDN theme={"dark"}
  secureFields.addEventListener(SecureFields.Events.CARD_VAULT_SUCCESS, () => {
    console.log("Card successfully tokenized");
  });
  secureFields.addEventListener(SecureFields.Events.CARD_VAULT_FAILURE, () => {
    console.log("Card tokenization failed");
  });

  document.querySelector("#cc-button").addEventListener("click", () => {
    secureFields.submit();
  });
  ```
</CodeGroup>

<br />

<Warning>
  **Checkout session expiry**

  A checkout session is only valid for one hour. This means that the checkout
  session needs to be used to create a transaction or store the details as
  a payment method before that time.
</Warning>

## Summary

In this step you:

* Installed and initialized Secure Fields.
* Rendered each of the individual fields in your own UI
* Submitted the data to the vault and listened for events