Set up the development environment

Prepare your development environment before building your in-person card payment integration.

Prerequisites

• An Apple Developer account with organization-level access (iOS only).
• A React Native, iOS, or Android project.

Step 1: Request Apple entitlements (iOS only)

iOS only

Skip this step if you're building for Android only.

To develop Tap to Pay on iPhone, you need the Tap to Pay on iPhone entitlement from Apple. It applies even if you're developing with React Native.

1. Sign in to your Apple Developer account as the Account Holder.
2. Submit a request using Apple's entitlement request form.
3. On the form, provide the following:
   • Your PSP: Stripe.
   • Distributed apps using this entitlement: the number of existing apps that will include Tap to Pay.
   • New apps using this entitlement: the number of new apps you plan to launch with Tap to Pay.
   • Distribution method: public through the App Store.
   • Fill in the remaining fields based on your use case: expected number of users, target countries, and expected release date.
4. After submitting, Apple sends a confirmation email. Follow Apple's guide to add the Tap to Pay capability to your App ID, download the provisioning profile, and configure the entitlements file.

Save your confirmation email

This entitlement covers development and internal testing only. Before publishing to the App Store or TestFlight, reply to this email to request the production entitlement, then resubmit the form.

Step 2: Install the Stripe Terminal SDK

Swan uses Stripe as its provider for in-person card payments. Install the Stripe Terminal SDK in your project.

Stripe docs reference

Follow this guide to install the SDK. Steps 3 and 4 in Stripe's documentation differ for Swan integrations.

React Native

The React Native SDK is open source and available on GitHub.

Install it using your package manager:

# npm
npm install @stripe/stripe-terminal-react-native

# Yarn
yarn add @stripe/stripe-terminal-react-native

# Expo
npx expo install @stripe/stripe-terminal-react-native

iOS

The Stripe Terminal iOS SDK requires iOS 13 or later.

CocoaPods

Add the following line to your Podfile, then run pod install:

pod 'StripeTerminal', '~> 4.0'

Swift Package Manager

1. In Xcode, select File > Add Packages….
2. Enter the SDK URL: https://github.com/stripe/stripe-terminal-ios
3. Select a version. The default Up to Next Major is recommended to receive security and feature updates without unexpected breaking changes.

Manual

1. Go to the latest release on GitHub.
2. Download StripeTerminal.xcframework.zip and unzip it.
3. Drag the .xcframework into your Xcode project.
4. In your target's General pane, under Frameworks, Libraries, and Embedded Content, set StripeTerminal.xcframework to Embed and Sign.

Android

The Android SDK requires AndroidX. Add stripeterminal to your app's build.gradle dependencies:

Kotlin (build.gradle.kts)

plugins {
  id("com.android.application")
}

android { ... }

dependencies {
  implementation("com.stripe:stripeterminal:4.7.3")
}

The SDK requires Java 8. Set your target Java version:

android {
  compileOptions {
    sourceCompatibility = JavaVersion.VERSION_1_8
    targetCompatibility = JavaVersion.VERSION_1_8
  }
  kotlinOptions {
    jvmTarget = "1.8"
  }
}

Groovy (build.gradle)

apply plugin: 'com.android.application'

android { ... }

dependencies {
  implementation "com.stripe:stripeterminal:4.7.3"
}

The SDK requires Java 8. Set your target Java version:

compileOptions {
  sourceCompatibility JavaVersion.VERSION_1_8
  targetCompatibility JavaVersion.VERSION_1_8
}

Step 3: Request location permissions

The Stripe Terminal SDK requires foreground location access to determine where payments are made and reduce fraud risks. Payments won't start without it.

UX best practice

Before requesting location access, explain to users why you need it. A brief in-app message before the system prompt improves acceptance rates.

React Native

Location permission configuration differs by target OS and whether you use React Native CLI or Expo.

Follow Step 2 (Configure your app) in Stripe's guide. Do not continue past that step. The remaining steps differ for Swan integrations.

iOS

Add the following key-value pair to your Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>Location access is required to accept payments.</string>

Android

Add the location permission to your AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Verify that location access has been granted before using the SDK. In your main activity:

if (ContextCompat.checkSelfPermission(
    this,
    android.Manifest.permission.ACCESS_FINE_LOCATION
  ) != PackageManager.PERMISSION_GRANTED
) {
  val permissions = arrayOf(android.Manifest.permission.ACCESS_FINE_LOCATION)
  ActivityCompat.requestPermissions(this, permissions, REQUEST_CODE_LOCATION)
}

Override onRequestPermissionsResult to handle the user's response:

override fun onRequestPermissionsResult(
  requestCode: Int,
  permissions: Array<String>,
  grantResults: IntArray
) {
  super.onRequestPermissionsResult(requestCode, permissions, grantResults)
  if (requestCode == REQUEST_CODE_LOCATION
    && grantResults.isNotEmpty()
    && grantResults[0] != PackageManager.PERMISSION_GRANTED
  ) {
    // Location permission denied. The SDK won't allow payments without it.
  }
}

Next steps

→ Request a merchant profile