EasyProvider

EasyProvider is the entry point for @easylabs/react. It owns three things:

The EasyApiClient instance used by every method on useEasy().
A live Basis Theory session, opened on mount and used to tokenize card and bank-account elements without their values touching your server.
The BasisTheoryProvider context that the <CardElement> family needs to render. All elements in your tree must be descendants of EasyProvider for tokenization to work.

Mount it once, as high in your component tree as is practical. In Next.js App Router, it must be inside a Client Component ("use client").

Props

Prop	Type	Required	Description
`apiKey`	`string`	yes	Your Easy Labs publishable API key. Keys starting with `sk_test_` route to the sandbox API; all others route to production.
`children`	`ReactNode`	yes	Your app tree.
`__internal_api_url`	`string`	no	Internal. Override the API base URL. Not part of the public API; intended for Easy Labs development and may change without notice.

EasyProvider resolves the API URL in this order: __internal_api_url if provided, otherwise https://sandbox-api.itseasy.co/v1/api for sk_test_ keys and https://api.itseasy.co/v1/api for everything else. Production apps should never set the internal override.

Example

src/main.tsx

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { EasyProvider } from "@easylabs/react";
import App from "./App";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <EasyProvider apiKey={import.meta.env.VITE_EASY_API_KEY}>
      <App />
    </EasyProvider>
  </StrictMode>,
);

For Next.js App Router, the provider must live in a Client Component that is then rendered from your root layout:

src/components/Providers.tsx

"use client";

import { EasyProvider } from "@easylabs/react";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <EasyProvider apiKey={process.env.NEXT_PUBLIC_EASY_API_KEY ?? ""}>
      {children}
    </EasyProvider>
  );
}

src/app/layout.tsx

import { Providers } from "@/components/Providers";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

The `useEasy()` hook

useEasy() returns an object with every API method on the SDK. Calling it outside an EasyProvider throws useEasy must be used within an EasyProvider.

The methods fall into a few groups:

Customers

Method	Description
`createCustomer(data)`	Create a customer record.
`updateCustomer(id, data)`	Patch a customer.
`getCustomer(id)`	Fetch a single customer.
`getCustomers(params?)`	List customers.
`getCustomerPaymentInstruments(id)`	List a customer's saved cards / bank accounts.
`getCustomerOrders(id, params?)`	List a customer's orders.
`getCustomerSubscriptions(id, params?)`	List a customer's subscriptions.
`getCustomerWallets(id, params?)`	List a customer's crypto wallets.

Payment instruments

Method	Description
`tokenizePaymentInstrument(data)`	Tokenize element refs into a Basis Theory token ID; rarely called directly.
`createPaymentInstrument(data)`	Tokenize and persist a new card or bank account against a customer.
`updatePaymentInstrument(id, data)`	Patch a saved instrument.

Transfers, products, prices, orders, subscriptions, settlements

createTransfer, getTransfers, getTransfer, updateTransferTags, getProducts, getProduct, getProductWithPrice, getProductWithPrices, createProduct, updateProduct, archiveProduct, getProductPrices, getProductPrice, createProductPrice, updateProductPrice, archiveProductPrice, getOrders, getOrder, updateOrderTags, getSubscriptions, getSubscription, createSubscription, updateSubscription, cancelSubscription, getSettlements, getSettlement, closeSettlement — all proxy directly to EasyApiClient and return ApiResponse<T>.

One-shot checkout

Method	Description
`checkout(data)`	The recommended end-to-end checkout call. Tokenizes a card / bank element (or accepts an existing instrument ID), creates a customer if `customer_creation: true`, and creates the order in a single round trip.
`anonCheckout(data)`	Deprecated. Use `checkout` with `customer_creation: true`.
`checkoutExistingCustomer(data)`	Deprecated. Use `checkout` with `customer_creation: false` and `identity_id`.

Payment links and embedded checkout

Method	Description
`createPaymentLink(data)`	Create a hosted payment link.
`createEmbeddedCheckoutSession(data)`	Create a session whose `client_secret` powers the `<EmbeddedCheckout>` iframe.
`getEmbeddedCheckoutSession(id)`	Poll an embedded checkout session's status.
`getCryptoPaymentStatus(id)`	Poll the on-chain status of a crypto payment in an embedded session.

Every method returns either a typed ApiResponse<T> envelope ({ success, data } or { success: false, message }) or, for the few that wrap multiple steps (checkout, anonCheckout, checkoutExistingCustomer), the underlying API response. See the TypeScript reference for the exported types.

Hooks that depend on this provider

useEasy() — the API surface above.
useEmbeddedCheckout() — read iframe lifecycle status when wrapped in <EmbeddedCheckoutProvider>.

The Basis Theory <CardElement>, <CardNumberElement>, <CardExpirationDateElement>, <CardVerificationCodeElement>, and <TextElement> re-exports also require EasyProvider as an ancestor — they read the Basis Theory client from the context that EasyProvider installs.

EasyProvider

On this page