React Native SDK

You can use our React Native SDK to:

Encrypt data client-side
Collect card data securely
Perform 3D Secure authentication

Installation

Our React Native SDK is distributed via npm, and can be installed using your preferred package manager.

## Using npm
npm install @evervault/react-native
## Using yarn
yarn add @evervault/react-native
## Using Expo
npx expo install @evervault/react-native

The react-native-webview package is a peer dependency and will need to be installed as well.

## Using npm
npm install react-native-webview
## Using yarn
yarn add react-native-webview
## Using Expo
npx expo install react-native-webview

Expo

This library has native code, so it does not work with Expo Go. However, you can install it using a custom development build.

If you are using code shrinking with ProGuard for Android, you will need to specify exclusion rules for several Evervault dependencies. The required ProGuard rules can be found in our Android SDK docs.

Quickstart

Add the EvervaultProvider to your App

Wrap your app with the <EvervaultProvider /> component and pass your Team and App ID as props.

Your Team and App ID can be found in the Evervault Dashboard.

1
import { EvervaultProvider } from '@evervault/react-native';
2
3
function App() {
4
  return (
5
    <EvervaultProvider teamId="team_id" appId="app_id">
6
      <YourApp />
7
    </EvervaultProvider>
8
  );
9
}

Collect Card Data

You can use the <Card /> component to collect card data securely.

1
import { Card, type CardPayload } from '@evervault/react-native';
2
import { Button, Form } from '@your/ui';
3
4
function CardForm({ onSubmit }: CardFormProps) {
5
  const [data, setData] = useState<CardPayload | null>(null);
6
7
  return (
8
    <Form>
9
      <Card onChange={setData}>
10
        <Card.Number />
11
        <Card.Expiry />
12
        <Card.Cvc />
13
        <Card.Holder />
14
      </Card>
15
16
      <Button disabled={!data?.isValid || !data?.isComplete} onPress={onSubmit}>
17
        Pay
18
      </Button>
19
    </Form>
20
  );
21
}

If you don't need to collect all four types of supported Card Data, you can omit the relevant components.

However, the components cannot be used individually outside of the <Card /> component.

Perform 3D Secure Authentication

You can use the <ThreeDSecure /> component in combination with the Evervault API to perform 3DS authentications.

In order to use the 3DS component you must first create a 3DS session on your backend and pass it to your frontend. You can then use the <ThreeDSecure.Frame /> component to display the 3DS webview.

1
import { ThreeDSecure, useThreeDSecure } from '@evervault/react-native';
2
import { createThreeDSecureSession } from '@your/api';
3
import { Button, Form, Modal } from '@your/ui';
4
5
function Checkout({ onSuccess, onFailure, onError }: CheckoutProps) {
6
  const tds = useThreeDSecure();
7
8
  async function handlePayment() {
9
    // Create a 3DS session on your backend
10
    const sessionId = await createThreeDSecureSession();
11
12
    tds.start(sessionId, {
13
      onSuccess,
14
      onFailure,
15
      onError,
16
    });
17
  }
18
19
  return (
20
    <Form>
21
      <Button onPress={handlePayment}>Pay</Button>
22
23
      <ThreeDSecure state={tds}>
24
        <Modal onRequestClose={() => tds.cancel()}>
25
          <ThreeDSecure.Frame />
26
        </Modal>
27
      </ThreeDSecure>
28
    </Form>
29
  );
30
}

Components

<EvervaultProvider />

Wraps your app in a new Evervault context, scoped to a specific team and app.

1
import { EvervaultProvider } from '@evervault/react-native';
2
3
function App() {
4
  return (
5
    <EvervaultProvider teamId="team_123" appId="app_123">
6
      <YourApp />
7
    </EvervaultProvider>
8
  );
9
}

Props

teamIdRequiredString

The Team ID found in the Evervault Dashboard.

appIdRequiredString

The App ID found in the Evervault Dashboard.

<Card />

1
import { Card, type CardPayload } from '@evervault/react-native';
2
3
function CardForm() {
4
  const [data, setData] = useState<CardPayload | null>(null);
5
6
  return (
7
    <Card onChange={setData}>
8
      <Card.Number />
9
    </Card>
10
  );
11
}

The Card component is used to collect card data securely. It is a wrapper component that manages the state of the child input components:

<Card.Holder />
<Card.Number />
<Card.Expiry />
<Card.Cvc />

You do not have to render all of the available child input components as children. For example, if you only need to collect a card number and expiry, you can omit the Card.Cvc and Card.Holder components.

The onComplete field will be true once all rendered fields are filled out successfully with valid values.

Props

acceptedBrandsCardBrandName[]

An array of card brands that are accepted. If not provided, all brands are accepted.

defaultValuesCardForm

Default values for the card fields.

onChange(payload: CardPayload) => void

A callback function that is called whenever the card data changes.

validationMode'onChange' | 'onBlur' | 'onTouched' | 'all'

The validation mode for the card fields. Defaults to all.

