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.

1npm 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 component is used to securely collect cardholder 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.ExpiryMonth /> and <Card.ExpiryYear />
<Card.Cvc />
<Card.Field />

You don't 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. Use <Card.Row /> to place fields side by side. Each field accepts every TextInput prop except value, onChange, and onChangeText.

1<Card autoProgress onChange={setData}>
2  <Card.Number label="Card number" />
3  <Card.Row>
4    <Card.ExpiryMonth label="Month" />
5    <Card.ExpiryYear label="Year" />
6    <Card.Cvc label="CVC" autoProgress={false} />
7  </Card.Row>
8  <Card.Field name="postcode" label="Postcode" maxLength={8} />
9</Card>

With autoProgress set, focus moves to the next field after the current one is filled. Focus follows the order the fields first render in, and a field rendered later is added to the end.

Declare each field once. A second field of the same kind, such as another Card.Number, isn't rendered and logs a warning. You can't combine Card.Expiry with Card.ExpiryMonth and Card.ExpiryYear, and the month and year must be declared together. Otherwise, an error is logged and the new layout isn't rendered.

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. Possible values are 'american-express', 'visa', 'mastercard', 'discover', 'jcb', 'diners-club', 'unionpay', 'maestro', 'mir', 'elo', 'hipercard', 'hiper', 'szep', 'uatp', 'rupay'.
defaultValuesCardForm
Default values for the card fields.
- namestring
  The card holder name.
- numberstring
  The unencrypted card number field.
- expirystring
  The expiry date for the card. Takes the format MMYY
- cvcstring
  The unencrypted three (or four) digit CVC code for the card.
validationMode'onChange' | 'onBlur' | 'onTouched' | 'all'
The validation mode for the card fields. Defaults to all.
autoProgressboolean
Moves focus to the next field after the current one is filled. A field's own autoProgress prop takes precedence. Defaults to false.
onChange(payload: CardPayload) => void
A callback function that is called whenever the card data changes.
- card.nameString
  The card holder name.
- card.numberString
  The encrypted card number. This will only be present if the number is valid.
- card.brandString
  The brand that issued the card.
- card.lastFourString
  The last 4 digits of the card. This will only be present if the number is valid.
- card.binString
  The BIN for the card.
- card.expiry.monthString
  The month for the card expiry field.
- card.expiry.yearString
  The year for the card expiry field.
- card.cvcString
  The encrypted card CVC.
- card.errorsObject
  Validation errors related to the card details.
- card.isValidBoolean
  Whether or not there are any errors shown in the component.
- card.isCompleteBoolean
  Whether or not all of the fields have been filled out successfully with valid values.
The payload also includes fields, the encrypted values of the custom fields by name. A field that's empty or invalid is null. A Card component without custom fields doesn't report fields. Errors for custom fields are under errors.fields, by name.
onError(error: Error) => void
A callback function that is called when a native error occurs.

Ref

The Card component exposes an imperative handle using ref.

1import { useRef } from "react";
2import { Card } from "@evervault/react-native";
3
4function CardForm() {
5  const cardRef = useRef<Card>(null);
6
7  return (
8    <Card ref={cardRef}>
9      <Card.Number />
10    </Card>
11  );
12}

Methods

reset()() => void
Resets the form to its default values and state. Fields with a defaultValue start with it again.

<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.
labelstring
Text rendered above the field. It's also read out as the field's accessibility label.
labelStyleStyleProp<TextStyle>
The style of the label text.
errorMessagestring
Replaces the text of this field's error in the payload's errors.
patternstring
A regular expression the whole name must match.
defaultValuestring
The name the field starts with. A changed defaultValue only replaces a name the user hasn't changed.

The cardholder name has no fixed length, so it never auto-progresses.

<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 •).
labelstring
Text rendered above the field. It's also read out as the field's accessibility label.
labelStyleStyleProp<TextStyle>
The style of the label text.
autoProgressboolean
Moves focus to the next field after this one is filled. Overrides the Card component's autoProgress for this field.
errorMessagestring
Replaces the text of this field's error in the payload's errors.
unsupportedBrandMessagestring
Replaces the error text for a card brand that isn't in acceptedBrands.

<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.
labelstring
Text rendered above the field. It's also read out as the field's accessibility label.
labelStyleStyleProp<TextStyle>
The style of the label text.
autoProgressboolean
Moves focus to the next field after this one is filled. Overrides the Card component's autoProgress for this field.
errorMessagestring
Replaces the text of this field's error in the payload's errors.

<Card.ExpiryMonth /> and <Card.ExpiryYear />

Used as children of <Card /> to collect the expiry date as two separate fields. Use them instead of Card.Expiry, not alongside it.

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

Both fields write the same expiry, but the payload reports a single card.expiry, and an invalid date is reported under errors.expiry. The date is checked when either field loses focus, except when focus moves to the other field while it's still empty.

The month accepts 01 to 12. A four-digit year, such as one filled in by autofill, is shortened to its last two digits.

Props

placeholderstring
The placeholder text to display in the input field. Defaults to MM for the month and YY for the year.
labelstring
Text rendered above the field. It's also read out as the field's accessibility label.
labelStyleStyleProp<TextStyle>
The style of the label text.
autoProgressboolean
Moves focus to the next field after this one is filled. Overrides the Card component's autoProgress for this field.
errorMessagestring
Replaces the text of the expiry's error in the payload's errors. Either field can set it. If both do, the field declared later is used.

