Skip to main content

SimplyConnect

Description​

The SimplyConnect module provides a high-level, pre-built payment interface that supports multiple payment methods, saved cards (UPOs), and alternative payment methods (APMs). It handles the full payment lifecycle, including session management, UI rendering, and 3D Secure authentication.

This module includes several components and hooks:

  • SimplyConnectScreen – the main container component that orchestrates the entire payment flow.
  • useCheckout – a hook that initializes the checkout session and retrieves available payment methods.
  • Context Providers (SimplyConnectContext, PaymentMethodCardContext) – manage shared state for payment methods and selection.
  • UI Components (PaymentMethodCard, MyPaymentMethods, SelectPaymentMethod, SaveCheckbox, WebView, DeleteButton).

useCheckout​

Overview​

Purpose - useCheckout is a custom hook that manages the initialization and configuration of the checkout process. It handles fetching available payment methods (merchant and user-specific) and setting up the transaction environment.

Where it is used - This hook is used at the start of the payment flow, typically in the main checkout screen.

Behavior

  • Fetches merchant payment methods.
  • Fetches user-saved payment methods (if a userTokenId is provided).
  • Sets up the nvPaymentMerchantSettings in the global Nuvei context.
  • Manages the initialization of the 3DS2 service.
  • Provides a loading state during the setup process.

What the hook does​

  1. Transaction Initialization

    • Accepts nvPaymentMerchantSettings and optional configuration parameters.
    • Updates the global Nuvei context with these settings.

  2. Fetching Payment Methods

    • Calls getMerchantPaymentMethods to retrieve methods supported by the merchant.
    • Calls getUserUpos to retrieve cards saved by the user (requires userTokenId).
    • Stores these methods in the SimplyConnectContext.

  3. 3DS2 Preparation

    • Retrieves 3DS2 configuration (directory server keys) from the merchant settings.
    • Initializes the 3DS2Service with these parameters.

  4. Session Management

    • Ensures a valid sessionToken is used for all subsequent API calls.

Data structure​

Request​

useCheckout parameters:

  • nvPaymentMerchantSettings: Object containing amount, currency, sessionToken, etc.
  • config: Optional configuration for 3DS2 UI and behavior.

Key functions​

initializeCheckout()

  • The main function that runs the initialization sequence (fetching methods and setting up services).

Integration​

import { useCheckout } from 'react-native-nuvei';

const { loading, error } = useCheckout(nvPaymentMerchantSettings);

SimplyConnectContext​

Overview​

Purpose - SimplyConnectContext provides a centralized state for the SimplyConnect flow. It stores available payment methods, selection state, and UI-related flags.

Responsibilities

  • Stores merchantPayments (available APMs and card options).
  • Stores userPayments (saved cards).
  • Tracks the currently selectedMethod (UPO or merchant method).
  • Manages isLoading and webviewUrl states.
  • Provides setter functions to update these values.

MyPaymentMethods​

Overview​

Purpose - The MyPaymentMethods component displays a list of the user’s active payment methods (saved credit cards or digital wallets).
It retrieves payment data from the SimplyConnectContext, filters active methods (upoStatus === 'enabled'), and renders a PaymentMethodCard for each one, wrapped in a PaymentMethodProvider.

Where it is used - In any screen that needs to display the user’s saved or active payment methods, such as a profile page or checkout screen.

What the component does​

  • Retrieves the user’s saved payment methods from context.
  • For each valid method:
    • Determines the card title which is the card number, depending on the payment type.
    • Selects the appropriate logo (Visa, MasterCard, PayPal, ..) or a fallback generic card icon.
    • Wraps each card in a PaymentMethodProvider and renders it using the PaymentMethodCard component.
  • Displays a section label (My payment methods) and renders the list of cards below it.
  • Returns null if there are no active methods or if userPayments is not available.

Data structure​

UserPaymentMethodType

export type UserPaymentMethodType = {
  userPaymentOptionId: number;
  upoName: string;
  paymentMethodName: PaymentMethodNames;
  upoStatus: UpoStatuses;
  upoRegistrationDate: string;
  upoRegistrationTime: string;
  expiryDate: string | undefined;
  depositSuccess: 'false' | 'true';
  withdrawSuccess: 'false' | 'true';
  billingAddress: {
    countryCode: string;
    email: string;
  };
  cccId: string | undefined;
  upoData:
    | undefined
    | {
        uniqueCC?: string;
        ccCardNumber?: string;
        cardProduct?: string;
        bin?: string;
        cardType?: string;
        ccExpMonth?: string;
        ccExpYear?: string;
        allowDcc?: string;
        secondaryBrand?: string;
        issuerCountry?: string;
        isDualBranded?: string;
        optionalWdType?: string;
        brand?: CardTypesEnum;
        ccNameOnCard?: string;
        lastUsedBrand?: CardTypesEnum;
        email?: string;
        vault_id?: string;
      };
  userTokenId: 'ran@sc';
  paymentMethodDisplayName?: { language: string; message: string }[];
};

