React Native SDK

The official Plexy React Native SDK exposes one JavaScript API backed by the native iOS and Android SDKs. Use it to render Drop-in or individual payment components while your backend creates sessions, fetches payment methods, and verifies the final payment status.

This guide targets @plexy/react-native 2.x.

Requirements

React Native 0.71+

iOS 15.0+

Android 7.0 (API 24)+

A backend endpoint that creates Plexy sessions

Installation

Copy install command: npm install @plexy/react-native

iOS setup

Install pods after adding the package:

Android setup

The SDK is autolinked. For Google Pay, also follow the shared Google Pay setup.

Expo

The SDK is not compatible with Expo Go because it includes native modules. Use Expo prebuild or a custom dev client:

The package includes an Expo config plugin. Use merchantIdentifier there only for native Apple Pay entitlements. The runtime checkout configuration uses applepay.merchantID.

{
  "expo": {
    "plugins": [
      [
        "@plexy/react-native",
        {
          "merchantIdentifier": "merchant.money.plexy.example"
        }
      ]
    ]
  }
}

SDK shape

PlexyCheckout is a provider component. It receives the SDK config, a session or paymentMethods, and lifecycle callbacks. usePlexyCheckout() must be called only from a child rendered inside PlexyCheckout.

<PlexyCheckout config={checkoutConfig} session={session} onComplete={onComplete} onError={onError}>
  <PayButton />
</PlexyCheckout>

Inside PayButton, call start('dropin') to open Drop-in. You can also start a specific payment method with its type, for example start('scheme') or start('googlepay'), when that method is present in the session payment methods.

Base configuration

Use APSE as the default live region:

import type { Configuration } from '@plexy/react-native';

function buildCheckoutConfig(returnUrl: string): Configuration {
  return {
    environment: 'live-apse',
    clientKey: process.env.EXPO_PUBLIC_PLEXY_CLIENT_KEY!,
    returnUrl,
    countryCode: 'KZ',
    locale: 'ru-KZ',
    amount: { value: 10000, currency: 'KZT' },
    analytics: { enabled: false },
    card: {
      holderNameRequired: false,
    },
  };
}

Shopper locale

locale controls checkout language and regional formatting, for example ru-KZ, kk-KZ, or en-US. It is not a currency setting. Currency is configured only in amount.currency, for example KZT.

Test and live

Keep the SDK environment on live-apse. For test transactions, use the test clientKey in the app and the matching test x-api-key on your backend. For production, use the live APSE key pair. The backend still calls https://api.plexypay.com/v2/sessions; do not send live-apse in the /v2/sessions request body.

Sessions flow

In Sessions flow, your backend creates a session and returns id and sessionData to the app. The app passes both values to PlexyCheckout.

import React, { useCallback, useMemo, useState } from 'react';
import { ActivityIndicator, Alert, Button, Text, View } from 'react-native';
import {
  PlexyCheckout,
  PlexyDropIn,
  ResultCode,
  usePlexyCheckout,
} from '@plexy/react-native';
import type {
  Configuration,
  PlexyComponent,
  PlexyError,
  SessionConfiguration,
  SessionsResult,
} from '@plexy/react-native';

type CheckoutState = {
  session: SessionConfiguration;
  returnUrl: string;
};

function buildCheckoutConfig(returnUrl: string): Configuration {
  return {
    environment: 'live-apse',
    clientKey: process.env.EXPO_PUBLIC_PLEXY_CLIENT_KEY!,
    returnUrl,
    countryCode: 'KZ',
    locale: 'ru-KZ',
    amount: { value: 10000, currency: 'KZT' },
    analytics: { enabled: false },
    dropin: {
      showRemovePaymentMethodButton: true,
    },
    card: {
      holderNameRequired: false,
      showStorePaymentField: true,
    },
  };
}

async function createSessionOnBackend(returnUrl: string): Promise<SessionConfiguration> {
  const response = await fetch('https://your-backend.example.com/api/sessions', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      amount: { value: 10000, currency: 'KZT' },
      countryCode: 'KZ',
      returnUrl,
    }),
  });

  if (!response.ok) {
    throw new Error(`Session request failed: ${response.status}`);
  }

  const data = await response.json();
  return { id: data.id, sessionData: data.sessionData };
}

function PayButton() {
  const { start, isReady } = usePlexyCheckout();

  return (
    <Button
      title="Pay 100 KZT"
      disabled={!isReady}
      onPress={() => start('dropin')}
    />
  );
}

