Quickstart

This guide takes a fresh React Native app to a working card checkout — capturing card data in native, PCI-scoped inputs, tokenizing it via Basis Theory, and creating an order through the Easy API.

1. Get your API keys

Create an application in the Easy dashboard and copy your publishable API key.

Sandbox keys start with sk_test_ and route to https://sandbox-api.itseasy.co/v1/api.
Live keys do not have the sk_test_ prefix and route to https://api.itseasy.co/v1/api.

The SDK picks the right environment automatically from the key prefix — you do not configure URLs.

Only ship publishable keys to mobile clients. Secret keys belong on your server. See the backend SDK for server-side calls.

2. Initialize the SDK

Wrap your root component with EasyProvider:

App.tsx

import { EasyProvider } from '@easylabs/react-native';
import CheckoutScreen from './src/screens/CheckoutScreen';

export default function App() {
  return (
    <EasyProvider apiKey={process.env.EXPO_PUBLIC_EASY_API_KEY!}>
      <CheckoutScreen />
    </EasyProvider>
  );
}

EasyProvider validates your API key against the Easy API on mount and creates a short-lived Basis Theory session under the hood. All children inside the provider can call useEasy().

3. Make your first call

Build a screen that captures card data with the three native elements and submits a checkout:

src/screens/CheckoutScreen.tsx

import {
  type BTDateRef,
  type BTRef,
  CardExpirationDateElement,
  CardNumberElement,
  CardVerificationCodeElement,
  useEasy,
} from '@easylabs/react-native';
import { useRef, useState } from 'react';
import { Alert, Button, Text, View } from 'react-native';

export default function CheckoutScreen() {
  const { checkout } = useEasy();
  const cardNumberRef = useRef<BTRef>(null);
  const cardExpirationRef = useRef<BTDateRef>(null);
  const cardCvcRef = useRef<BTRef>(null);
  const [loading, setLoading] = useState(false);

  const handleSubmit = async () => {
    setLoading(true);
    try {
      const result = await checkout({
        customer_creation: true,
        customer_details: {
          first_name: 'Jane',
          last_name: 'Doe',
          email: 'jane@example.com',
        },
        source: {
          type: 'PAYMENT_CARD',
          name: 'Jane Doe',
          cardNumberElement: cardNumberRef,
          cardExpirationDateElement: cardExpirationRef,
          cardVerificationCodeElement: cardCvcRef,
        },
        line_items: [{ price_id: 'price_123', quantity: 1 }],
      });

      if (result.success) {
        Alert.alert('Paid', `Order ${result.data.orderId}`);
      }
    } catch (err) {
      Alert.alert('Error', err instanceof Error ? err.message : 'Failed');
    } finally {
      setLoading(false);
    }
  };

  return (
    <View style={{ padding: 16, gap: 12 }}>
      <Text>Card number</Text>
      <CardNumberElement btRef={cardNumberRef} />

      <Text>Expiration</Text>
      <CardExpirationDateElement btRef={cardExpirationRef} />

      <Text>CVC</Text>
      <CardVerificationCodeElement btRef={cardCvcRef} />

      <Button title={loading ? 'Processing…' : 'Pay'} onPress={handleSubmit} disabled={loading} />
    </View>
  );
}

Use the test card 4242 4242 4242 4242, any future expiration date, and any 3-digit CVC against a sandbox key.

4. Handle the response

checkout() resolves with the standard Easy API response shape:

{
  success: true,
  data: {
    orderId: 'ord_…',
    // …additional fields from the checkout session
  }
}

Failures throw — wrap the call in try/catch. The thrown Error.message will tell you which step failed:

Message contains	Cause
`apiKey is required`	`EasyProvider` was rendered without an `apiKey` prop.
`API key validation failed`	The key was rejected by the Easy API.
`Card element reference is not set`	A required element ref was `null` at submit time.
`Card expiration date is incomplete`	The user did not finish typing MM / YY.
`Failed to create payment instrument token`	Basis Theory tokenization failed (network / data).
`API request failed: …`	The Easy API returned a non-2xx response. Thrown as `EasyApiError`; check `err.status` (HTTP status) and `err.code` (Easy error code, if available) with `instanceof EasyApiError` for granular handling.

What's next

EasyProvider — every prop, every option.
Elements — full element reference and styling.
Wallet Checkout — Apple Pay and Google Pay.
Examples → Expo — guided tour of the runnable example app.