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 used to initialize the SimplyConnect checkout configuration, save settings/callbacks globally, and return a trigger function to launch the payment screen flow.

Where it is used - Initiated in the parent component/screen where checkout is started.

What the hook does

1. Saves Configuration and Callbacks
   • Stores settings (forceWebChallenge, etc.), the customer's countryCode, custom i18n label overrides, payment result callbacks, and optional form-event callbacks in the SDK contexts.
2. Returns Checkout Trigger Function
   • Returns a function: (nvPayment: NVPaymentCheckout) => void.
   • When this returned function is invoked with the current transaction details (sessionToken, amount, currency, etc.), it validates the settings/parameters, updates the transaction details in the context, and triggers the navigate() function to open the checkout payment screen.

Data structure

Arguments

The useCheckout hook accepts the following parameters:

useCheckout(
  settings: UseCheckoutSettingsType,
  countryCode: string,
  navigate: () => void,
  onSuccess: () => void,
  onFail: (error: { errorCode?: number; reason: string }) => void,
  callbacks: {
    onPaymentFormChange?: (payload: OnPaymentFormChangePayload) => void;
    onFormValidated?: (payload: OnFormValidatedPayload) => void;
  } | null,
  checkoutI18NFields?: i18NFieldsType,
)

Parameter	Type	Required	Description
settings	UseCheckoutSettingsType	Yes	Checkout configuration containing options such as forceWebChallenge.
countryCode	string	Yes	ISO 2-letter country code of the user.
navigate	() => void	Yes	Callback function to trigger navigation to the SimplyConnect screen.
onSuccess	() => void	Yes	Callback invoked when the payment transaction completes successfully.
onFail	(error) => void	Yes	Callback invoked when the payment transaction fails.
callbacks	{ onPaymentFormChange?, onFormValidated? } | null	No	Event callbacks for payment-form interaction and validation. Pass null when no event callbacks are needed.
checkoutI18NFields	i18NFieldsType	No	Optional dictionary of custom translated labels and placeholders.

useCheckout registers the supplied functions in SimplyConnectContext inside a useEffect. The hook itself does not emit form events: the active card or alternative-payment-method field components retrieve the registered callbacks from context and emit them as the customer interacts with the form.

onPaymentFormChange

Called when a Simply Connect payment field gains or loses focus.

type OnPaymentFormChangePayload = {
  pm: string;
  label: string;
  action: 'focus' | 'blur';
  oldValue: string;
  newValue: string;
  validation: string | null;
  paste: boolean;
};

• pm identifies the selected payment method.
• label is the localized field label.
• validation contains the current field error, or null when valid.
• paste reports whether the value associated with a blur event was pasted.
• Sensitive card-number values are masked.

How it works internally:

1. The active payment-field component handles its own focus and blur events. Text inputs and dropdowns both use the same public payload shape.
2. pm comes from the selected merchant or saved payment method, while label comes from the localized card label or the dynamic field caption.
3. Field components keep the last reported value in a ref. This becomes oldValue; the current context value becomes newValue.
4. The component evaluates its current field validation and places the error text in validation, or null when valid. Card-number values are masked before the callback is invoked.
5. Text fields detect a likely paste when the input grows by more than one character in a single change. The flag is reported with the blur event and then cleared.
6. The event is emitted on focus and blur, not on every keystroke. This gives integrations interaction milestones without exposing a stream of sensitive input changes.

onFormValidated

Called when the form validity or set of invalid fields changes:

type OnFormValidatedPayload = {
  isFormValid: boolean;
  invalidFields: string[];
};

For card forms, invalidFields uses card field identifiers such as ccNameOnCard, ccCardNumber, ccExpYear, and ccCVV. For alternative payment methods, it contains the invalid dynamic field names supplied by that payment method.

How it works internally depends on the active Simply Connect form:

