monext-react-native-sdk

⚠️ Beta / work in progress — this wrapper is under active development. APIs, native dependency versions, and behavior may still change without notice. Avoid using it in production until a stable release is announced.

React Native library exposing the Monext native payment sheet on Android and iOS through a TurboModule. There is no payment logic on the JS side — this package only validates arguments and bridges to the native Monext SDKs (com.monext.sdk on Android, Monext SPM package on iOS), which own the actual payment flow.

Overview

Both native SDKs ship a drop-in payment sheet that handles the full checkout flow (card entry, 3DS, Apple Pay/Google Pay) once your backend has created a session — this package exposes that same sheet to React Native, imperatively (presentPaymentSheet) or declaratively (<PaymentButton>):

Requirements

• React Native with the New Architecture enabled (TurboModules + Codegen). There is no legacy-bridge fallback.
• Android 8.0 (API 26)+.
• iOS 16.0+.
• react/react-native as peer dependencies (any version compatible with the New Architecture).
• An active Monext merchant account and a backend able to call the Monext Retail API — see Backend integration.

Install

npm install monext-react-native-sdk

Enable the New Architecture in the host React Native app because this module is implemented as a TurboModule.

Apple Pay setup (optional)

To offer Apple Pay through applePayConfiguration, configure it once in the host app before it can be used:

1. Create a Merchant ID in the Apple Developer portal.
2. Generate a Payment Processing Certificate for that Merchant ID (submit the CSR) and send it to Monext, following Monext's own onboarding documentation.
3. In Xcode, enable the Apple Pay capability under Signing & Capabilities for the iOS app target, and select the Merchant ID created above.
4. Pass applePayConfiguration (buttonLabel/buttonStyle) in MnxtSDKContext to control the button's appearance — see ApplePayConfiguration.

Backend integration

There is no payment logic on the JS or native side beyond presenting the sheet and reporting its result — session creation and final status checks happen on your backend, which is the only place allowed to hold Monext credentials:

1. Your backend creates a payment session through the Monext Retail API (Session Create) using your BasicToken/merchant ID. Never call the Monext Retail API directly from the app, and never ship those credentials in the app bundle.
2. Your backend returns the resulting sessionToken to the app, which passes it to presentPaymentSheet/PaymentButton.
3. After the sheet resolves, treat its PaymentSheetResult as a UI-level hint only; confirm the final outcome from your backend via the Retail API's GET Session (or your webhook/notification flow) before granting the purchase.

Usage

There are two ways to present the payment sheet: imperatively with presentPaymentSheet, or declaratively with the <PaymentButton> component.

Imperative

import { presentPaymentSheet } from 'monext-react-native-sdk';

const result = await presentPaymentSheet(sessionToken, {
  environment: 'sandbox',
  config: { language: 'FR' },
});

if (result.result === 'completed' && result.state === 'paymentSuccess') {
  // payment completed
}

Declarative

import { PaymentButton } from 'monext-react-native-sdk';

<PaymentButton
  sessionToken={sessionToken}
  context={{ environment: 'sandbox', config: { language: 'FR' } }}
  onResult={(result) => {
    if (result.result === 'completed' && result.state === 'paymentSuccess') {
      // payment completed
    }
  }}
  onError={(error) => {
    // Strongly recommended: handle presentation errors gracefully
    console.error('Payment sheet failed:', error);
  }}
>
  {({ isPresenting }) => (
    <Text>{isPresenting ? 'Processing...' : 'Checkout'}</Text>
  )}
</PaymentButton>;

API

presentPaymentSheet

presentPaymentSheet(sessionToken: string, context: MnxtSDKContext): Promise<PaymentSheetResult>

Presents the native payment sheet full-screen (a dedicated Activity on Android, a modal UIHostingController on iOS) and resolves once the user completes, cancels, or the native SDK returns an error. Only one payment sheet can be presented at a time; calling this again while one is already open rejects with E_PAYMENT_IN_PROGRESS.

Before calling native, presentPaymentSheet validates sessionToken (trimmed, must be non-empty) and context.environment (must be 'production'/'sandbox', case-insensitive) itself and rejects with a MonextError — see Errors — without a native round-trip if either is invalid.

PaymentButton

