React

GitHub NPM

The React SDK is a thin wrapper around the JavaScript SDK. It allows you to add Evervault's UI components, such as the Card component, to any React app.

Getting Started

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

1npm install @evervault/react

Once installed, Initialize the SDK by wrapping your application with the EvervaultProvider component.

1import { EvervaultProvider } from "@evervault/react";
2
3export default function App() {
4  return (
5    <EvervaultProvider teamId="<TEAM_ID>" appId="<APP_ID>">
6      ...
7    </EvervaultProvider>
8  );
9}

Once you've added the <EvervaultProvider>, you can access the useEvervault() hook in its children. The useEvervault() hook returns an initialized instance of the JavaScript SDK, which includes the encrypt() function. The encrypt() function can be used to encrypt plaintext data in your application.

1import { useState } from "react";
2import { useEvervault } from "@evervault/react";
3
4export default function ChildComponent() {
5  const evervault = useEvervault();
6  const [message, setMessage] = useState("");
7
8  const handleSubmit = async (e) => {
9    e.preventDefault();
10    const encryptedMessage = await evervault.encrypt(message);
11    alert(encryptedMessage);
12  };
13
14  return (
15    <form onSubmit={handleSubmit}>
16      <input value={message} onChange={(e) => setMessage(e.target.value)} />
17      <button>Submit</button>
18    </form>
19  );
20}

Components

EvervaultProvider

Sets up a client for interacting with Evervault. You must provide a teamId and appId to the provider.

1<EvervaultProvider teamId={String} appId={String}>
2  {children}
3</EvervaultProvider>

Props

teamIdRequiredString
The unique identifier for your Team.
appIdRequiredString
The unique identifier for your App.
onLoadError(error: unknown) => void
A callback function that is called if the SDK fails to load. Use the isScriptLoadError utility to determine the cause of the error.
loadTimeoutNumber
The timeout in milliseconds for the SDK to load. Defaults to 15000 (15s).

The EvervaultProvider accepts a ref that exposes a reload() method that you can use to reload the script if it fails.

Ref Methods

reload() => void
Attempts to reload the Evervault script. Typically called in response to an onLoadError event.

Card

Card API

The Card component collects and encrypts card data for Card Collection in a completely PCI-compliant environment. You can build it in two ways.

Composable: compose the fields yourself as children of <Card>. They render in the order you write them, so you control the layout.
Config: configure the Card component with props on <Card>. The fields render in a fixed order.

Declare the Card component's fields as children of <Card>. They render in the order you write them, and Card.Row places fields side by side.

1import { Card, EvervaultProvider } from "@evervault/react";
2
3export function Checkout() {
4  const handleChange = (payload) => {
5    console.log(payload.card.number, payload.fields.postcode);
6  };
7
8  return (
9    <EvervaultProvider teamId="<TEAM_ID>" appId="<APP_ID>">
10      <Card autoProgress onChange={handleChange}>
11        <Card.Holder label="Name on card" />
12        <Card.Number label="Card number" />
13        <Card.Row>
14          <Card.ExpiryMonth label="Month" />
15          <Card.ExpiryYear label="Year" />
16          <Card.Cvc label="CVC" redact autoProgress={false} />
17        </Card.Row>
18        <Card.Field name="postcode" label="Postcode" maxLength={8} required />
19      </Card>
20    </EvervaultProvider>
21  );
22}

A <Card> with children renders the <ev-card> element from the JavaScript SDK, so it follows the same rules. It mounts with the client from the nearest EvervaultProvider.

Children can change after the component mounts, and the details a customer has already entered are kept.

Card component field components

Each field is declared as its own component. Declare each field once. A duplicate field is ignored and logs a warning.

Components

Card.Holder
The cardholder name field.
Card.Number
The card number field.
Card.Expiry
The expiry field, with the month and year in a single input.
Card.ExpiryMonth
The expiry month field of a split expiry.
Card.ExpiryYear
The expiry year field of a split expiry.
Card.Cvc
The CVC field.
Card.Field
A custom field for your own, non-card data.
Card.Row
Places the fields side by side, sharing the width of the component.

