Skip to main content

​
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: 
npx create-expo-app@latest my-chipi-app
cd my-chipi-app
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:
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).

​
Installation

After upgrading to SDK 55, install the remaining packages: 
# 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:
EXPO_PUBLIC_CHIPI_API_PUBLIC_KEY=pk_dev_your_public_key_here
EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_your_clerk_publishable_key
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.
You can get your Chipi API public key here. And your Clerk publishable key here.
  1. Update your app.json to include the required permissions:
{
  "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:
// 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>
  );
}
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.

​
Adding Clerk JWKS Endpoint

1

Copy your JWKS endpoint

Go into your Clerk dashboard and copy the JWKS endpoint available in the developers tab.
2

Register JWKS Endpoint in The Chipi dashboard

Register JWKS Endpoint URL in the dashboard.

​
Next Steps

  • Add error handling and loading states
  • Customize the UI to match your app’s design
Need help? Check out our Telegram Community for support and to connect with other developers.