SelectPaymentMethod​

Overview​

Purpose - The SelectPaymentMethod component displays the list of available merchant payment methods (those offered by the merchant for checkout).
It retrieves merchant payment data from the SimplyConnectContext, filters out excluded payment methods (using excludeMerchantMethods), and renders a PaymentMethodCard for each one inside a PaymentMethodProvider.

Where it is used - On checkout or payment setup screens where the user must select one of the available merchant payment options to proceed with the transaction.

What the component does​

  • Retrieves merchant payment methods from the SimplyConnectContext.
  • For each valid method:
    • Excludes methods defined in excludeMerchantMethods.
    • Determines the logo:
      • If the method is cc_card, apmgw_ACH, or apmgw_PayWithCrypto, uses a generic card icon (card.svg).
    • Extracts the title from the English entry (language === 'en') in paymentMethodDisplayName.
    • Replaces all .svg extensions in the logo URL with .png (if applicable).
  • Wraps the data inside a PaymentMethodProvider and renders it with a PaymentMethodCard.
  • Displays a section label — "Select your payment method".
  • Returns null if there are no merchant payment methods available.

Data structure​

MerchantPaymentMethod

export type MerchantPaymentMethod = {
  paymentMethod: PaymentMethodNames;
  paymentMethodDisplayName: {
    language: string;
    message: string;
  }[];
  countries: string[];
  currencies: string[];
  logoURL: string;
  fields: MerchantPaymentMethodFieldType[];
  openInExternalBrowser: 'false';
  blockedCards: [];
};

SimplyConnectScreen​

Overview​

Purpose - SimplyConnectScreen is a screen component that provides a complete payment UI for the SimplyConnect flow. It displays platform-specific quick-pay buttons (Google Pay / Apple Pay) when available, lists saved payment methods, allows selection of a payment method, shows a loading backdrop while operations are in progress and opens an embedded WebView for web interaction.

Where it is used - This component is used to present the full SimplyConnect payment flow (quick-pay buttons, saved payment methods, method selection and web-based redirections).

Behavior

  • Renders a full screen SafeAreaView with a scrollable content area.
  • Shows Google Pay button on Android when merchant supports ppp_GooglePay.
  • Shows Apple Pay button on iOS when merchant supports ppp_ApplePay.
  • Renders MyPaymentMethods (saved methods) and SelectPaymentMethod (manual selection).
  • Displays BackdropLoader while isLoading from SimplyConnect context is true.
  • Renders an embedded WebView for flows that require external pages or redirections.

Integration​

import { SimplyConnectScreen } from 'react-native-nuvei';

<SimplyConnectScreen />

WebView​

Overview​

Purpose - WebViewScreen is a component that displays a modal popup containing a WebView.
It is used to handle payment flows that require monitoring navigation events and performing actions based on URL changes.

Behavior

  • Opens a modal containing a full-screen webview.
  • Loads a dynamic URL provided by the SimplyConnect context.
  • Monitors navigation events to detect payment completion URLs (autoclose.html).
  • Checks the payment status when a completion URL is reached.
  • Calls success or failure callbacks based on the payment result.

Key function​

handleNavigationStateChange(navState: WebViewNavigation)

  • Triggered whenever the WebView changes navigation state.
  • Checks if the current URL matches any of the predefined completion URLs.
  • When matched:
    1. Verifies the payment using the checkPaymentStatus API.
    2. Invokes success or failure callbacks based on API response.

SaveCheckbox​

Overview​

Purpose - SaveCheckbox is a UI component that allows the user to decide whether their payment method should be saved for future use.

Behavior

  • Reads and updates the savePm state in the SimplyConnectContext.
  • Always starts unchecked when entering the payment flow.

PaymentMethodCard​

Overview​

Purpose - PaymentMethodCard is an interactive component representing a single payment method. It handles selection, displays card details/logos, and triggers the expansion of payment fields (for cards or APMs).

Behavioral Logic​

  • When selected, it highlights with a border and background color.
  • If it's a credit card method (cc_card), it expands to show the NuveiFields input form.
  • If it's a saved method (UPO), it allows direct payment or expansion for CVV input if required.
  • If it's an APM, it displays any required dynamic fields.

DeleteButton​

Overview​

Purpose - DeleteButton allows users to remove a saved payment method (UPO) from their account.

Behavior

  • Calls the deleteUpo API with the userPaymentOptionId.
  • On success, it triggers a refresh of the user's payment methods.