Any other child is ignored, and the console logs a warning that names it. A Card component with children ignores the fields prop and logs a warning.

With autoProgress set, focus moves to the next field in the order the fields are declared, including fields inside a Card.Row. Backspace in an empty field moves focus back to the previous one.

Split expiry

The expiry can be declared as a single Card.Expiry or as separate Card.ExpiryMonth and Card.ExpiryYear fields. The month and year can be placed independently of each other, but a warning is logged if other fields are declared between them.

1<Card>
2  <Card.Number />
3  <Card.Row>
4    <Card.ExpiryMonth />
5    <Card.ExpiryYear />
6  </Card.Row>
7  <Card.Cvc />
8</Card>

A split expiry still reports a single expiry in the card payload, under card.expiry, and its errors under errors.expiry. When the date is invalid, both fields are marked invalid.

You can't combine the two forms. A Card component that declares a month without a year, a year without a month, or either one alongside Card.Expiry logs an error and isn't rendered. If the component is already mounted, it keeps its previous fields.

Custom fields

Card.Field collects your own, non-card data inside the component, such as a postcode or an email address. It's styled by the same theme as the card fields. Each value is encrypted before it leaves the iframe.

1<Card onChange={(payload) => console.log(payload.fields.postcode)}>
2  <Card.Number />
3  <Card.Field
4    name="postcode"
5    label="Postcode"
6    autoComplete="postal-code"
7    autoCapitalize="characters"
8    pattern="[A-Z]{1,2}\d[A-Z\d]? ?\d[A-Z]{2}"
9    errorMessage="Enter a UK postcode"
10    required
11  />
12</Card>

The encrypted values are reported in the fields object of the card payload, by name. A field that's empty or invalid is reported as null, and its error is reported under errors.fields as required or invalid.

Validation follows the same rules as HTML form validation. Errors show after the customer leaves the field, or on every field when you call the validate() ref method. The Card component isn't complete until every custom field is valid.

Changing a field's validation rules clears its value, so a value is only ever validated against the rules it was entered under. This prevents a script on your page from changing a pattern repeatedly to determine what was typed.

A field without a name, or with the same name as another field, isn't rendered and logs a warning. Themes can target the field as [ev-name="field-<name>"].

Card component props

Component-wide settings are props of <Card>. A field's own prop takes precedence over the same setting on <Card>.

Props

themeObject
The theme to use for the component. See the styling section for more information.
colorSchemestring
The root color-scheme of the iframe document. For a seamless transparent background, use the same color scheme as the parent document. Only read when the Card component mounts.
iconsBoolean | Record<brand, string>
Displays an icon for the detected card brand. You can customize icons by passing an object with the brand as the key and the icon URL as the value.
autoFocusBoolean
Focuses the Card component when it mounts. A field's own autoFocus prop takes precedence.
autoProgressBoolean
Moves focus to the next field after the current one is complete. A field's own autoProgress prop takes precedence.
autoCompleteBoolean
Enables browser autocomplete for every field. A field's own autoComplete prop takes precedence.
acceptedBrandsstring[]
The card brands to accept. If not set, all brands are accepted. Possible values are visa, mastercard, american-express, diners-club, discover, jcb, unionpay, maestro, elo, mir, hiper, hipercard, szep, uatp, rupay.
customBrandsCustomBrand[]
Custom card brand definitions created with brands.create. Custom brands are always accepted, even when acceptedBrands is set. See the custom card brands section for usage examples.
defaultValuesObject
Default values for the component's fields.
- defaultValues.namestring
  Default value for the cardholder name field. Setting a new value replaces the name the customer has entered.
- defaultValues.fieldsRecord<string, string>
  Default values for custom fields, by name. A field's own defaultValue prop takes precedence.
translationsObject
Customizes the text shown in the component. A field's own label, placeholder, and errorMessage props take precedence.
- translations.name.label
  The label for the name field.
- translations.name.placeholder
  The placeholder for the name field.
- translations.name.errors.invalid
  The error message for the name field when the value is invalid.
- translations.name.errors.regex
  The error message for when the name field fails regex validation.
- translations.number.label
  The label for the number field.
