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:
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:
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:

Configuration

  1. Create a .env file in your project root and add your publishable API keys:
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:

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:
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.