❗️

The Tap to Phone SDK is currently in Beta and only available for iOS.

Rainforest reserves the right to introduce breaking changes during this period. You will be notified of any updates prior to the release.

Please contact Rainforest support or your Platform Success Manager for more information on this feature.

✔️

Feature requirements

🔐 Rainforest must enable the platform to access this feature

💲 Billing fees associated to this feature

Implement Tap to Phone SDK into your platform's iOS application with five steps:

• Enable Tap to Phone on your integration with Rainforest
• Configure your application with Apple pre-requisites
• Create device registrations for each device your application will process payments on
• Integrate the Rainforest SDK Tap to Phone payment flow
• Configure the Deposit Report Component to show the billing details

Enable Tap to Phone

Please reach out to your Platform Success Manager or support to enable this feature. Rainforest will provide:

• The Rainforest iOS SDK through a ZIP file
• A sample application if your platform utilizes React Native, Expo, or Flutter

Apple pre-requisites

There are a few permissions and app-level configuration that needs to be set within your mobile application before trying to interact with the SDK in code.

Entitlements

NFC permission entitlement

The NFC entitlement must be included to enable the Tap to Phone feature.

Near Field Communication Tag Reader Session Format
- Near Field Communication Tag Reading Session Format = Tag-Specific Data Protocol (TAG)

Payment Acceptance Entitlement

📘

Apple Approval of Entitlement

You should request the Tap to Pay on iPhone entitlement with Apple as soon as possible. Even if you do not plan to complete development immediately. This integration cannot be done until Apple has approved your entitlement, which can take time.

To configure an iOS app for Tap to Phone, the Apple Developer provisioning profile must be enabled with the Tap to Pay on iPhone entitlement. Details on requesting and configuring this entitlement from Apple can be found in Apple’s developer documentation. Once Apple approves the entitlement, it can be enabled in your application's entitlements file:

com.apple.developer.proximity-reader.payment.acceptance = YES

Information property list

The following values are set through Info.plist variables:

Apple developer account ID

Set PRODUCT_TEAM_IDENTIFIER equal to your platform's Apple Developer Account ID.

Location permissions

Location permissions must be enabled by the application due Tap to Phone being available is select countries and regions. This will prompt the end user to allow their device's location to be shared when using the application. If they do not allow their location to be shared, then the Tap to Phone feature will not work.

Privacy - Location When In Use Usage Description = Location is required while using the app to process payments

The text for this field appears in the UI to the end user for them to share their location. Set it to something that let's the end user know you need access to their location to process Tap to Phone payments through the device.

Device registration

Each device with your platform's application must be registered as a Rainforest device registration.

Devices must be registered to a merchant in order to process payments, which is completed via the create device registration endpoint. You'll need to pass:

• registration_code: set to IOS_SDK
• merchant_id: the merchant to process payments on with the device
• device_name: the friendly name of the device, this will only appear in the Rainforest API and not in any Tap to Phone flows

{
    "registration_code": "IOS_SDK",
    "merchant_id": "sbx_mid_example",
    "device_name": "Example device"
}

The Device Registration ID will be utilized when presenting a payin and initiating the Tap to Phone payment flow through the Rainforest SDK. You should create a Rainforest Device Registration when your application is downloaded to the iOS device and represents that specific iOS device.

Each device that will utilize the Rainforest SDK for Tap to Phone must have it's own unique Rainforest Device Registration ID and cannot be shared across devices. Only one payin can be presented at a time on a Rainforest Device Registration.

Session permissions

Create a session to grant the SDK permissions to process a payin with the permission group payment_sdk and pass the session_key into the Rainforest SDK.

"statements": [
  {
    "permissions": ["group#payment_sdk"],
    "constraints": {
      "merchant": {
        "merchant_id": "REPLACE_ME"
      }
    }
  }
]

Rainforest iOS SDK

Rainforest will provide you with a ZIP file that contains the Rainforest SDK and its dependencies. Once downloaded, unzip the file. Move this directory to a place where you can reference it's location when adding dependencies to your application.

Versioning

The publicly available version will be an evergreen build during the beta phase. Once out of beta, the SDK version will follow semantic versioning principles.

Add dependencies to app

Framework dependencies are added through the applications settings, following these steps:

1. In Xcode navigator choose your project to open the settings views.
2. Select your application target > General > Frameworks, Libraries and Embedded Content
3. Click '+' icon to add three dependencies
   1. RainforestSDK - "Add Other" > select RainforestSDK.xcframework from the unzipped file provided by Rainforest. Set the "Embed" value to "Embed & Sign".
   2. RainforestSDK dependency package - "Add Other" > select CloudCommerce.xcframework from the unzipped file provided by Rainforest. Set the "Embed" value to "Embed & Sign".
   3. ProximityReader - Search for "proximity" and select "Apple SDKs > ProximityReader.framework"