- translations.number.placeholder
  The placeholder for the number field.
- translations.number.errors.invalid
  The error message for the number field when the value is invalid.
- translations.number.errors.unsupportedBrand
  The error message for a card brand that isn't accepted.
- translations.expiry.label
  The label for the expiry field.
- translations.expiry.placeholder
  The placeholder for the expiry field.
- translations.expiry.errors.invalid
  The error message for an invalid expiry, for both the combined and the split expiry.
- translations.expiryMonth.label
  The label for the expiry month field.
- translations.expiryMonth.placeholder
  The placeholder for the expiry month field.
- translations.expiryYear.label
  The label for the expiry year field.
- translations.expiryYear.placeholder
  The placeholder for the expiry year field.
- translations.cvc.label
  The label for the CVC field.
- translations.cvc.placeholder
  The placeholder for the CVC field.
- translations.cvc.errors.invalid
  The error message for the CVC field when the value is invalid.
- translations.field.errors.required
  The error message for every custom field that's required but empty. Defaults to This field is required.
- translations.field.errors.invalid
  The error message for every custom field with an invalid value. Defaults to Please enter a valid value.
- translations.fields.<name>Object
  The label, placeholder, errors.required, and errors.invalid text of a single custom field, by name. Takes precedence over translations.field.
validationObject
Customizes the validation of the fields.
- validation.name.regexRegExp
  A regex pattern that the name must match in order to be considered valid. The pattern prop of Card.Holder takes precedence.
- validation.cvc.optionalBoolean
  When set to true, CVCs aren't required. CVCs are still validated if provided. The optional prop of Card.Cvc takes precedence.
- validation.fields.<name>Object
  Validation rules for a single custom field, by name. Accepts required, pattern, minLength, maxLength, min, max, and step, which work like the Card.Field props of the same name. A field's own props take precedence.
agentToolsObject
Registers WebMCP tools inside the iframe so browser agents can interact with the component. Accepts the same object as the agentTools prop of a Card component configured with props. Only read when the component mounts.
preloadBoolean
Hides the component when loaded. Call the show() ref method to show it. Only read when the component mounts.
onChange(payload: Object) => void
Called whenever the component's state 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.
onComplete(payload: Object) => void
Called after every field, including custom fields, holds a valid value, and again on each change while every field stays valid. Receives the same payload as onChange.
onValidate(payload: Object) => void
Called when the fields are validated with the validate() ref method. Receives the same payload as onChange.
onSwipe(payload: Object) => void
Called when a card reader is used. The component must have focus for the card reader to be detected. The payload has the encrypted number, the brand, lastFour, bin, and expiry with its month and year, and the cardholder's firstName and lastName if detected.
onFocus(event: { field: string, name?: string, data: Object }) => void
Called when a field gains focus. field is name, number, expiry, cvc, or field for a custom field, whose name is in name. Both fields of a split expiry report expiry.
onBlur(event: { field: string, name?: string, data: Object }) => void
Called when a field loses focus. Receives the same event as onFocus.
onKeyDown(event: { field: string, name?: string, data: Object }) => void
Called on a key-down event within a field. Receives the same event as onFocus.
onKeyUp(event: { field: string, name?: string, data: Object }) => void
Called on a key-up event within a field. Receives the same event as onFocus.
onReady() => void
Called after the component loads and is ready to be used.
onError() => void
Called when the component fails to load, including when the Evervault client fails to load.

The card payload also includes fields, the encrypted values of the custom fields by name. Errors for custom fields are under errors.fields, by name, as required or invalid.

The redactCVC and allow3DigitAmexCVC props, and an autoComplete object by field, are deprecated on a Card component with children. They still apply to fields that don't set their own redact, allow3DigitAmex, or autoComplete prop.

Card component field props

Each field component takes its own settings as props. A field's own prop takes precedence over the same setting on <Card>.

1<Card.Number
2  label="Card number"
3  unsupportedBrandMessage="This card isn't accepted"
4/>

Props

