Secure Fields is a light-weight way to capture card data in a PCI-compliant way, while fitting uniquely into any bespoke payment flow.

We recommend you start by installing our SDK to get access the Cloud Vault API.

​
Install Secure Fields

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

npm install @gr4vy/secure-fields-react --save
# or: yarn add @gr4vy/secure-fields-react

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

​
Initializing secure fields

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

Secure Fields expects a checkout session ID you created using one of our server-side SDKs.

import '@gr4vy/secure-fields-react/lib/style.css'
import { SecureFields } from "@gr4vy/secure-fields-react";

const App = () => {
  return (
    <SecureFields
      // set up the environment
      gr4vyId="vault"
      environment="sandbox" // or "production"
      sessionId={sessionId} 
      // 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>
  );
};

​
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.

import {
  CardNumber,
  ExpiryDate
} 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" />

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

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.

You should now see each secure field loaded on your page. Please see our more extensive guides on how to add event listeners and your own styles 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.

import { useSecureFields } from "@gr4vy/secure-fields-react";

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

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

Checkout session expiry

A checkout session is only valid for one hour. This means that the checkout session needs to be used to fully store a payment method before that time.

​
Convert to payment method

Card data in a checkout session needs to be explicitly stored as a payment method. At this point, the payment method can also be associated with a buyer record to group payment methods together.

curl -i -X POST "https://api.vault.gr4vy.app/payment-methods" \
    -H "Authorization: Bearer [JWT_TOKEN]" \
    -H "Content-Type: application/json" \
    -d '{
            "method": "checkout-session",
            "id": "332a6c3a-c4eb-45f6-9a4e-72af459535e2"
        }'

The returned payment method includes details about the card used, and ID of the payment method can be used to create a transaction at a later point.

{
    "type": "payment-method",
    "id": "77a76f7e-d2de-4bbc-ada9-d6a0015e6bd5",
    "method": "card",
    "scheme": "visa",
    "expiration_date": "07/24",
    ...
}

Was this page helpful?

API accessForward vaulted data