<Card.Holder />

Used as a child of <Card /> to collect the name of a card holder.

1
import { Card } from '@evervault/react-native';
2
3
function CardForm() {
4
  return (
5
    <Card>
6
      <Card.Holder placeholder="Johnny Appleseed" />
7
    </Card>
8
  );
9
}

<Card.Number />

Used as a child of <Card /> to collect a card number.

1
import { Card } from '@evervault/react-native';
2
3
function CardForm() {
4
  return (
5
    <Card>
6
      <Card.Number placeholder="1234 1234 1234 1234" />
7
    </Card>
8
  );
9
}

<Card.Expiry />

Used as a child of <Card /> to collect a card expiry.

1
import { Card } from '@evervault/react-native';
2
3
function CardForm() {
4
  return (
5
    <Card>
6
      <Card.Number />
7
      <Card.Expiry placeholder="MM / YY" />
8
    </Card>
9
  );
10
}

<Card.Cvc />

Used as a child of <Card /> to collect a card CVC.

1
import { Card } from '@evervault/react-native';
2
3
function CardForm() {
4
  return (
5
    <Card>
6
      <Card.Number />
7
      <Card.Cvc placeholder="CVC" />
8
    </Card>
9
  );
10
}

<ThreeDSecure />

The ThreeDSecure component is used to provide access to the 3DS authentication process.

This component allows you to use the <ThreeDSecure.Frame /> component to display the 3DS webview. Any custom components you want to display alongside the 3DS webview should be wrapped in the ThreeDSecure component.

It should be used in combination with the useThreeDSecure hook.

Props

stateRequiredThreeDSecureState

The 3DS session state returned from the useThreeDSecure hook.

<ThreeDSecure.Frame />

The ThreeDSecure.Frame component is used to display the 3DS webview, which will handle the authentication process.

If the user closes the frame before completion, you will need to use the cancel() method (from the useThreeDSecure hook) to properly close the webview and clean up the session.

1
import { ThreeDSecure, useThreeDSecure } from '@evervault/react-native';
2
import { createThreeDSSession } from '@your/api';
3
import { Button, Form, Modal } from '@your/ui';
4
5
function CustomCheckout() {
6
  const tds = useThreeDSecure();
7
8
  async function handlePayment() {
9
    // Create a 3DS session on your backend
10
    const sessionId = await create3DSecureSession();
11
12
    tds.start(sessionId, {
13
      onSuccess: () => {
14
        console.log('3DS successful');
15
      },
16
      onFailure: (error: Error) => {
17
        console.error('3DS failed', error);
18
      },
19
      onError: (error: Error) => {
20
        console.warn('3DS errored', error);
21
      },
22
    });
23
  }
24
25
  return (
26
    <Form>
27
      <Button onPress={handlePayment}>Pay</Button>
28
29
      <ThreeDSecure state={tds}>
30
        <Modal onRequestClose={tds.cancel}>
31
          <ThreeDSecure.Frame />
32
        </Modal>
33
      </ThreeDSecure>
34
    </Form>
35
  );
36
}

Props

styleStyleProp<ViewStyle>

The style for the inner WebView component.

Hooks

useEvervault()

The useEvervault hook is used to access the current Evervault scope in context.

Any component that uses this hook must be wrapped in the <EvervaultProvider /> component.

1
import { useEvervault } from '@evervault/react-native';
2
import { Button, Text, TextInput, View } from 'react-native';
3
4
function YourApp() {
5
  const { teamId, appId, encrypt } = useEvervault();
6
7
  const [data, setData] = useState('');
8
  const [encryptedData, setEncryptedData] = useState('');
9
10
  async function handleEncrypt() {
11
    const encrypted = await encrypt(data);
12
    setEncryptedData(encrypted);
13
  }
14
15
  return (
16
    <View>
17
      <Text>
18
        Encrypting data for team {teamId} and app {appId}
19
      </Text>
20
21
      <TextInput value={data} onChangeText={setData} />
22
      <Button title="Encrypt" onPress={handleEncrypt} />
23
24
      <Text>Encrypted Data: {encryptedData}</Text>
25
    </View>
26
  );
27
}

Returns

encrypt(data)

Encrypts the provided data using native encryption modules and the Evervault API.

Parameters

dataRequired

The data to encrypt.

useThreeDSecure()

The useThreeDSecure hook is used to manage the 3DS authentication process.

It returns an object with start() and cancel() methods. The returned object should be used with the <ThreeDSecure /> component.

Returns

start(sessionId, callbacks)

The start function is used to kick off the 3DS authentication process.

Parameters

sessionIdRequiredString

The 3DS session ID. A 3DS session can be created using the Evervault API.

callbacksThreeDSecureCallbacks

The callbacks to be called when the 3DS authentication process is finished.

cancel()

The cancel() function is used to cancel the ongoing 3DS authentication process. This can be particularly useful for canceling a session when a custom cancel button is triggered.

Types

CardBrandName

1
import { type CardBrandName } from '@evervault/react-native';