export function CheckoutScreen() {
  const [checkoutState, setCheckoutState] = useState<CheckoutState | null>(null);
  const [loading, setLoading] = useState(false);

  const prepareCheckout = useCallback(async () => {
    setLoading(true);
    try {
      const returnUrl = await PlexyDropIn.getReturnURL();
      const session = await createSessionOnBackend(returnUrl);
      setCheckoutState({ session, returnUrl });
    } catch (error) {
      Alert.alert('Checkout error', String(error));
    } finally {
      setLoading(false);
    }
  }, []);

  const config = useMemo(
    () => checkoutState ? buildCheckoutConfig(checkoutState.returnUrl) : null,
    [checkoutState]
  );

  const onComplete = useCallback(
    (result: SessionsResult, component: PlexyComponent) => {
      const authorised = result.resultCode === ResultCode.authorised;
      component.hide(authorised);

      if (authorised) {
        Alert.alert('Payment authorised');
      } else {
        Alert.alert('Payment result', result.resultCode);
      }

      // Always confirm the final status on your backend through a webhook
      // or by checking the session/payment status before fulfilling the order.
    },
    []
  );

  const onError = useCallback(
    (error: PlexyError, component: PlexyComponent) => {
      component.hide(false);
      Alert.alert('Payment error', error.message);
    },
    []
  );

  if (!checkoutState || !config) {
    return (
      <View>
        {loading ? <ActivityIndicator /> : null}
        <Button title="Start checkout" onPress={prepareCheckout} disabled={loading} />
      </View>
    );
  }

  return (
    <PlexyCheckout
      config={config}
      session={checkoutState.session}
      onComplete={onComplete}
      onError={onError}
    >
      <View>
        <Text>Order total: 100 KZT</Text>
        <PayButton />
      </View>
    </PlexyCheckout>
  );
}

Creating a session

Create sessions from your backend only. The app should send the return URL and order context to your backend; the backend adds merchantAccount, authenticates with x-api-key, and calls Plexy.

const returnUrl = await PlexyDropIn.getReturnURL();
const session = await createSessionOnBackend(returnUrl);

Your backend response to the app must include:

{
  "id": "CS123...",
  "sessionData": "..."
}

Pass those values as:

const session: SessionConfiguration = {
  id: response.id,
  sessionData: response.sessionData,
};

Drop-in configuration

Drop-in options are configured with the lowercase dropin key:

const config: Configuration = {
  environment: 'live-apse',
  clientKey: process.env.EXPO_PUBLIC_PLEXY_CLIENT_KEY!,
  returnUrl,
  countryCode: 'KZ',
  locale: 'ru-KZ',
  amount: { value: 10000, currency: 'KZT' },
  dropin: {
    showRemovePaymentMethodButton: true,
    skipListWhenSinglePaymentMethod: true,
  },
};

Card configuration

Card options are configured with the lowercase card key:

const config: Configuration = {
  environment: 'live-apse',
  clientKey: process.env.EXPO_PUBLIC_PLEXY_CLIENT_KEY!,
  returnUrl,
  countryCode: 'KZ',
  locale: 'ru-KZ',
  amount: { value: 10000, currency: 'KZT' },
  card: {
    holderNameRequired: false,
    showStorePaymentField: true,
    addressVisibility: 'none',
  },
};

Hide Cardholder Name Field

card: {
  holderNameRequired: false,
}

Google Pay

Google Pay is available on Android. It is not available as an in-app Google Pay component on iOS.

Use the lowercase googlepay key:

const GOOGLE_PAY_ENVIRONMENT_PRODUCTION = 1;
const GOOGLE_PAY_ENVIRONMENT_TEST = 3;

const config: Configuration = {
  environment: 'live-apse',
  clientKey: process.env.EXPO_PUBLIC_PLEXY_CLIENT_KEY!,
  returnUrl,
  countryCode: 'KZ',
  locale: 'ru-KZ',
  amount: { value: 10000, currency: 'KZT' },
  googlepay: {
    merchantAccount: 'YOUR_MERCHANT_ACCOUNT',
    countryCode: 'KZ',
    amount: { value: 10000, currency: 'KZT' },
    googlePayEnvironment: GOOGLE_PAY_ENVIRONMENT_PRODUCTION,
  },
};

For development before Google Pay production approval, use:

googlepay: {
  merchantAccount: 'YOUR_MERCHANT_ACCOUNT',
  countryCode: 'KZ',
  amount: { value: 10000, currency: 'KZT' },
  googlePayEnvironment: GOOGLE_PAY_ENVIRONMENT_TEST,
}

googlepay.merchantAccount is the Plexy merchant account that is used as Google Pay's gatewayMerchantId in the tokenization request. It is not the Google Pay merchantId. Keep it aligned with the merchantAccount your backend uses when creating the session.

