Warning
Implementing Tap to Pay on iPhone is a complex process that requires submitting your app to Apple for approval. Plan extra time for the entitlement request and review process, which can take several weeks.
Four steps to configure your Apple Developer account and Xcode project for Tap to Pay on iPhone.
### Step 1: Register your App ID
In Apple's Certificates, Identifiers & Profiles, create or select an App ID and note the Bundle ID (e.g. `com.yourcompany.yourapp`). Use the same Bundle ID for test and production -- the Surfboard SDK controls environments through the connection blob and backend URLs, not the bundle identifier.
### Step 2: Enable the capability
Edit the App ID, find **Tap to Pay on iPhone** under Capabilities, and enable it. Apple may require additional contracts before this is available.
### Step 3: Update provisioning profiles
Regenerate your development and distribution profiles for the updated App ID and install them in Xcode.
### Step 4: Add the entitlement in Xcode
In your app target under Signing & Capabilities, click "+ Capability" and add **Tap to Pay on iPhone**. Xcode creates the entitlements file automatically. Also add any required `Info.plist` usage descriptions per Apple's ProximityReader documentation.
The entitlement key that must be present in your `.entitlements` file:
| Entitlement Key | Type | Value |
|-----------------|------|-------|
| `com.apple.developer.proximity-reader.payment.acceptance` | Boolean | `true` |
### Further reading
- [Apple: Setting up the entitlement for Tap to Pay on iPhone](https://developer.apple.com/documentation/proximityreader/setting-up-the-entitlement-for-tap-to-pay-on-iphone)
- [Apple: Tap to Pay on iPhone for Developers](https://developer.apple.com/tap-to-pay/)
> **Tip:** The Surfboard SDK does not use different bundle IDs for environments. Environments are controlled by the connection blob and backend URLs, not by the bundle ID.
## SDK Installation
The SDK is delivered as a prebuilt `tap_to_pay_apple.xcframework`. Surfboard provides separate staging and production builds.
1. Copy `tap_to_pay_apple.xcframework` into your repo (e.g., `YourApp/SDKs/tap_to_pay_apple/`).
2. In Xcode, go to your app target > General > Frameworks, Libraries, and Embedded Content.
3. Click + > Add Other > Add Files, then select the xcframework.
4. Set embedding to **"Do Not Embed"** (the SDK is a static framework).
5. Build to verify linking.
Import in Swift:
```swift
import tap_to_pay_apple
```
> **Note:** Swap the xcframework binary to switch between staging and production. Store both variants in your repo (e.g., `staging/` and `release/` subdirectories) and link only one at a time.
## Credentials & Initialization
Three objects to set up before processing payments: a logger, credentials, and the SDK instance.
### GapLogger
Implement the `GapLogger` protocol to route SDK logs into your logging stack. The protocol requires three methods: `addLog`, `addErrorLog`, and `addDebugLog`.
```swift
import os
import tap_to_pay_apple
final class AppGapLogger: GapLogger {
private let logger = Logger(subsystem: "YourApp", category: "TapToPay")
func addLog(logText: String) {
logger.log("\(logText, privacy: .public)")
}
func addErrorLog(logText: String) {
logger.error("\(logText, privacy: .public)")
}
func addDebugLog(logText: String) {
logger.debug("\(logText, privacy: .public)")
}
}
```
### GapCredentials
Build `GapCredentials` once, typically at app startup, using values provided by Surfboard:
```swift
let credentials = GapCredentials(
connectionBlob: connectionBlob, // from Surfboard
versionNumber: appVersion,
tmsPublicKey: tmsPublicKey, // from Surfboard Developer Portal
merchantId: merchantId, // from merchant onboarding
storeId: storeId, // from merchant onboarding
applicationBundleId: Bundle.main.bundleIdentifier ?? ""
)
```
### Gap instance
Create a single, long-lived `Gap` instance. Subscribe to events, initialize the SDK, and set the auth token:
```swift
let gap = try Gap(logger: logger, credentials: credentials)
gap.subscribeToPublicEvents { wrapper in
// Handle wrapper.event and wrapper.data
}
try await gap.initializeSdk()
let authToken = try await fetchAuthTokenFromBackend()
gap.setAuthToken(authToken: authToken)
```
> **Warning:** Auth tokens are short-lived. Refresh them before expiry and call `setAuthToken(authToken:)` again. Never generate tokens on the device -- always fetch them from your backend.
## Terminal Lifecycle
The terminal represents a logical payment endpoint on the Surfboard side. You register it once per device, then open it for each session.
### Register (first run)
```swift
let result = await gap.registerTerminal()
switch result {
case .success:
print("Terminal ID: \(gap.terminalId)")
case .failure(let error):
print("Registration failed: \(error.code.details.message)")
}
```
Registration is a one-time operation per device or installation. After success, `gap.terminalId` contains the terminal identifier.
### Open and initialize (each session)
On subsequent app launches, skip registration and go straight to opening:
```swift
let openResult = await gap.openTerminal()
let readerResult = await gap.initializeReader()
try await gap.getReadyForTransaction()
```
Call these three methods in sequence before starting any payment.
### Cleanup
For logout or troubleshooting flows, use `disposeTerminal()` to close the session and `clean()` to reset SDK state. After calling `clean()`, you need to re-register the terminal.
## Payment Flow
Every payment follows three steps: create an order on your backend, start a transaction through the SDK, and handle the result.
### Step 1: Create an order
From your iOS app, call your backend to create an order via the Surfboard Orders API. Pass the amount in **minor units** (e.g., `1000` for 10.00 SEK), the ISO numeric currency code (e.g., `"752"` for SEK), and `gap.terminalId` as the terminal identifier. Your backend returns an `orderId`.
### Step 2: Start the transaction
```swift
let parameters = GapPaymentParameters(
amount: NSNumber(value: amountInMinorUnits),
type: "PURCHASE",
currency: "SEK",
orderId: orderId,
aidPreference: nil
)
let paymentId = try await gap.startTransaction(parameters: parameters)
```
The SDK takes over and presents Apple's Tap to Pay UI. The customer taps their card. The SDK emits events throughout -- use them to update your UI ("Present card", "Processing", "Approved", "Declined").
### Step 3: Complete or cancel
After the transaction resolves:
```swift
// Confirm completion
gap.sendCompletedEvent(paymentId: paymentId, approved: true)
// Or cancel an in-progress transaction
let cancelResult = await gap.cancelTransaction(paymentId: paymentId)
```
## Cardholder Verification & PIN
Tap to Pay on iPhone supports on-device PIN entry starting with **iOS 16.4**. When a contactless transaction requires cardholder verification, the SDK presents a secure PIN input screen on the iPhone.
### When is PIN required?
- **NFC wallet payments** (Apple Pay, Google Pay) typically do not require PIN -- the cardholder authenticates via Face ID or passcode on their own device.
- **Physical contactless cards** may require PIN depending on the transaction amount, card issuer policy, and regional regulations.
### Regional considerations
| Region | Consideration |
|--------|--------------|
| United Kingdom | Strong Customer Authentication (SCA) may require card insertion for verification. If the card only supports offline PIN, the transaction will decline with an `offline_pin_required` error. |
| Canada & Finland | Cards that only support offline PIN are not compatible with Tap to Pay on iPhone. These transactions will be declined. |
Recommendation
If a transaction declines due to PIN or verification issues, ask the customer to try a different card or use an alternative payment method such as a
Payment Link or a traditional card reader.
For more information on contactless transaction limits by country, see [Visa's contactless transaction limits](https://www.visa.co.uk/dam/VCOM/regional/ve/unitedkingdom/PDF/visa-contactless-transaction-limit.pdf).
## Events & Monitoring
Subscribe to the SDK event stream to drive your UI and logging:
```swift
gap.subscribeToPublicEvents { wrapper in
switch wrapper.event {
case .INITIALIZED: // SDK ready
case .TERMINAL_CREATED: // Registration succeeded
case .TERMINAL_CREATION_ERROR: // Registration failed
case .TRANSACTION_COMPLETED: // Payment finished
case .TRANSACTION_FAILED: // Payment failed
default: break
}
}
```
### Key status properties
| Property | Purpose |
|----------|---------|
| `gap.isInitialized` | SDK has completed initialization |
| `gap.terminalId` | Terminal ID after successful registration |
| `gap.isReadyForTransactions` | Terminal and reader are ready for payments |
| `gap.canMakePayments()` | Device supports Tap to Pay and is in a usable state |
Use these for health checks and to enable or disable payment UI elements.
## Best Practices
Follow these recommendations to deliver a reliable and polished Tap to Pay experience.
### Reader connection
- **Connect early:** Initialize the SDK and connect to the reader in the background during app startup, so the terminal is ready when the merchant needs to accept a payment.
- **Automatic reconnection:** When your app returns to the foreground, check `gap.isReadyForTransactions` and re-initialize the reader if needed. This ensures the terminal is always available after the app has been backgrounded.
### User experience
- Follow Apple's [Human Interface Guidelines for Tap to Pay on iPhone](https://developer.apple.com/design/human-interface-guidelines/tap-to-pay-on-iphone) to provide a consistent and intuitive payment experience.
- On **iOS 18+**, use Apple's `ProximityReaderDiscovery` API to display localized educational content that helps merchants and customers understand how Tap to Pay works.
### Marketing & branding
- When promoting Tap to Pay on iPhone in your app or marketing materials, follow Apple's [Tap to Pay on iPhone Marketing Guidelines](https://developer.apple.com/tap-to-pay/marketing-guidelines/) for correct branding, terminology, and asset usage.
## Testing
**Simulator:** Supports SDK initialization and terminal registration. Card presentation is simulated -- no real NFC reads. Use the simulator to validate your integration flow and UI before moving to a device.
**Physical device:** Required for end-to-end payment validation. Needs an iPhone running iOS 17.4+ with NFC. Test at least one full transaction on a real device before release.
### Common issues and checks
- **SDK not initializing:** Verify credentials (connection blob, TMS public key, merchant/store IDs). Check network connectivity. Inspect `GapLogger` output.
- **Registration fails:** Confirm `initializeSdk()` completed. Verify a valid `authToken` is set. Check that merchant/store IDs match the target environment.
- **Payments fail:** Confirm `gap.terminalId` is set. Verify order creation succeeds on your backend. Check that amount uses minor units and currency uses the correct ISO code. Inspect transaction events to distinguish declines from technical errors.
## Release Checklist
Verify these items before shipping your app with Tap to Pay on iPhone.
### Apple configuration
- App ID has Tap to Pay on iPhone capability enabled
- Provisioning profiles are up to date and installed
- Required `Info.plist` usage descriptions are present
### Surfboard configuration
- Using the correct `connectionBlob` and `tmsPublicKey` for the target environment
- Backend calls the correct Surfboard endpoints (staging vs. production) for auth tokens and orders
- `merchantId` and `storeId` match the target environment
### SDK wiring
- `tap_to_pay_apple.xcframework` is linked to the correct app target
- Only one xcframework variant (staging or production) is linked at a time
- `Gap` is instantiated once and reused across the app lifecycle
- Auth tokens are refreshed before expiry via `setAuthToken(authToken:)`
### Functional validation
- `gap.isInitialized` returns `true` after startup
- `gap.terminalId` is populated after registration
- At least one full transaction completes on a real device
- Event stream fires expected events: `INITIALIZED`, `TERMINAL_CREATED`, `TRANSACTION_COMPLETED`
## Reference
- [iOS Example App on GitHub](https://github.com/surfboardpayments/ios-gap-example)
- [Client Auth Token API](https://developers.surfboardpayments.com/references/api/client-auth-token/create-token)
- [Orders API](https://developers.surfboardpayments.com/api/orders)
## Disclaimer
While this document aims to assist users in the application process, it is ultimately the user's responsibility to meet Apple's requirements, and the final decision to approve or decline an application lies with Apple.
### Android SoftPOS SDK
Category: in-store | Tags: Android, Kotlin, SoftPOS, In-Store, NFC
URL: /developers/guides/android-softpos-sdk
## Overview
The Surfboard Android SoftPOS SDK enables Android applications to process tap-to-pay transactions using NFC-enabled devices. It provides terminal management, transaction processing, and security -- supporting seamless integration for contactless payments.
The SDK is distributed via Surfboard-hosted Maven repositories and ships as separate debug and release variants.
> **Note:** The canonical reference implementation is the [Android GAP Example App](https://github.com/surfboardpayments/android-gap-example), which demonstrates the full integration flow.
## Prerequisites
Before starting integration, confirm you have the following:
### Development Environment
- **Android Studio** 4.1 or higher
- **Minimum SDK**: API level 29 (Android 10.0)
- **Java**: 11 or higher
- **Kotlin**: 2.0.21 or higher
### Surfboard Account & Credentials
- Registered Surfboard Partner account
- Active merchant setup with at least one store
- Surfboard-issued SoftPOS configuration values:
- `connectionBlob` -- provided by Surfboard during onboarding
- `tmsPublicKey` -- retrieved from the Developer Portal after registering your SDK app under **Console > SDK Apps**
- Merchant and store identifiers:
- `merchantId`
- `storeId`
- Access to the [Client Auth Token API](https://developers.surfboardpayments.com/references/api/client-auth-token/create-token) for obtaining bearer tokens
> **Tip:** You do not generate `connectionBlob` or `tmsPublicKey` yourself. Surfboard shares them as part of onboarding. If you are missing any values, contact Surfboard integrations support.
## SDK Setup & Installation
### 1. Add softpos.properties
Create a `softpos.properties` file in your Android project root (same level as `settings.gradle.kts`):
```properties
softpos1.mavenurl = MAVEN_URL1
softpos1.mavenusername = MAVEN_USERNAME1
softpos1.mavenpassword = MAVEN_PASSWORD1
softpos2.mavenurl = MAVEN_URL2
softpos2.mavenusername = MAVEN_USERNAME2
softpos2.mavenpassword = MAVEN_PASSWORD2
```
Add it to `.gitignore`:
```text
softpos.properties
```
### 2. Configure Gradle Repositories
In your root `build.gradle.kts`, load the properties and configure repositories:
```kotlin
import java.util.Properties
import java.io.FileInputStream
val localProperties = Properties()
val localPropertiesFile = rootProject.file("softpos.properties")
if (localPropertiesFile.exists()) {
localProperties.load(FileInputStream(localPropertiesFile))
}
allprojects {
repositories {
google()
mavenCentral()
mavenLocal()
maven {
url = uri(localProperties.getProperty("softpos1.mavenurl"))
credentials {
username = localProperties.getProperty("softpos1.mavenusername")
password = localProperties.getProperty("softpos1.mavenpassword")
}
}
maven {
url = uri(localProperties.getProperty("softpos2.mavenurl"))
credentials {
username = localProperties.getProperty("softpos2.mavenusername")
password = localProperties.getProperty("softpos2.mavenpassword")
}
authentication {
create