<PaymentButton
  sessionToken={sessionToken}
  context={context}
  onResult={(result: PaymentSheetResult) => void}
  onError={(error: unknown) => void}
  style={pressableStyle}
  disabled={boolean}
  testID={string}
  accessibilityLabel={string}
>
  {({ disabled, isPresenting }) => content}
</PaymentButton>

| Prop | Type | Required | Notes | |---|---|---|---| | sessionToken | string | no | The button is inactive (tap is a no-op) while empty/unset. | | context | MnxtSDKContext | yes | | | onResult | (result: PaymentSheetResult) => void | yes | Called when the sheet resolves (completed or dismissed). | | onError | (error: unknown) => void | no | Called if presentPaymentSheet rejects. Strongly recommended in production to avoid silent failure handling (defaults to console.error). | | children | ReactNode \| (state: PaymentButtonRenderProps) => ReactNode | yes | The button's content or a render prop ({ disabled, isPresenting }) => ReactNode for loading/disabled UX. | | style | PressableProps['style'] | no | Forwarded to the underlying Pressable. | | disabled | boolean | no | Forces the button inactive in addition to the sessionToken check. | | testID | string | no | Forwarded to the underlying Pressable. | | accessibilityRole | AccessibilityRole | no | Defaults to 'button'. | | accessibilityState | AccessibilityState | no | Merged with the button state; disabled and busy always reflect the actual presentation state. | | accessibilityLabel | string | no | Forwarded to the underlying Pressable. | | accessibilityHint | string | no | Forwarded to the underlying Pressable. |

While a sheet is being presented, further taps are ignored until it resolves — presentPaymentSheet itself rejects with E_PAYMENT_IN_PROGRESS for genuinely concurrent calls (e.g. from a second, independent PaymentButton). The button updates accessibilityState={{ disabled: true, busy: true }} while presenting.

MnxtSDKContext

| Field | Type | Required | Notes | |---|---|---|---| | environment | 'production' \| 'sandbox' | yes | Case-insensitive. Rejects with E_INVALID_ENVIRONMENT if set to any other value. | | config | MnxtSDKConfiguration | no | | | appearance | Appearance | no | | | googlePayConfiguration | GooglePayConfiguration | no | Android only. | | applePayConfiguration | ApplePayConfiguration | no | iOS only. |

MnxtSDKConfiguration

| Field | Type | Notes | |---|---|---| | language | string | e.g. 'FR', 'EN'. |

Appearance

All fields are optional; omitted fields fall back to the native SDK's defaults.

| Field | Type | Notes | |---|---|---| | primaryColor / onPrimaryColor | string | Hex color, e.g. '#0057FF'. | | secondaryColor / onSecondaryColor | string | | | backgroundColor / onBackgroundColor | string | | | surfaceColor / onSurfaceColor | string | | | confirmationColor / onConfirmationColor | string | | | errorColor | string | | | pendingColor | string | Android only — no iOS equivalent. | | textfieldLabelColor | string | | | textfieldTextColor | string | | | textfieldBorderColor | string | | | textfieldBorderSelectedColor | string | | | textfieldBackgroundColor | string | | | textfieldAccessoryColor | string | | | buttonRadius | number | | | cardRadius | number | | | textfieldRadius | number | | | textfieldStroke | number | | | textfieldStrokeSelected | number | | | paymentMethodShape | PaymentMethodShape ('round' | 'square') | Case-insensitive. Any other value falls back to 'round'. | | headerTitle | string | | | headerBackgroundColor / onHeaderBackgroundColor | string | | | backButtonText | string | |

GooglePayConfiguration (Android)

| Field | Type | Notes | |---|---|---| | theme | GooglePayTheme ('light' | 'dark') | Case-insensitive. Any other value falls back to 'dark'. | | type | GooglePayButtonType ('buy' | 'donate' | 'book' | 'checkout' | 'order' | 'subscribe' | 'pay' | 'plain') | Case-insensitive. Any other value falls back to 'plain'. |

ApplePayConfiguration (iOS)

