React Native

Installation

Our React Native SDK is distributed via npm, and can be installed using your preferred package manager. The react-native-webview package is a peer dependency and will need to be installed as well.

bash npm install @evervault/react-native react-native-webview@13

Compatibility

Our React Native SDK requires React Native 0.76 or higher. We recommend upgrading if possible.

If you are unable to upgrade, you will need to use our legacy React Native SDK.

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

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.

1import { EvervaultProvider } from "@evervault/react-native";
2
3function 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.

1import { Card, type CardPayload } from "@evervault/react-native";
2import { Button, Form } from "@your/ui";
3
4function 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.

1import { ThreeDSecure, useThreeDSecure } from "@evervault/react-native";
2import { createThreeDSecureSession } from "@your/api";
3import { Button, Form, Modal } from "@your/ui";
4
5function 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.

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

Props

teamIdRequired
The Team ID found in the Evervault Dashboard.
appIdRequired
The App ID found in the Evervault Dashboard.

<Card />

The Card compnent is used to securely collect card holder data from your users.

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

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

acceptedBrandsRequiredCardBrandName[]
An array of card brands that are accepted. If not provided, all brands are accepted.
defaultValuesRequiredCardForm
Default values for the card fields.
onChangeRequired(payload: CardPayload) => void
A callback function that is called whenever the card data changes.
validationModeRequired'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.

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

Props

placeholderstring
The placeholder text to display in the input field.

<Card.Number />

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

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

Props

placeholderstring
The placeholder text to display in the input field.
obfuscateValueboolean | string
If true, all but the first 6 characters of the card number will be obfuscated. If a string is provided, it will be used as the obfuscation character (defaults to •).

<Card.Expiry />

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

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

Props

placeholderstring
The placeholder text to display in the input field.

<Card.Cvc />

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

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

Props

placeholderstring
The placeholder text to display in the input field.
obfuscateValueboolean | string
If true, all of the CVC will be obfuscated. If a string is provided, it will be used as the obfuscation character (defaults to •).

<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

sessionRequiredstring
The 3D Secure session ID.

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

1import { ThreeDSecure, useThreeDSecure } from "@evervault/react-native";
2import { createThreeDSSession } from "@your/api";
3import { Button, Form, Modal } from "@your/ui";
4
5function 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}

Options

themeObject
Allows you to customize the appearance of the component.

Parameters

sessionRequiredstring
The 3D Secure session ID.
optionsThreeDSSessionOptions
The options for the 3DS authentication process.

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.

1import { useEvervault } from "@evervault/react-native";
2import { Button, Text, TextInput, View } from "react-native";
3
4function 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

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

Parameters

dataRequiredstring | number | boolean | object | array
The data to encrypt.

useThreeDSecure

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

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

Options

failOnChallengeboolean | () => Promise<boolean>
If set to true (or a function that returns true), the authentication will fail if any sessions require a challenge. Can be overridden on a per-session basis by the failOnChallenge option passed to the start() method.

Returns

start

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.
optionsThreeDSSessionOptions
The options for the 3DS authentication process.

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.

V2 Migration Guide

If your app currently uses the older @evervault/evervault-react-native package, you can follow our migration guide to upgrade to the new package.

React Native

Compatibility

Props

Props

Props

Props

Props

Props

Props

Options

Parameters

Parameters

Options

Parameters

On this page