Google Pay has its own TEST / PRODUCTION environment. This is separate from the Plexy SDK environment. Keep the Plexy SDK environment on live-apse.

Apple Pay

Apple Pay is available on iOS. Configure the Apple Pay entitlement in your iOS project or through the Expo config plugin.

In runtime checkout configuration, use the lowercase applepay key and the merchantID field:

const config: Configuration = {
  environment: 'live-apse',
  clientKey: process.env.EXPO_PUBLIC_PLEXY_CLIENT_KEY!,
  returnUrl,
  countryCode: 'KZ',
  locale: 'ru-KZ',
  amount: { value: 10000, currency: 'KZT' },
  applepay: {
    merchantID: 'merchant.money.plexy.example',
    merchantName: 'Your Store',
    summaryItems: [{ label: 'Order', amount: '100.00' }],
  },
};

Do not use merchantIdentifier in runtime checkout configuration. merchantIdentifier belongs to native entitlement setup, for example in the Expo config plugin. The runtime field is merchantID.

Components and advanced flow

For custom layouts, pass paymentMethods instead of session and implement onSubmit / onAdditionalDetails. The callbacks should forward SDK data to your backend, where you call /v2/payments and /v2/payments/details.

<PlexyCheckout
  config={config}
  paymentMethods={paymentMethodsResponse}
  onSubmit={(data, component) => {
    // Send data to your backend POST /v2/payments endpoint.
  }}
  onAdditionalDetails={(data, component) => {
    // Send data to your backend POST /v2/payments/details endpoint.
  }}
  onError={onError}
>
  <PayButton />
</PlexyCheckout>

Inside the child component, start the payment method you want:

function CardButton() {
  const { start, isReady } = usePlexyCheckout();

  return (
    <Button
      title="Pay by card"
      disabled={!isReady}
      onPress={() => start('scheme')}
    />
  );
}

Return URLs and redirects

Use PlexyDropIn.getReturnURL() to get the return URL that should be sent to your backend when creating a session or payment:

const returnUrl = await PlexyDropIn.getReturnURL();

There is no PlexyDropIn.handleReturnURL(url) API in @plexy/react-native 2.x. Do not add that call to your JavaScript code.

For redirect-based payment methods such as 3D Secure, make sure the native app is configured to receive the return URL scheme. If you use Expo prebuild, let the Plexy config plugin patch the native project. If you manage native projects manually, follow the corresponding iOS and Android return URL setup in the platform SDK docs.

Error handling

Use the callbacks on PlexyCheckout:

const onComplete = (result: SessionsResult, component: PlexyComponent) => {
  const authorised = result.resultCode === ResultCode.authorised;
  component.hide(authorised);
};

const onError = (error: PlexyError, component: PlexyComponent) => {
  component.hide(false);
  console.error(error.errorCode, error.message);
};

For Advanced flow, also use:

<PlexyCheckout
  config={config}
  paymentMethods={paymentMethodsResponse}
  onSubmit={handleSubmit}
  onAdditionalDetails={handleAdditionalDetails}
  onError={onError}
>
  <PayButton />
</PlexyCheckout>

Never treat a client-side callback as the source of truth for fulfillment. Confirm the final status on your backend via webhooks or a server-side status lookup before shipping goods or granting access.

Common mistakes

Calling usePlexyCheckout() outside of PlexyCheckout children.

Passing onResult; use onComplete.

Using PlexyProvider, useCheckout, or startCheckout; these are not the @plexy/react-native 2.x API.

Using camelCase payment-method config keys such as googlePay or applePay; use googlepay and applepay.

Using merchantIdentifier in runtime Apple Pay config; use applepay.merchantID.

Setting locale to a currency such as KZT; use locale: 'ru-KZ' and amount.currency: 'KZT'.

Sending API keys to the app. The app only receives clientKey; x-api-key stays on your backend.

React Native SDK

Installation#

iOS setup#

Android setup#

Expo#

SDK shape#

Base configuration#

Sessions flow#

Creating a session#

Drop-in configuration#

Card configuration#

Hide Cardholder Name Field#

Google Pay#

Apple Pay#

Components and advanced flow#

Return URLs and redirects#

Error handling#

Common mistakes#

Installation

iOS setup

Android setup

Expo

SDK shape

Base configuration

Sessions flow

Creating a session

Drop-in configuration

Card configuration

Hide Cardholder Name Field

Google Pay

Apple Pay

Components and advanced flow

Return URLs and redirects

Error handling

Common mistakes