Methods

The WebView integration exposes createSession and startChallenge through the useBasisTheory3ds hook. The native integration exposes configure, createSession, and startAuthentication on BasisTheoryThreeDS, and is described in Native Methods.

Create Session

This method collects information for the device from a WebView on the background and sends it to the Basis Theory API, which then returns a newly created 3DS session.

Usage

import { BasisTheory3dsProvider, useBasisTheory3ds } from "@basis-theory/react-native-threeds";

const App = () => {
  return (
    <BasisTheory3dsProvider apiKey={"<API_KEY>"}>
      <MyApp />
    </BasisTheory3dsProvider>
  );
}

const MyApp = () => {
  const { createSession, startChallenge } = useBasisTheory3ds();

  //... rest of your component

  const session = await createSession({ tokenId: "<TOKEN_ID>" });
}

Parameters

The createSession method takes an object as parameter w/ the following attributes:

Attribute	Required	Type	Description
`tokenId`	false	string	The Basis Theory token id for the card token to be used
`tokenIntentId`	false	string	The Basis Theory token id for the card token intent to be used
`pan`	false	string	DEPRECATED The Basis Theory token id for the card token to be used

Either tokenId or tokenIntentId is required.

Return

The method returns an object with the following attributes:

Attribute	Type	Description
`id`	string	The created session `id`
`cardBrand`	string	The brand for the used card (i.e. Visa)
`additionalCardBrands`	array	Array of all brands the card was identified as (if co-badged).

Start Challenge

This method initiates the 3DS challenge process, if it was deemed necessary during the 3DS authentication. The challenge window will be displayed to the user in a WebView.

Usage

import { BasisTheory3dsProvider, useBasisTheory3ds } from "@basis-theory/react-native-threeds";

const App = () => {
  return (
    <BasisTheory3dsProvider apiKey={"<API_KEY>"}>
      <MyApp />
    </BasisTheory3dsProvider>
  );
}

const MyApp = () => {
  const { createSession, startChallenge } = useBasisTheory3ds();

  //... rest of your component

  const challengeCompletion = await startChallenge({
    acsChallengeUrl: "https://some-challenge-url.com",
    acsTransactionId: "5236966c-62be-417b-8f66-dbec6d87911d",
    sessionId: "9289231e-2c0b-4f38-92fa-dec3c586d58b",
    threeDSVersion: "2.2.0",
  });
}

Parameters

The startChallenge method takes in an object with the following attributes:

Attribute	Required	Type	Description
`acsChallengeUrl`	true	string	The URL for the challenge window. Available from the Authenticate endpoint response
`acsTransactionId`	true	string	The ACS transaction id. Available from the Authenticate endpoint response
`sessionId`	true	string	The created 3DS session id
`threeDSVersion`	true	string	The 3DS message version. Available from the Authenticate endpoint response
`windowSize`	false	string	The code for the pre-configured window size. See Challenge Window Sizes
`timeout`	false	number	The time in miliseconds to wait for challenge completion before considering it timed out. Defaults to 60000ms (1 minute)

Return

The method returns a boolean, with it being true if the challenge was able to completed, or false if an error or timeout occurred.

Challenge Window Sizes

WindowSize ID	Size
`01`	250px x 400px
`02`	390px x 400px
`03`	500px x 600px
`04`	600px x 400px
`05`	100% x 100%

Native Methods

These methods are available on BasisTheoryThreeDS and on each strategy in BasisTheoryThreeDSStrategies once native 3DS is enabled. No provider is needed. When the bank requires a challenge, the platform SDK presents it over the screen that is currently visible and dismisses it when the challenge ends.

import { useEffect, useState } from "react";
import { Button } from "react-native";
import { BasisTheoryThreeDS } from "@basis-theory/react-native-threeds";

const Checkout = ({ tokenId }) => {
  const [ready, setReady] = useState(false);

  useEffect(() => {
    BasisTheoryThreeDS.configure({
      apiKey: "<PUBLIC_API_KEY>",
      authenticationEndpoint: "<YOUR_AUTHENTICATION_ENDPOINT>",
    }).then(() => setReady(true));
  }, []);

  const pay = async () => {
    const session = await BasisTheoryThreeDS.createSession({ tokenId });
    const result = await BasisTheoryThreeDS.startAuthentication(session.id);
  };

  return <Button title="Pay" disabled={!ready} onPress={pay} />;
};

Configure

This method initializes the platform 3DS SDK. Call it once, before creating sessions.

Parameters

Attribute	Required	Type	Description
`apiKey`	true	string	The API Key used to identify the Application
`authenticationEndpoint`	true	string	Your 3DS authentication endpoint. The SDK sends it a `POST` request with `{ "sessionId": "<SESSION_ID>" }`
`authenticationEndpointHeaders`	false	object	Additional headers sent to your authentication endpoint, such as an `Authorization` header
`sandbox`	false	boolean	Runs the 3DS process against a sandbox environment, which must be enabled for your tenant. Remove it in production
`locale`	false	string	The default locale for the challenge UI, in `{language}-{country}` format