<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 •).
labelstring
Text rendered above the field. It's also read out as the field's accessibility label.
labelStyleStyleProp<TextStyle>
The style of the label text.
autoProgressboolean
Moves focus to the next field after this one is filled. The CVC advances after the max number of digits are entered (the max depends on the card brand). Overrides the Card component's autoProgress for this field.
errorMessagestring
Replaces the text of this field's error in the payload's errors.
optionalboolean
Makes the CVC optional. CVCs are still validated if provided. Defaults to false.
allow3DigitAmexboolean
Set it to false to require a 4-digit CVC for American Express cards. Defaults to true.

The CVC is validated against the card number, so its required length depends on the card brand.

<Card.Row />

Used as a child of <Card /> to place fields side by side. Each child takes an equal share of the row's width.

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

Props

styleStyleProp<ViewStyle>
The style of the row. Card.Row accepts every View prop.

<Card.Field />

Used as a child of <Card /> to collect your own, non-card data, such as a postcode or an email address. The value is encrypted and reported in the payload's fields, under the field's name.

1import { Card } from "@evervault/react-native";
2
3function CardForm() {
4  return (
5    <Card onChange={(payload) => console.log(payload.fields?.postcode)}>
6      <Card.Number />
7      <Card.Field
8        name="postcode"
9        label="Postcode"
10        pattern="[A-Z]{1,2}\d[A-Z\d]? ?\d[A-Z]{2}"
11        errorMessage="Enter a UK postcode"
12        required
13      />
14    </Card>
15  );
16}

A field that's empty or invalid is reported as null, and its error is reported under errors.fields, following the Card component's validationMode. The default error messages are This field is required and Please enter a valid value. A second field with the same name isn't rendered and logs a warning. A field without a name isn't rendered and also logs a warning. Changing a field's validation props clears its value and its error.

Props

nameRequiredstring
The key the field's encrypted value is reported under, in the payload's fields.
type'text' | 'email' | 'tel' | 'url' | 'number'
The kind of value the field takes. An email, url or number value must be valid for its type. Every type except text shows a matching keyboard. Defaults to text.
defaultValuestring
The value the field starts with. A changed defaultValue only replaces a value the user hasn't changed.
readOnlyboolean
Stops the user from changing the value. A read-only field is never invalid.
requiredboolean
Rejects an empty value.
patternstring
A regular expression the whole value must match. Doesn't apply to number fields.
minLengthnumber
The minimum length of the value. Doesn't apply to number fields.
maxLengthnumber
The maximum length of the value. With autoProgress set, focus moves to the next field after the value reaches this length.
minstring
The lowest value a number field takes.
maxstring
The highest value a number field takes.
stepstring
The steps a number value must keep to, counted from min.
errorMessagestring
Replaces the text of the field's error in the payload's errors.fields, for both a missing and an invalid value.
labelstring
Text rendered above the field. It's also read out as the field's accessibility label.
labelStyleStyleProp<TextStyle>
The style of the label text.
autoProgressboolean
Moves focus to the next field after the value reaches maxLength. Without a maxLength, the field doesn't auto-progress. Overrides the Card component's autoProgress for this field.
placeholderstring
The placeholder text to display in the input field.

<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 state object returned by 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.

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}

Props

styleStyleProp<ViewStyle>
Style applied to the WebView container.

Parameters

sessionRequiredstring
The 3D Secure session ID.
optionsThreeDSSessionOptions
The options for the 3DS authentication process.
- failOnChallengeboolean | () => Promise<boolean>
  If set to true (or a function that returns true), the authentication will fail if a challenge is required.
- onRequestChallenge(event: ThreeDSecureEvent) => void
  The requestChallenge event will be fired if the 3DS authentication process requires a challenge. If you'd like to fail the authentication, you should call preventDefault on the passed event.
- onSuccess() => void
  The 'success' event will be fired once the 3DS authentication process has been completed successfully. You should use this event to trigger your backend to finalize the payment. Your backend can use the Retrieve 3DS Session endpoint to retrieve the cryptogram for the session and complete the payment.
- onFailure(error: Error) => void
  The 'failure' event will be fired if the 3DS authentication process fails. You should use this event to handle the failure and inform the user and prompt them to try again. If the user cancels the 3DS authentication process this event will be fired.
- onError(error: Error) => void
  The error event will be fired if the component fails to load.

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.
- failOnChallengeboolean | () => Promise<boolean>
  If set to true (or a function that returns true), the authentication will fail if a challenge is required.
- onRequestChallenge(event: ThreeDSecureEvent) => void
  The requestChallenge event will be fired if the 3DS authentication process requires a challenge. If you'd like to fail the authentication, you should call preventDefault on the passed event.
- onSuccess() => void
  The 'success' event will be fired once the 3DS authentication process has been completed successfully. You should use this event to trigger your backend to finalize the payment. Your backend can use the Retrieve 3DS Session endpoint to retrieve the cryptogram for the session and complete the payment.
- onFailure(error: Error) => void
  The 'failure' event will be fired if the 3DS authentication process fails. You should use this event to handle the failure and inform the user and prompt them to try again. If the user cancels the 3DS authentication process this event will be fired.
- onError(error: Error) => void
  The error event will be fired if the component fails to load.