labelstring
The text of the field's label.
placeholderstring
The field's placeholder.
tooltipstring
Text shown beside the label. Themes can target it as [ev-tooltip].
autoFocusBoolean
Focuses the field when the component renders. If more than one field sets it, the first is focused. Focus doesn't move after the customer starts entering details.
autoProgressBoolean
Moves focus to the next field after this one is complete. Set it to false to turn auto-progress off for this field only. The cardholder name doesn't auto-progress. The CVC advances after the max number of digits are entered (the max depends on the card brand).
autoCompleteBoolean
Enables browser autocomplete for the field.
errorMessagestring
Replaces the text of the field's error. On a split expiry, either the month or the year can set it. On the card number field, the error for a card brand that isn't accepted is set separately, with unsupportedBrandMessage.
defaultValuestring
Card.Holder only. Fills in the cardholder name. The value only applies while the field is untouched, and never replaces a name the customer has typed.
patternstring
Card.Holder only. A regular expression the whole cardholder name must match.
iconPositionstring
Card.Number only. Added to the field as the ev-icon-position attribute, so your theme can position the brand icon.
unsupportedBrandMessagestring
Card.Number only. Replaces the error text for a card brand that isn't accepted.
redactBoolean
Card.Cvc only. Masks the CVC as it's typed.
optionalBoolean
Card.Cvc only. Makes the CVC optional. CVCs are still validated if provided.
allow3DigitAmexBoolean
Card.Cvc only. Set it to false to require a 4-digit CVC for American Express cards. Accepted by default.

Custom field props

Card.Field takes label, placeholder, tooltip, autoFocus, autoProgress, errorMessage, and defaultValue, as well as the following props.

Props

nameRequiredstring
The field's name. Its value is reported under this key in the fields object of the card payload.
typestring
The input type. One of text, email, tel, url, number, or date. Defaults to text.
requiredBoolean
Rejects an empty value.
patternstring
A regular expression the whole value must match. Doesn't apply to number or date fields.
minLengthnumber
The minimum length of the value. Doesn't apply to number or date 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 minimum value of a number or date field.
maxstring
The maximum value of a number or date field.
stepstring
The step of a number or date field, counted from min. Defaults to 1, measured in days for a date field. Use any to accept any value.
readOnlyBoolean
Prevents the customer from editing the value. A read-only field isn't validated.
autoCompleteBoolean | string
An autocomplete token, such as postal-code, or true or false to turn autofill on or off.
autoCapitalizestring
One of characters, words, sentences, or none. Capitalizes the value as it's typed, so characters lets a lowercase value match an uppercase pattern. Only applies to text and tel fields.
inputModestring
The inputmode.
spellCheckBoolean
Enables the browser's spell checking.
enterKeyHintstring
The enterkeyhint.

An email or url field must also hold a valid email address or URL. An empty required field shows This field is required, and an invalid value shows Please enter a valid value, unless the field sets an errorMessage. You can also change this text with the translations prop.

Ref methods

The Card component accepts a ref that exposes the following methods.

1const card = useRef(null);
2
3<Card ref={card} preload onValidate={(payload) => console.log(payload.isValid)}>
4  <Card.Number />
5</Card>;
6
7card.current.validate();
8card.current.show();

Ref methods

validate() => void
Validates every field and shows any errors. The result is passed to onValidate.
show() => void
Shows a Card component loaded with the preload prop. If it's called before the component mounts, the component mounts visible.

ThreeDSecure

The ThreeDSecure component can be used instead of the useThreeDSecure hook when you want more control over how and where the 3D Secure iframe is displayed. In order to use the component you must first create a 3D Secure session on your backend.

1import { ThreeDSecure } from "@evervault/react";
2
3export function MyComponent() {
4  const handleSuccess = () => {
5    console.log("3D Secure authentication complete");
6  };
7
8  return (
9    <ThreeDSecure session="tds_visa_123456789" onSuccess={handleSuccess} />
10  );
11}

Props