The type for the card brand name. One of the following:

american-express
visa
mastercard
discover
jcb
diners-club
unionpay
maestro
mir
elo
hipercard
hiper
szep
uat

CardPayload

1
import { type CardPayload } from '@evervault/react-native';

The payload returned by the onChange callback of the <Card /> component.

Properties

card.namestring | null

The card holder name.

card.numberstring | null

The encrypted card number. This will only be present if the number is valid.

card.brandCardBrandName | null

The global payment card brand associated with the card.

card.localBrandsCardBrandName[]

The local payment card brands that are accepted by the card

card.lastFourstring | null

The last 4 digits of the card. This will only be present if the number is valid.

card.binstring | null

The bin for the card. This will only be present if the number id valid.

card.expiry.monthstring | null

The month for the card expiry field.

card.expiry.yearstring | null

The year for the card expiry field.

card.cvcstring | null

The encrypted card CVC.

errors{ name?: string, number?: string, expiry?: string, cvc?: string }

Validation errors related to the card details.

isValidboolean

Whether or not there are any errors present.

isCompleteboolean

Whether or not all of the fields have been filled out successfully with valid values.

EvervaultInput

1
import { type EvervaultInput } from '@evervault/react-native';

The type for the ref that can be passed to the <Card /> input components.

It exposes a subset of the React Native TextInput methods.

1
type EvervaultInput = Pick<
2
  TextInput,
3
  | 'isFocused'
4
  | 'focus'
5
  | 'blur'
6
  | 'clear'
7
  | 'measure'
8
  | 'measureInWindow'
9
  | 'measureLayout'
10
>;

EvervaultInputProps

1
import { type EvervaultInputProps } from '@evervault/react-native';

The type for the props that can be passed to the <Card /> input components.

It is a subset of the React Native TextInputProps type.

1
type EvervaultInputProps = Omit<
2
  TextInputProps,
3
  'onChange' | 'onChangeText' | 'value' | 'defaultValue'
4
>;

ThreeDSecureState

1
import { type ThreeDSecureState } from '@evervault/react-native';

The type for the state returned from the useThreeDSecure hook.

Properties

sessionThreeDSecureSession | null

The 3DS session object.

isVisibleboolean

Whether or not the <ThreeDSecure.Frame /> component is visible.

start(sessionId: string, callbacks?: ThreeDSecureCallbacks) => void

Starts the 3DS authentication process for the given session ID.

cancel() => void

Cancels the current 3DS authentication process.

Migration Guide

If your app currently uses @evervault/evervault-react-native, follow the steps below to migrate to the new package.

Install `react-native-webview`

The react-native-webview package is now a peer dependency and will need to be installed as well.

## Using npm
npm install react-native-webview
## Using yarn
yarn add react-native-webview
## Using Expo
npx expo install react-native-webview

Update your imports

The package name has been updated to @evervault/react-native.

1
- import { EvervaultProvider } from '@evervault/evervault-react-native';
2
+ import { EvervaultProvider } from '@evervault/react-native';

Remove top-level function calls

In the previous version, you could call init() and encrypt() directly from the package.

These functions are no longer exposed at the top level. Instead:

Initializing the SDK is now done via the <EvervaultProvider /> component.
Encrypting data is now done via the encrypt() method returned from the useEvervault hook.

1
- import { init } from '@evervault/evervault-react-native';
2
+ import { EvervaultProvider } from '@evervault/react-native';
3
4
  function App() {
5
-   useEffect(() => {
6
-     init('team_id', 'app_id');
7
-   }, []);
8
9
    return (
10
+     <EvervaultProvider teamId="team_id" appId="app_id">
11
        <YourApp />
12
+     </EvervaultProvider>
13
    );
14
  }

1
- import { encrypt } from '@evervault/evervault-react-native';
2
+ import { useEvervault } from '@evervault/react-native';
3
4
  function App() {
5
+   const { encrypt } = useEvervault();
6
7
    async function handleEncrypt() {
8
      const encrypted = await encrypt('data');
9
    }
10
  }

Update Card props

In the previous version, you could pass styles to the <Card /> component via the style prop.

The Card component no longer renders a View, so you should move the styles to a parent or child View.

1
- <Card style={{ padding: 16 }} />
2
+ <View style={{ padding: 16 }}>
3
+   <Card />
4
+ </View>

The previous version also accepted acceptedBrands via the config prop. This has been moved top-level:

1
- <Card config={{ acceptedBrands: ['visa', 'mastercard'] }} />
2
+ <Card acceptedBrands={['visa', 'mastercard']} />

Finally, the initialValue prop has been renamed to defaultValues:

1
- <Card initialValue={{ name: 'John Doe' }} />
2
+ <Card defaultValues={{ name: 'John Doe' }} />

Rename Card.CVC to Card.Cvc

The Card.CVC prop has been renamed to Card.Cvc.

1
- <Card.CVC placeholder="CVC" />
2
+ <Card.Cvc placeholder="CVC" />