1. New card – the credit-card component calculates all field errors and includes any merchant card-blocking error. Internal card keys are mapped to the public cc... identifiers.
2. Saved card – only fields that still require customer input are evaluated, such as CVV and an expired card date.
3. Alternative payment method – DynamicFields checks the required values defined by the selected method and returns their original field names in invalidFields. Dropdown initialization is guarded to avoid emitting an intermediate duplicate while its default value is being applied.
4. Each form sets isFormValid to true only when its invalid-field list is empty.
5. Each form keeps the last emitted validity and invalid-field list in a ref. onFormValidated runs only when that snapshot changes, rather than on every render or keystroke.
6. The event is informational: it does not submit the payment or navigate away from Simply Connect.

Return Value

Returns a launcher function: (nvPayment: NVPaymentCheckout) => void.

The nvPayment argument must satisfy:

type NVPaymentCheckout = {
  sessionToken: string;
  merchantId: string;
  merchantSiteId: string;
  amount: string;
  currency: string;
  clientRequestId?: string;
  billingAddress?: BillingAddress;
  shippingAddress?: ShippingAddress;
  userDetails?: UserDetails;
  requestTimeout?: number;
};

Integration & Usage

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

// 1. Initialize the hook with settings and navigation handler
const startCheckout = useCheckout(
  { forceWebChallenge: false },
  'US',
  () => navigation.navigate('SimplyConnectScreen'),
  () => console.log('Payment Successful!'),
  (error) => console.log('Payment Failed:', error.reason),
  {
    onPaymentFormChange: (payload) => {
      console.log('Field event:', payload);
    },
    onFormValidated: ({ isFormValid, invalidFields }) => {
      console.log('Form valid:', isFormValid, invalidFields);
    },
  },
  customI18nLabels
);

// 2. Trigger the payment flow when the user is ready to pay
const handlePay = () => {
  const nvPayment = {
    sessionToken: 'SESSION_TOKEN_FROM_SERVER',
    merchantId: 'MERCHANT_ID',
    merchantSiteId: 'MERCHANT_SITE_ID',
    amount: '100.00',
    currency: 'USD',
  };
  
  startCheckout(nvPayment);
};

---

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.

---

useGetCreditCardFieldsErrors

Overview

Purpose - useGetCreditCardFieldsErrors is a utility hook that validates credit card fields using the current SimplyConnect i18n settings and validation rules.

What the hook does

• Retrieves the current simplyConnectI18NSettings from NuveiContext.
• Validates the input values for Cardholder Name, CVV, Card Number, and Expiry Date.
• Returns validation error messages (cvvError, dateError, nameError, numberError) aligned with configured localized error strings.

Data structure

Usage:

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

const getErrors = useGetCreditCardFieldsErrors();

const { cvvError, dateError, nameError, numberError } = getErrors(
  cardHolder,
  cvv,
  cardNumber,
  expiry,
  isValidCardType,
  cvvLengthArray
);

---

Card Validation and Blocking (blockCards)

SimplyConnect supports restricting or blocking specific credit/debit card types, brands, or issuing countries using the blockCards rules array configured in NuveiProvider.

How it works

When the user enters a card number in the credit card input form (either for a new card or a saved card/UPO):

1. Rule Evaluation Trigger

   • As the user inputs a valid card pattern, a debounced check calls cardDetailsHandler().
   • The hook temporarily blocks the payment flow (MerchantCardProps.BLOCKED = 'true') while validating the card to prevent premature submissions.

2. Fetching Card Details

   • The SDK calls the getCardDetails() API to fetch card properties such as card brand, card type (Credit or Debit), prepaid status, issuer country, and issuer bank.

3. Rule Matching

   • The returned card properties are evaluated against the blockCards array.
   • If any rule matches (indicating the card is blocked):
     • The Pay button is disabled (MerchantCardProps.BLOCKED = 'true').
     • A customized error message (either from simplyConnectI18NSettings.errorMessageCustomisation or dynamically generated from the matched rule) is shown directly under the card number field.
   • If no rules match:
     • The block is removed, allowing the payment to proceed.