Hooks

useGetCardDetails

Overview

useGetCardDetails returns a memoized async function that retrieves metadata for a card. The source of the card and merchant data is selected through moduleType:

• ModuleType.FIELDS retrieves details for the card currently entered in NuveiFields.
• ModuleType.CHECKOUT retrieves details for the card currently selected in Simply Connect.

The result can include the card brand, card type, prepaid status, issuing country, issuing bank, BIN, and last four digits. Card details are requested explicitly when the returned function is called; this hook replaces the former card-details event.

Enable card-detail retrieval

The feature is disabled by default. Enable it on the root provider before using the hook:

import { EnvironmentEnum, NuveiProvider } from 'react-native-nuvei';

<NuveiProvider
  environment={EnvironmentEnum.STAGING}
  getCardDetailsEnabled={true}
>
  <App />
</NuveiProvider>

Signature

useGetCardDetails(moduleType: ModuleType): () => Promise<
  | CardDetails
  | {
      status: ResponseStatuses.ERROR;
      errCode: number;
      reason: string | null;
    }
>

Parameter	Type	Description
moduleType	ModuleType	Selects whether the hook reads its card and merchant data from Nuvei Fields (FIELDS) or Simply Connect (CHECKOUT).

Nuvei Fields behavior

With ModuleType.FIELDS, the hook reads:

• The current card number from NuveiFieldsContext.
• merchantId, merchantSiteId, and sessionToken from the NuveiFields transaction details.

It validates the card number and sends it to the card-details API with the merchant settings.

import {
  ModuleType,
  ResponseStatuses,
  useGetCardDetails,
} from 'react-native-nuvei';

const getCardDetails = useGetCardDetails(ModuleType.FIELDS);

const handleFieldsCardDetails = async () => {
  const response = await getCardDetails();

  if (response.status === ResponseStatuses.ERROR) {
    console.error(response.reason);
    return;
  }

  console.log(response.brand, response.cardType);
};

Use this mode inside NuveiProvider with a rendered NuveiFields component so the hook can access the current card and transaction details.

Simply Connect behavior

With ModuleType.CHECKOUT, the hook reads the merchant configuration and selected payment method from the Simply Connect contexts. It supports:

• A card entered through the Select method flow, using its card number.
• A saved card from My methods, using its userPaymentOptionId.

import {
  ModuleType,
  ResponseStatuses,
  useGetCardDetails,
} from 'react-native-nuvei';

const getCardDetails = useGetCardDetails(ModuleType.CHECKOUT);

const handleSelectedCardDetails = async () => {
  const response = await getCardDetails();

  if (response.status === ResponseStatuses.ERROR) {
    console.error(response.reason);
    return;
  }

  console.log(response.brand, response.issuerCountry);
};

Use this mode while Simply Connect has a selected card. Alternative payment methods are not supported.

Error handling

The returned function resolves with status: 'ERROR' and a reason when:

• getCardDetailsEnabled is false.
• No supported card or saved-card identifier is available.
• A supplied card number is invalid.
• The API request fails or times out.

It throws Merchant settings not found. when the settings required by the selected module are unavailable. Handle both returned errors and thrown configuration errors:

try {
  const response = await getCardDetails();
  if (response.status === ResponseStatuses.ERROR) {
    console.error(response.reason);
  }
} catch (error) {
  console.error(error);
}

useCreatePayment

Overview

useCreatePayment returns a function that creates a direct payment and handles 3D Secure authentication when required. Use it when you want to supply the complete payment request yourself instead of using an SDK payment UI.

The hook runs the create-payment flow with isCreatePayment: true and RequestSource.DIRECT. It supports frictionless 3DS, native 3DS2 challenges, and web-based challenges.

Signature

const createPayment = useCreatePayment();

createPayment(
  nvPayment: NVPaymentBody,
  forceWebChallenge: boolean,
  onSuccess: (response: any) => void,
  onError: (error: any) => void
): Promise<void>

Parameter	Type	Description
nvPayment	NVPaymentBody	Complete transaction configuration, including merchant identifiers, session token, and paymentOption.
forceWebChallenge	boolean	Forces a web-based 3DS challenge when a challenge is required. Defaults to false.
onSuccess	(response: any) => void	Called with the approved payment response, including after a successful 3DS challenge.
onError	(error: any) => void	Called when initialization fails, the payment is declined, card blocking applies, or another error occurs.

Use onSuccess and onError as the authoritative payment result. The returned promise covers the initial async orchestration and does not itself return the payment response; for a challenge flow, the final callback can run after that promise resolves.

Payment flow

1. Checks the selected card against any blockCards rules configured on NuveiProvider.
2. Initializes 3D Secure using the supplied paymentOption and transaction settings.
3. Sends the payment through the client-payment endpoint.
4. Calls onSuccess immediately for an approved frictionless payment.
5. Opens the required native or web challenge for redirected 3DS flows, then calls onSuccess after successful completion.
6. Calls onError for initialization errors, declined payments, blocked cards, and thrown errors.

Integration

import {
  useCreatePayment,
  type NVPaymentBody,
} from 'react-native-nuvei';

const createPayment = useCreatePayment();

const handlePayment = async () => {
  const payment: NVPaymentBody = {
    sessionToken: 'YOUR_SESSION_TOKEN',
    merchantId: 'YOUR_MERCHANT_ID',
    merchantSiteId: 'YOUR_MERCHANT_SITE_ID',
    amount: '10.00',
    currency: 'USD',
    paymentOption: {
      card: {
        cardNumber: '4111111111111111',
        cardHolderName: 'John Doe',
        expirationMonth: '12',
        expirationYear: '30',
        CVV: '123',
      },
    },
  };

  await createPayment(
    payment,
    false,
    (response) => console.log('Payment approved:', response),
    (error) => console.error('Payment failed:', error)
  );
};

The hook must be called from a component inside NuveiProvider.

useAuthenticate3d

Overview

useAuthenticate3d returns a function that performs direct 3D Secure authentication without creating the payment. Use it when authentication and payment are separate steps in your integration.

It uses the same 3DS orchestration as useCreatePayment, but runs with isCreatePayment: false. Consequently, it sends the client request through the Auth3D endpoint instead of the create-payment endpoint.

Signature

const authenticate3d = useAuthenticate3d();

authenticate3d(
  nvPayment: NVPaymentBody,
  forceWebChallenge: boolean,
  onSuccess: (response: any) => void,
  onError: (error: any) => void
): Promise<void>

The parameters and 3DS challenge behavior are the same as for useCreatePayment. The difference is the resulting transaction: useAuthenticate3d authenticates the cardholder, whereas useCreatePayment creates the payment.

Integration

import {
  useAuthenticate3d,
  type NVPaymentBody,
} from 'react-native-nuvei';

const authenticate3d = useAuthenticate3d();

const handleAuthentication = async (payment: NVPaymentBody) => {
  await authenticate3d(
    payment,
    false,
    (response) => console.log('Authentication approved:', response),
    (error) => console.error('Authentication failed:', error)
  );
};

As with useCreatePayment, the hook checks configured card-blocking rules, handles frictionless and challenge-based 3DS flows, and must be called from a component inside NuveiProvider.