sessionRequiredString
The 3D Secure session ID. A 3D Secure session can be created using the API.
themeObject
Allows you to customize the appearance of the component. Note: You can't customize the appearance of the iframe content itself. This is controlled by the card issuer.
colorSchemestring
Allows you to set the root color-scheme for the iframe document. For a seamless transparent background, use the same color scheme as the parent document.
size{ width: string, height: string }
This size of the 3D Secure iframe. Card issuers are required to support content at 250x400, 390x400, 500x600, 600x400. The default size is 500x600.
failOnChallengeBoolean | () => Boolean | () => Promise<Boolean>
If set to true, the component will fail 3DS authentication when a challenge is requested and no challenge will be shown. Alternatively, you can provide a function which will be called when a challenge is requested. If the function returns true 3DS authentication will fail, if it returns false the challenge will be shown.
onSuccessFunction
The 'success' event will be fired once the 3D Secure 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.
onFailureFunction
The 'failure' event will be fired if the 3D Secure authentication process fails. You should use this event to handle the failure and inform the user and prompt them to try again.
onErrorFunction
The error event will be fired if the component fails to load.
onReadyFunction
The ready event will be fired once the component has fully loaded and is ready to be displayed. This is often used to show a loading state while the component loads.

Reveal

The Reveal component allows you to display previously encrypted card data to your users in plaintext in a secure iframe hosted by Evervault. See Card Reveal for more information.

1import { useMemo } from "react";
2import { Reveal } from "@evervault/react";
3
4export function MyComponent() {
5  const request = useMemo(() => {
6    return new Request("<YOUR_ENDPOINT>");
7  }, []);
8
9  return (
10    <Reveal request={request}>
11      <Reveal.Text path="$.card.number" />
12      <Reveal.CopyButton path="$.card.number" text="Copy Number" />
13    </Reveal>
14  );
15}

Props

requestRequiredRequest
The request to use to fetch the encrypted data.
onReadyFunction
Triggered when the component has fully loaded and is ready to be shown.
onErrorFunction
Triggered when the component fails to load.

Reveal.Text

Creates a Reveal Text consumer component. The Reveal Text consumer allows you to render a selected field from the request response. This component must be rendered as a child of the Reveal component.

1import { useMemo } from "react";
2import { Reveal } from "@evervault/react";
3
4export function MyComponent() {
5  const request = useMemo(() => {
6    return new Request("<YOUR_ENDPOINT>");
7  }, []);
8
9  return (
10    <Reveal request={request}>
11      <Reveal.Text path="$.user.pin" />
12    </Reveal>
13  );
14}

Props

themeObject
Allows you to completely customize the appearance of the component.
colorSchemestring
Allows you to set the root color-scheme for the iframe document. For a seamless transparent background, use the same color scheme as the parent document.
pathRequiredString
A JSON path selector for the response field you want to display.
formatObject
Allows you to use regex matching to format the field value.
- regexRequiredString
  The regex statement to match against the value.
- replaceRequiredString
  The text to replace the value with. You can use $ to reference matched regex groups.

Reveal.CopyButton

Creates a Reveal Copy Button consumer component. This renders a button which when clicked will copy a response field to the users clipboard. This component must be rendered as a child of the Reveal component.

1import { useMemo } from "react";
2import { Reveal } from "@evervault/react";
3
4export function MyComponent() {
5  const request = useMemo(() => {
6    return new Request("<YOUR_ENDPOINT>");
7  }, []);
8
9  return (
10    <Reveal request={request}>
11      <Reveal.CopyButton path="$.card.number" />
12    </Reveal>
13  );
14}

Props

pathRequiredString
A JSON path selector for the response field you want to copy.
themeObject
Allows you to completely customize the appearance of the component.
colorSchemestring
Allows you to set the root color-scheme for the iframe document. For a seamless transparent background, use the same color scheme as the parent document.
formatObject
Allows you to use regex matching to format the field value.
- regexRequiredString
  The regex statement to match against the value.
- replaceRequiredString
  The text to replace the value with. You can use $ to reference matched regex groups.
onCopy() => void
A callback function that is called when the button is clicked.

Creates a Pin component which allows you to collect and encrypt pin numbers in a completely PCI-compliant environment.

1import { Pin, themes } from "@evervault/react";
2const theme = themes.clean();
3
4export function MyComponent() {
5  const handleChange = (details) => {
6    console.log(details);
7  };
8
9  return (
10    <div>
11      <Pin theme={theme} onChange={handleChange} />
12    </div>
13  );
14}

