Getting Started
Install the SDK, set up the native project and check device requirements.
Install
npm install @lemonway/terminalnpm (7 or later) and pnpm also install the native Tap to Pay module the SDK runs on. react and react-native must already be in your app.
Yarn or React Native CLIYarn does not install peer dependencies, and the React Native CLI only links native modules listed in your
package.json. Add the peer dependencies of the SDK to your app, at the listed versions:npm info @lemonway/terminal peerDependencies
Expo Go is not supportedTap to Pay needs native code. Use an Expo development build or the React Native CLI.
Configure the native project
Add the config plugin to app.json, then run npx expo prebuild.
{
"expo": {
"plugins": [
[
"@lemonway/terminal",
{
"locationWhenInUsePermission": "Location access is required to accept in-person payments.",
"iosTapToPayEntitlement": true
}
]
]
}
}| Option | Default | Description |
|---|---|---|
locationWhenInUsePermission | Location access is required to accept in-person payments. | Text of the iOS location permission prompt. |
iosTapToPayEntitlement | true | Adds the iOS Tap to Pay entitlement. Set it to false until Apple has enabled Tap to Pay on your App ID, or iOS signing fails. |
The plugin:
- adds the location permission and the Android permissions,
- sets Android
minSdkVersionto 26 (it never lowers a higher value), - adds the Tap to Pay process guard to
MainApplication, - adds the iOS Tap to Pay entitlement.
Do by hand what the Expo plugin does.
Android
- Set
minSdkVersionto 26 or higher. - Declare
ACCESS_FINE_LOCATION,ACCESS_COARSE_LOCATION,BLUETOOTH_CONNECTandBLUETOOTH_SCANinAndroidManifest.xml. - In
MainApplication.kt, return early fromonCreate()in the Tap to Pay process, beforesuper.onCreate(). Without it, the app crashes when Tap to Pay starts its own process.
import com.stripeterminalreactnative.TapToPay
override fun onCreate() {
if (TapToPay.isInTapToPayProcess()) {
return
}
super.onCreate()
// ...
}iOS
- Add
NSLocationWhenInUseUsageDescriptiontoInfo.plist. - Add the
com.apple.developer.proximity-reader.payment.acceptanceentitlement (Boolean,YES) once Apple has enabled Tap to Pay on your App ID. - Run
pod installinios/.
Device requirements
Tap to Pay runs on a physical phone only, never on an emulator or simulator.
- iPhone XS or later, on the latest iOS version (not a beta).
- Apple's Tap to Pay on iPhone entitlement for your bundle identifier. Apple first grants a development entitlement; TestFlight and App Store releases need the distribution entitlement.
- On the first connection, a merchant admin accepts Apple's Tap to Pay terms with their Apple ID.
- Apple requires the app to explain Tap to Pay to merchants: follow Apple's Human Interface Guidelines for Tap to Pay on iPhone.
- NFC phone on Android 13 or later, with Google Play services, not rooted, with a recent security patch.
- Release build only. Tap to Pay refuses debuggable builds.
- Developer options off on the phone.
- Location services on, and precise location granted to the app.
Testing on a deviceInstall the release build with USB debugging on, then turn Developer options off and open the app from its icon.
PermissionsOn Android,
<LemonwayTerminalRoot>asks for the location (and Bluetooth) permissions when it mounts. Mount it on the screen where the merchant expects that prompt.
Updated 11 days ago