| Field | Type | Notes | |---|---|---| | buttonLabel | ApplePayButtonLabel ('buy' | 'book' | 'checkout' | 'donate' | 'subscribe' | 'setup' | 'plain') | Case-insensitive, '_' ignored. Any other value falls back to 'plain'. | | buttonStyle | ApplePayButtonStyle ('black' | 'white' | 'whiteOutline' | 'whiteoutline') | Case-insensitive, '_' ignored. Any other value falls back to 'black'. |

PaymentSheetResult

| Field | Type | Notes | |---|---|---| | result | 'completed' \| 'dismissed' | Whether the user completed a flow or dismissed the sheet before finishing. | | state | PaymentSheetState? | Native SDK payment state (e.g. 'paymentSuccess'). |

PaymentSheetState

Canonical union of possible native payment states across Android and iOS:

export type PaymentSheetState =
  | 'paymentSuccess'
  | 'paymentFailure'
  | 'paymentPending'
  | 'tokenExpired'
  | 'paymentCanceled'
  | 'paymentSheetDismissedByUser'
  | 'paymentIncomplete';

| State | Platform | Description | |---|---|---| | 'paymentSuccess' | Both | Payment completed successfully. | | 'paymentFailure' | Both | Payment process failed. | | 'paymentPending' | Both | Payment is pending asynchronous confirmation. | | 'tokenExpired' | Both | The payment session token has expired. | | 'paymentCanceled' | Both | Payment was canceled. | | 'paymentSheetDismissedByUser' | iOS | Payment sheet was explicitly dismissed by the user (iOS native event). | | 'paymentIncomplete' | Android | Payment process is incomplete (Android only). |

All types are re-exported from the package entry point alongside presentPaymentSheet.

Errors

presentPaymentSheet rejects the returned Promise (instead of resolving) for programmer errors and unrecoverable native failures. Every rejection is a MonextError (also passed to PaymentButton's onError) exposing the same { code, message } shape regardless of whether it originated in JS or natively. Unknown native failures are normalized to E_PAYMENT_SHEET; code is one of the exported MonextErrorCodes:

| Code | Origin | Meaning | |---|---|---| | E_INVALID_SESSION_TOKEN | JS | sessionToken was empty or whitespace-only, checked before any native call. | | E_INVALID_ENVIRONMENT | JS | context.environment was missing or not 'production'/'sandbox' (case-insensitive), checked before any native call. | | E_PAYMENT_IN_PROGRESS | Native (Android + iOS) | A payment sheet is already being presented. | | E_NO_ACTIVITY | Native (Android only) | No host Activity was available to present on. | | E_NO_VIEW_CONTROLLER | Native (iOS only) | No view controller was available to present on. | | E_PAYMENT_SHEET | Native (Android only) | The native payment sheet reported an unrecoverable error. iOS has no equivalent path today: a failing iOS payment resolves the Promise with result: 'completed', state: 'paymentFailure' instead of rejecting. |

Import MonextErrorCodes for typed comparisons instead of hardcoding strings:

import { presentPaymentSheet, MonextErrorCodes } from 'monext-react-native-sdk';

try {
  await presentPaymentSheet(sessionToken, context);
} catch (error) {
  if (error instanceof Error && 'code' in error && error.code === MonextErrorCodes.PAYMENT_IN_PROGRESS) {
    // ...
  }
}

Platform notes

• Android — presentPaymentSheet launches a dedicated Compose Activity (startActivityForResult) that renders the native PaymentSheet(...). The Promise resolves/rejects from an ActivityEventListener once that Activity finishes.
• iOS — presentPaymentSheet presents a SwiftUI view wrapped in a UIHostingController over the current top view controller. Presentation and the SwiftUI result callback are sequenced to avoid a present/dismiss race.

Development

This repository includes Jest unit tests for the JS API and PaymentButton. The example-app/, which depends on this package via file:.., is the integration target for manual native testing:

npm install         # installs deps and builds this package
npm run typecheck   # tsc --noEmit against src/
npm test            # unit tests for the JS API and PaymentButton
npm run android     # runs example-app on Android
npm run ios         # runs example-app on iOS (run `pod install` in example-app/ios first)
npm --prefix example-app test

The Android bridge also has JVM unit tests for context parsing, payment-result mapping, cancellation, native errors and the delayed-launch lifecycle guard. For bridge or payment-flow changes, test both platforms manually through example-app, including cancellation and error paths, not just the happy path.