Return

The method returns an array of string warnings reported by the platform SDK, which is usually empty.

Create Native Session

This method collects the device data required for 3DS and creates a 3DS session. The platform SDK holds one session at a time: a new session replaces one that was created but never authenticated, for example when the user leaves checkout.

Parameters

Attribute	Required	Type	Description
`tokenId`	false	string	The Basis Theory token id for the card token to be used
`tokenIntentId`	false	string	The Basis Theory token intent id for the card token intent to be used

Provide exactly one of tokenId or tokenIntentId.

Return

Attribute	Type	Description
`id`	string	The created session `id`
`cardBrand`	string	The brand for the used card (i.e. Visa)
`additionalCardBrands`	array	Array of all brands the card was identified as (if co-badged)

Start Authentication

This method calls your authentication endpoint with the session id, presents the challenge if the bank requires one, and resolves when the authentication is complete.

Parameters

Parameter	Required	Type	Description
`sessionId`	true	string	The `id` returned by Create Native Session

Return

Attribute	Type	Description
`id`	string	The 3DS session `id`
`status`	string	The authentication result: `successful`, `attempted`, `failed`, `unavailable`, `rejected`, `decoupled_challenge`, or `informational`
`details`	string	Additional context about the result, such as why a challenge failed

A failed, cancelled, or timed-out challenge is a valid 3DS outcome, so the promise resolves with status: "failed" and the reason in details. decoupled_challenge means the issuer authenticates the cardholder outside your app. Subscribe to the 3ds.session.decoupled-challenge-notification webhook to learn when it completes, then get the outcome from your backend with Get Challenge Result. See Decoupled Challenge Authentication. informational means authentication wasn't requested. The promise only rejects on configuration, network, or SDK errors, including when no screen is visible to present the challenge on.

Native Errors

When a native method rejects, the error's code is one of these, on both platforms:

Code	Description
`INVALID_CONFIGURATION`	`configure` is missing `apiKey` or `authenticationEndpoint`, or received invalid configuration
`INITIALIZATION_FAILED`	The platform 3DS SDK failed to initialize
`NOT_CONFIGURED`	`createSession` or `startAuthentication` was called before `configure`
`SESSION_IN_PROGRESS`	A session is being created or authenticated. Wait for it to finish
`INVALID_SESSION_REQUEST`	`createSession` didn't receive exactly one of `tokenId` or `tokenIntentId`
`SESSION_CREATION_FAILED`	The session couldn't be created
`INVALID_SESSION`	`startAuthentication` received a session id other than the one last created
`NO_VIEW_CONTROLLER` (iOS) / `NO_ACTIVITY` (Android)	No visible screen to present the challenge on
`AUTHENTICATION_FAILED`	The authentication request or the platform SDK failed

Authentication Endpoint

The native SDKs call your authentication endpoint, which authenticates the session with your private API key using Authenticate Session. It differs from the WebView examples in two ways:

Request: the SDK sends a POST to the exact authenticationEndpoint URL, with the session id in the body: { "sessionId": "<SESSION_ID>" }.
Response: return the Authenticate Session result with camelCase keys, plus merchantName, purchaseAmount, and currency, which the SDK needs and Authenticate Session doesn't return. Android doesn't accept snake_case keys.

Request body
{
  "sessionId": "<SESSION_ID>"
}

Response
{
  "panTokenId": "<PAN_TOKEN_ID>",
  "threedsVersion": "2.2.0",
  "acsTransactionId": "<ACS_TRANSACTION_ID>",
  "dsTransactionId": "<DS_TRANSACTION_ID>",
  "sdkTransactionId": "<SDK_TRANSACTION_ID>",
  "acsReferenceNumber": "<ACS_REFERENCE_NUMBER>",
  "dsReferenceNumber": "<DS_REFERENCE_NUMBER>",
  "authenticationStatus": "successful",
  "authenticationStatusCode": "Y",
  "merchantName": "Example 3DS Merchant",
  "purchaseAmount": "80000",
  "currency": "826"
}

Every field except merchantName, purchaseAmount, and currency comes from the Authenticate Session result. For app sessions, that result also includes sdkTransactionId, which the native SDK generated when it created the session. Keep the rest of the result in the response, in camelCase.

Create Session​

Usage​

Parameters​

Return​

Start Challenge​

Usage​

Parameters​

Return​

Challenge Window Sizes​

Native Methods​

Configure​

Parameters​

Return​

Create Native Session​

Parameters​

Return​

Start Authentication​

Parameters​

Return​

Native Errors​

Authentication Endpoint​

Create Session

Usage

Parameters

Return

Start Challenge

Usage

Parameters

Return

Challenge Window Sizes

Native Methods

Configure

Parameters

Return

Create Native Session

Parameters

Return

Start Authentication

Parameters

Return

Native Errors

Authentication Endpoint