Props

themeObject
The theme to use for the Pin.
colorSchemestring
Allows you to set the root color-scheme for the iframe document. For a seamless transparent background, use the same color scheme as the parent document.
autoFocusBoolean
If set to true, the component will automatically steal focus when it mounts.
lengthNumber
Change the length of the pin number.
modenumeric | alphanumeric
If set to 'alphanumeric' the pin number will also accept letters as input.
inputType"number" | "text" | "password"
Sets the type attribute of the underlying input elements used to capture the pin. Defaults to "number".
onChange(payload: Object) => void
Triggered whenever the component's state is updated.
- valueString
  The encrypted pin number.
- isCompleteBoolean
  Whether or not the pin number field is complete.
onComplete(payload: Object) => void
Triggered when the pin number field has been fully filled out by the user.
- valueString
  The encrypted pin number.
- isCompleteBooleanBoolean
  Whether or not the pin number field is complete.
onReadyFunction
Triggered when the component has fully loaded and is ready to be shown.
onErrorFunction
Triggered when the component fails to load. If you want to respond to validation errors you should use the change event instead.

Hooks

useEvervault

The useEvervault hook is accessible in children of the EvervaultProvider, and returns an initialized instance of the Evervault JavaScript SDK. One of the functions included in the returned object is encrypt(), which can be passed any plaintext data structure.

1const evervault = useEvervault();

.encrypt()

Encrypts data using Evervault Encryption. Evervault Strings can be used across all of our products. It is accessible on the returned value from the useEvervault() hook. To encrypt data using the React.js SDK, simply pass a String or an Object into the evervault.encrypt() function.

The encrypted data can be passed to your server and stored in your database as normal. It can also be used with any of Evervault's other services.

1function MyComponent() {
2  const evervault = useEvervault();
3
4  const handleEncrypt = async () => {
5    const encrypted = await evervault.encrypt("Hello, world!");
6    console.log(encrypted);
7  };
8
9  return <button onClick={handleEncrypt}>Encrypt</button>;
10}

Parameters

dataRequiredString | Object | Array | File | Blob
The data to encrypt.

.decrypt()

Allows you to decrypt a previously encrypted piece of data using a client side token. The token is a time bound token for decrypting data. The token can be generated using our backend SDKs or through our REST API.

The payload must be the same payload that was used to create the token and expires in a maximum of 10 minutes depending on the expiry set when creating the token.

The payload can be any String or Object and it will be returned, decrypted, in the same form.

1const evervault = useEvervault();
2const data = await evervault.encrypt("Hello, world!");
3const decrypted = await evervault.decrypt("[client-side-token]", data);

Parameters

tokenRequiredString
A valid client-side token with permissions to decrypt the data.
dataRequiredString | Object
The encrypted data to decrypt.

.brands.create()

Creates a custom card brand definition that can be passed to the customBrands prop on Card. Use this to add support for card networks that aren't included in Evervault's built-in brand list.

1const acmeBrand = evervault.brands.create("acme-card", {
2  numberValidationRules: {
3    ranges: [9900, [88000, 88999]],
4    lengths: [16],
5  },
6  securityCodeValidationRules: {
7    lengths: [3],
8  },
9})

Parameters

nameRequiredstring
A unique identifier for the brand. This value is returned in the localBrands array of the card change payload.
optionsRequiredObject
Configuration for the custom brand.
- options.numberValidationRulesRequiredObject
  Rules used to validate card numbers for this brand.
- options.securityCodeValidationRulesRequiredObject
  Rules used to validate the CVC for this brand.
- options.iconSrcstring
  A URL for the brand's icon. Displayed in the card component when a matching card number is entered.

useThreeDSecure

The useThreeDSecure hook can be used in combination with the Evervault API to perform 3D Secure authentication. In order to use the hook you must first create a 3D Secure session on your backend and pass it to your frontend. The hook will manage displaying the 3D Secure iframe inside of a modal window and handle the authentication process.