4. "Embed & Sign" all necessary dependencies

Import the SDK

Once the Rainforest SDK is added as an dependency, you can import it into your code:

import RainforestSDK

SDK reference

The Rainforest iOS SDK exposes a generic interface through the RainforestPay namespace for initializing the Tap to Phone functionality and presenting a payin through the Tap to Phone flow.

To initialize the SDK, call RainforestPay.TapToPhone

Initialize the SDK

static public func TapToPhone(_ environment: Environment, sessionKey: String)

Initialize Tap to Phone

func prepare(deviceRegistrationId: String) async throws

Present a payin

func presentPayin(deviceRegistrationId: String, payinConfigId: String) async throws -> PaymentResponse

public struct PaymentResponse: {
    public var status: RainforestResponseStatus
    public var payin: PayinData
}

public enum RainforestResponseStatus: String, Decodable, Sendable {
  case success = "SUCCESS"
  case failure = "FAILURE"
}

public struct PayinData: Codable, Sendable {
  public let payinId: String
  public let status: String
  public let amount: Int

Cancel the presented payin

func cancelPresented(deviceRegistrationId: String) async throws

Resume the app

func resume(deviceRegistrationId: String) async throws

SDK errors

The following errors can be thrown

Evaluate the error code and message field for details about the error.

Code examples

Swift

import RainforestSDK


/*
Initialize the SDK instance during application normal "bootstrapping" lifecycle. You should maintain a reference to the SDK if not instantiated in the same scope.
*/
let tapSDK = RainforestPay.TapToPhone(.sandbox, sessionKey: "sbx_session_*****")

// ...

/*
Prepare the SDK with Tap to Phone functionality early in the payment lifecycle.
*/
do {
	try await tapSDK.prepare(
    deviceRegistrationId: "sbx_dvc_******"
  )
} catch {
	// handle prepare error  
}

// ...

/*
Present the payin on the device to initiate the Tap to Phone payment flow.
*/
do {
  try await tapSDK.presentPayin(
		payinConfigId: "sbx_cfg_******,
    deviceRegistrationId: "sbx_dvc_******"
  )
} catch {
 	// handle present error 
}

React Native

If your application is written in React Native, then you must create a bridge between your application and Rainforest's SDK written in Swift. Rainforest will provide a sample application demonstrating how to complete this integration.

Expo

If your application is written in Expo, then you must create a bridge between your application and Rainforest's SDK written in Swift. Rainforest will provide a sample application demonstrating how to complete this integration.

Flutter

If your application is written in Flutter, then you must create a bridge between your application and Rainforest's SDK written in Swift. Rainforest will provide a sample application demonstrating how to complete this integration.

Sandbox simulation

On Sandbox, Rainforest will not automatically process the presented payin on the device through the Tap to Phone payment flow. The end user will complete the Tap to Phone interaction, but you will need to complete the presentation of the payin on the device. This allows you to simulate the expected payin status and various cards and decline flows.

Device interactions

Once the payin has been presented on the device, the next step is asynchronous because you are waiting for the interaction to complete on the device.

You can simulate various scenarios with the simulate device interaction endpoint. For example, to test the case where a Visa card is tapped on the device and then successfully processes a payment, you would pass the event PRESENTED and the card VISA_SUCCESS:

{
    "event": "PRESENTED",
    "card": "VISA_SUCCESS"
}

Configure deposit report for billing

Tap to Phone does incur an additional billing fee. If you're passing the fee onto the merchant, then the deposit will include a billing adjustment.

Configure the Deposit Report Component to include the memo column in the Deposit Details activity report to provide the context on the billing adjustment to your merchant.

<rainforest-deposit-report
    activity-columns='[
    {"name":"Created","type":"builtin","value":"created_at"},
    {"name":"Type","type":"builtin","value":"type"},
    {"name":"ID","type":"builtin","value":"id"},
    {"name":"Memo","type":"builtin","value":"memo"},
    {"name":"Customer","type":"builtin","value":"billing_contact_name"},
    {"name":"Method","type":"builtin","value":"payment_method"},
    {"name":"Amount","type":"builtin","value":"gross_amount"},
    {"name":"Fees","type":"builtin","value":"billing_fees_amount"},
    {"name":"Net","type":"builtin","value":"net_amount"}
]'
></rainforest-deposit-report>