> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chipipay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Expo with Clerk

> Learn how to integrate Chipi Pay with your Expo application using Clerk Auth for authentication and biometric security.

# Building with Expo

This guide will walk you through integrating Chipi Pay into your Expo application with biometric authentication and secure storage. We'll cover everything from installation to implementing secure payment flows.

## Prerequisites

* Node.js 20.19.0 or later
* **Expo SDK 55 or later** (`@chipi-stack/chipi-expo` peer-requires `expo-local-authentication >=55.0.0` and `expo-secure-store >=55.0.0`)
* Expo CLI
* Basic knowledge of React Native
* A Chipi Pay account
* Clerk account for authentication
* Device with biometric authentication support (for biometric features)

## Getting Started

To get started with Chipi Pay in your Expo application, you'll need to have a basic Expo project set up. If you don't have one yet, you can create it using:

```bash theme={null}
npx create-expo-app@latest my-chipi-app
cd my-chipi-app
```

<Warning>
  `create-expo-app@latest` currently scaffolds Expo SDK 54, but
  `@chipi-stack/chipi-expo` requires SDK 55+ (for `expo-local-authentication`
  and `expo-secure-store` peer dependencies). Upgrade before installing the
  Chipi SDK:

  ```bash theme={null}
  npx expo install expo@~55.0.12 expo-local-authentication expo-secure-store
  ```

  Verified: `npx expo install` picks SDK-55-compatible versions automatically
  (`expo-local-authentication@~55.0.12`, `expo-secure-store@~55.0.12`).
</Warning>

## Installation

After upgrading to SDK 55, install the remaining packages:

```bash theme={null}
# Install Chipi Pay SDK
npx expo install @chipi-stack/chipi-expo

# Install Clerk and authentication packages
# (expo-local-authentication and expo-secure-store already installed in the SDK 55 upgrade above)
npx expo install @clerk/clerk-expo expo-web-browser
```

## Configuration

1. Create a `.env` file in your project root and add your **publishable** API keys:

```bash theme={null}
EXPO_PUBLIC_CHIPI_API_PUBLIC_KEY=pk_dev_your_public_key_here
EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_your_clerk_publishable_key
```

<Warning>
  **Never put secret keys in an Expo client app.** `@chipi-stack/chipi-expo` is a
  mobile SDK — treat `apiSecretKey` as backend-only and do not pass it from
  client code. (Note: `ChipiProvider` accepts `ChipiSDKConfig` which includes
  `apiSecretKey?: string` as optional — TypeScript will not block you, but
  passing it bundles the secret into your app binary. The type-level guard
  `apiSecretKey?: never` exists only on `ChipiBrowserSDKConfig` used by the
  web SDK.) Clerk's `@clerk/clerk-expo` only accepts a `publishableKey` —
  there is no `secretKey` prop on `ClerkProvider`. Secret keys
  (`CHIPI_SECRET_KEY`, `CLERK_SECRET_KEY`) belong on your backend, never in a
  mobile app bundle.
</Warning>

You can get your Chipi API public key [here](https://dashboard.chipipay.com/configure/credentials). And your Clerk publishable key [here](https://dashboard.clerk.com/last-active?path=api-keys).

2. Update your `app.json` to include the required permissions:

```json theme={null}
{
  "expo": {
    "plugins": [
      [
        "expo-local-authentication",
        {
          "faceIDPermission": "Allow $(PRODUCT_NAME) to use Face ID to unlock your wallet."
        }
      ],
      "expo-secure-store"
    ],
    "ios": {
      "supportsTablet": true,
      "infoPlist": {
        "NSFaceIDUsageDescription": "Allow $(PRODUCT_NAME) to use Face ID to unlock your wallet."
      }
    }
  }
}
```

## Implementing Secure Authentication Flow

1. Wrap your app in `ClerkProvider` and `ChipiProvider`. In Expo Router projects (the default from `create-expo-app`), the root component lives at `app/_layout.tsx`:

```typescript theme={null}
// app/_layout.tsx
import { ClerkProvider } from "@clerk/clerk-expo";
import { ChipiProvider } from "@chipi-stack/chipi-expo";
import { tokenCache } from "@clerk/clerk-expo/token-cache";
import { Slot } from "expo-router";

export default function RootLayout() {
  return (
    <ClerkProvider
      publishableKey={process.env.EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY!}
      tokenCache={tokenCache}
    >
      <ChipiProvider
        config={{
          apiPublicKey: process.env.EXPO_PUBLIC_CHIPI_API_PUBLIC_KEY!,
        }}
      >
        <Slot />
      </ChipiProvider>
    </ClerkProvider>
  );
}
```

<Note>
  `ChipiProvider` takes configuration via the `config` prop (`ChipiSDKConfig`).
  In Expo usage, pass only public client-safe values (`apiPublicKey`, and
  optionally `alphaUrl`/`nodeUrl`). Do not pass `apiPublicKey` as a direct
  prop on `ChipiProvider`.
</Note>

## Adding Clerk JWKS Endpoint

<Steps>
  <Step title="Copy your JWKS endpoint">
    Go into your Clerk dashboard and copy the [JWKS endpoint](https://dashboard.clerk.com/last-active?path=api-keys) available in the developers tab.
  </Step>

  <Step title="Register JWKS Endpoint in The Chipi dashboard">
    Register JWKS Endpoint URL in the [dashboard](https://dashboard.chipipay.com/configure/jwks-endpoint).
  </Step>
</Steps>

## Next Steps

* Add error handling and loading states
* Customize the UI to match your app's design

<Tip>
  Need help? Check out our [Telegram Community](https://t.me/+e2qjHEOwImkyZDVh) for
  support and to connect with other developers.
</Tip>