Note: If you want more control over how and where the 3D Secure iframe is displayed you can use the ThreeDSecure component instead.

See 3D Secure for more information.

1import { Card, useThreeDSecure } from "@evervault/react";
2import { createThreeDSSession, finalizePayment } from "./api";
3
4function Checkout() {
5  const threeDSecure = useThreeDSecure();
6
7  const handlePay = async () => {
8    const session = await createThreeDSSession();
9    threeDSecure.start(session, {
10      onSuccess: () => {
11        finalizePayment(session);
12      },
13    });
14  };
15
16  return (
17    <>
18      <Card />
19      <button onClick={handlePay}>Pay</button>
20    </>
21  );
22}

Options

themeObject
Allows you to customize the appearance of the component. Note: You can't customize the appearance of the iframe content itself. This is controlled by the card issuer.
colorSchemestring
Allows you to set the root color-scheme for the iframe document. For a seamless transparent background, use the same color scheme as the parent document.
size{ width: string, height: string }
This size of the 3D Secure iframe. Card issuers are required to support content at 250x400, 390x400, 500x600, 600x400. The default size is 500x600.
failOnChallengeBoolean | () => Boolean | () => Promise<Boolean>
If set to true, the component will fail 3DS authentication when a challenge is requested and no challenge will be shown. Alternatively, you can provide a function which will be called when a challenge is requested. If the function returns true 3DS authentication will fail, if it returns false the challenge will be shown.

threeDSecure.start()

The start function is used to begin the 3D Secure authentication process.

Parameters

sessionRequiredString
The 3D Secure session ID. A 3D Secure session can be created using the API.
options.onSuccessFunction
The 'success' event will be fired once the 3D Secure 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.
options.onFailureFunction
The 'failure' event will be fired if the 3D Secure authentication process fails. You should use this event to handle the failure and inform the user and prompt them to try again.
options.onErrorFunction
The error event will be fired if the component fails to load.
options.onReadyFunction
The ready event will be fired once the component has fully loaded and is ready to be displayed. This is often used to show a loading state while the component loads.

threeDSecure.update()

The update function updates the options passed to the active 3D Secure instance without restarting the authentication flow.

Parameters

options.themeObject
Allows you to customize the appearance of the component. Note: You can't customize the appearance of the iframe content itself. This is controlled by the card issuer.
options.colorSchemestring
Allows you to set the root color-scheme for the iframe document. For a seamless transparent background, use the same color scheme as the parent document.
options.size{ width: string, height: string }
This size of the 3D Secure iframe. Card issuers are required to support content at 250x400, 390x400, 500x600, 600x400. The default size is 500x600.
options.failOnChallengeBoolean | () => Boolean | () => Promise<Boolean>
If set to true, the component will fail 3DS authentication when a challenge is requested and no challenge will be shown. Alternatively, you can provide a function which will be called when a challenge is requested. If the function returns true 3DS authentication will fail, if it returns false the challenge will be shown.

Utilities

isScriptLoadError

The isScriptLoadError function can be used to determine if an error was caused by the Evervault.js browser script failing to load.

1<EvervaultProvider teamId="..." appId="..." onLoadError={(error) => {
2  if (isScriptLoadError(error)) {
3    console.error("Failed to load for reason:", error.code, error.message);
4  } else {
5    console.error("An error occurred:", error);
6  }
7}}>

Known Error Codes

window_not_available
The window object isn't available.
head_or_body_not_found
The document's head or body element wasn't found to mount the Evervault script tag.
script_error
The <script> tag encountered an error when loading the Evervault script.
timed_out
The script failed to load before the specified loadTimeout period.
evervault_not_available
The Evervault object wasn't available after the script loaded.
amd_module_not_exported
When using the AMD module loader, the Evervault module wasn't available after the script loaded.
amd_module_error
The AMD module loader encountered an error when loading the Evervault module.

Content Security Policy (CSP)

If you are using a Content Security Policy (CSP), you will need to add the following directives to allow the Evervault SDK to function correctly.

1script-src https://js.evervault.com;
2connect-src https://keys.evervault.com https://api.evervault.com;
3frame-src https://ui-components.evervault.com;