EasyProvider

EasyProvider is the entry point of @easylabs/react-native. It does three things on mount:

Validates your API key against the Easy API.
Creates a Basis Theory session bound to that key.
Wraps its children in BasisTheoryProvider so all SDK-exported elements (CardNumberElement, etc.) work without extra setup.

Mount it once, as high in your tree as possible — typically at the root of your app, above your navigator. Everything inside can call useEasy().

Props

Prop	Type	Required	Description
`apiKey`	`string`	yes	Your Easy publishable API key. The SDK selects sandbox vs. production from the key prefix (`sk_test_` → sandbox, otherwise production).
`children`	`ReactNode`	yes	Your app tree.
`__internal_api_url`	`string`	no	Internal override for the Easy API base URL. Reserved for Easy Labs' own development and testing. Not part of the public API and may change without notice — do not use this to point at a custom or staging environment.
`__dev`	`boolean`	no	Legacy flag. Currently a no-op for URL routing — use `__internal_api_url` if you need to override the endpoint. Will be removed in a future release.

The provider does not accept locale, theme, currency, or analytics props — those are concerns of the components you render inside it.

Example

App.tsx

import { EasyProvider } from '@easylabs/react-native';
import { NavigationContainer } from '@react-navigation/native';
import { createNativeStackNavigator } from '@react-navigation/native-stack';
import CheckoutScreen from './src/screens/CheckoutScreen';
import HomeScreen from './src/screens/HomeScreen';

const Stack = createNativeStackNavigator();

export default function App() {
  return (
    <EasyProvider apiKey={process.env.EXPO_PUBLIC_EASY_API_KEY!}>
      <NavigationContainer>
        <Stack.Navigator>
          <Stack.Screen name="Home" component={HomeScreen} />
          <Stack.Screen name="Checkout" component={CheckoutScreen} />
        </Stack.Navigator>
      </NavigationContainer>
    </EasyProvider>
  );
}

EasyProvider validates and creates a session on every mount. Avoid unmounting and re-mounting it on every navigation — keep it at the root so the session is reused for the lifetime of the app session.

Initialization errors

If validation or session creation fails, the error is logged to console.error with the prefix EasyProvider initialization failed: and the provider continues to render its children. Calls into useEasy() that require an initialized Basis Theory session (anything that tokenizes card or bank data — checkout, createPaymentInstrument, tokenizePaymentInstrument) will throw "Basis Theory client is not initialized". Plain API methods (getCustomers, getProducts, etc.) work as soon as apiClient is constructed.

The SDK does not auto-retry initialization. initClient() only runs when EasyProvider mounts or when its apiKey prop changes. If init fails (e.g. transient network blip during app start), tokenizing calls keep throwing until you trigger a re-init by one of:

Re-mounting EasyProvider (e.g. by toggling a key on the provider element, or unmounting and re-rendering the subtree that owns it).
Restarting the app.
Changing the apiKey prop to a new value (a no-op string change does not re-trigger init — the prop must actually differ).

If you need automatic recovery, wrap your app in a small effect that bumps a key prop on EasyProvider after a window of failed tokenizations, or surface a "retry" affordance in your UI that does the same.

Hooks that depend on this provider

`useEasy()`

The single hook surface for the SDK. Returns the typed API client plus the tokenizing checkout helpers. Must be called inside an EasyProvider; otherwise it throws "useEasy must be used within an EasyProvider".

import { useEasy } from '@easylabs/react-native';

function MyComponent() {
  const {
    // Customers
    createCustomer, updateCustomer, getCustomer, getCustomers,
    getCustomerPaymentInstruments, getCustomerOrders,
    getCustomerSubscriptions, getCustomerWallets,

    // Payment instruments
    tokenizePaymentInstrument, createPaymentInstrument, updatePaymentInstrument,

    // Transfers
    createTransfer, getTransfers, getTransfer, updateTransferTags,

    // Products & prices
    getProducts, getProduct, getProductWithPrice, getProductWithPrices,
    createProduct, updateProduct, archiveProduct,
    getProductPrices, getProductPrice, createProductPrice,
    updateProductPrice, archiveProductPrice,

    // Orders, subscriptions, settlements
    getOrders, getOrder, updateOrderTags,
    getSubscriptions, getSubscription, createSubscription,
    updateSubscription, cancelSubscription,
    getSettlements, getSettlement, closeSettlement,

    // Checkout
    checkout,
    createPaymentLink,

    // Deprecated
    anonCheckout, checkoutExistingCustomer,
  } = useEasy();
}

See the Quickstart for checkout() end-to-end and Elements for the tokenization helpers.

Basis Theory hooks

@easylabs/react-native does not re-export useBasisTheory from @basis-theory/react-native-elements. If you need lower-level control over Basis Theory tokens, import it directly from @basis-theory/react-native-elements — the BasisTheoryProvider is already in the tree, so the hook will resolve the same client EasyProvider is using.