On This Page

Managing Device Activation

Before you can use a device to process transactions, it must be activated. Activation registers the device with the payment platform. Use this information to manage device activation in the Tap to Pay on iPhone SDK.

IMPORTANT

Things to know about migrating from SDK 3.5.0 to SDK 3.6.0:

The term

Enrollment

was replaced with

Activation

throughout the SDK.

The

mposUI.enroll()

method was replaced with

reader.activation()

, followed by

activation.activate(credentials:environment:)

The

mposUI.enroll(with: serialNumber)

method was replaced with

activation.activate(credentials:environment:deviceId:)

The

mposUI.enrollmentStatus()

method was replaced with

reader.activationStatus

, which is now an asynchronous property, not a method.

The

.enrolling

intermediate status no longer exists.

Update your application code to handle these new result cases:

.alreadyActivated

and

.activatedToAnotherMerchant

Activate a New Device Using Credentials

Use this information to activate a new device using credentials. When you activate the device, specify whether the device is used in the production environment or the sandbox environment.

In the code example, the

environment

parameter is set to

.live

so that the device can be used to process real transactions. To activate a device for use in sandbox testing, set the

environment

parameter to

.test

Call

reader.activation()

to get an

MposUIActivation

object, and then call

activate(credentials:environment:)

with credentials and your chosen environment.

let activation = try await reader.activation()
let result: ActivationResult = await activation.activate(
    credentials: credentials,
    environment: .live
)

switch result {
case .success(let device, let isNewDevice):
    print("Merchant: \(device.merchantId)")
    print("Device ID: \(device.deviceId)")
    print("Env: \(device.environment)")
    print("Currencies: \(device.supportedCurrencies)")
case .cancelledByUser:
    print("Activation cancelled.")
case .error(let developerInfo):
    print("Activation failed. Info: \(developerInfo)")
@unknown default:
    break
}

Activate a New Device Using an Activation Code

Use this information to activate a new device using an activation code. The activation code can be generated in the Business Center and is valid for 24 hours.

There are two options for using an activation code to activate a new device. The merchant can enter the activation code on the device screen or the activation code can be passed programmatically.

NOTE

The activation code must be sourced from a trusted backend channel and must never be logged or persisted on the device.

In the code example, the

environment

parameter in the

activateWithOtp(environment:)

call is set to

.live

so the device can be used to process real transactions. To activate a device for use in sandbox testing, set the

environment

parameter to

.test

Call

reader.activation()

to get an

MposUIActivation

object, and then call

activateWithOtp(environment:)

with your chosen environment.

let activation = try await reader.activation()
let result: ActivationResult = await activation.activateWithOtp(
    environment: .live,
    otp: nil
)

switch result {
case .success(let device, let isNewDevice):
    print("Activated. Merchant: \(device.merchantId)")
case .cancelledByUser:
    print("Activation cancelled.")
case .invalidOTP(let developerInfo):
    print("Invalid OTP. Info: \(developerInfo)")
case .error(let developerInfo):
    print("Activation failed. Info: \(developerInfo)")
@unknown default:
    break
}

Reactivate a Previously Activated Device Using Credentials

Use this information to reactivate a previously activated device by using credentials and a stored serial number (

deviceId

, as shown in the code example). Supplying the stored device ID streamlines the activation workflow because the merchant does not need to manually select or enter the device ID during activation.

In the code example, the

environment

parameter in the

activate(credentials:environment:deviceId:)

call is set to

.live

so the device can be used to process real transactions. To activate a device for use in sandbox testing, set the

environment

parameter to

.test

Call

reader.activation()

to get an

MposUIActivation

object, and then call

activate(credentials:environment:deviceId:)

with credentials, your chosen environment, and the stored device ID.

let activation = try await reader.activation()
let result: ActivationResult = await activation.activate(
    credentials: credentials,
    environment: .live,
    deviceId: "deviceId"
)

switch result {
case .success(let device, let isNewDevice):
    print("Reactivated. Merchant: \(device.merchantId)")
    print("Device ID: \(device.deviceId)")
case .cancelledByUser:
    print("Activation cancelled.")
case .error(let developerInfo):
    print("Activation failed. Info: \(developerInfo)")
@unknown default:
    break
}

Reactivate a Previously Activated Device Using an Activation Code

Use this information to reactivate a previously activated device by using an activation code and a stored serial number (

deviceId

, as shown in the code example). The activation code can be generated in the Business Center and is valid for 24 hours.

Supplying the stored device ID streamlines the activation workflow because the merchant does not need to manually select or enter the device ID during activation.

There are two options for using an activation code during the device reactivation process. The merchant can enter the activation code on the device screen or the activation code can be passed programmatically.

NOTE

The activation code must be sourced from a trusted backend channel and must never be logged or persisted on the device.

In the code example, the

environment

parameter in the

activateWithOtp(environment:deviceId:)

call is set to

.live

so the device can be used to process real transactions. To activate a device for use in sandbox testing, set the

environment

parameter to

.test

Call

reader.activation()

to get an

MposUIActivation

object, and then call

activateWithOtp(environment:deviceId:)

with your chosen environment and the stored device ID.

let activation = try await reader.activation()
let result: ActivationResult = await activation.activateWithOtp(
    environment: .live,
    deviceId: "deviceId"
)

switch result {
case .success(let deviceId, let isNewDevice, let supportedCurrencies):
    print("Activation successful. Device ID: \(deviceId)")
case .cancelledByUser:
    print("Activation cancelled.")
case .alreadyActivated:
    print("Device is already activated for this merchant.")
case .activatedToAnotherMerchant:
    print("Device is activated to a different merchant.")
case .error(let developerInfo):
    print("Activation failed. Info: \(developerInfo)")
}

Check Activation Status

You can check the activation status only for a previously activated device.

Use the

activationStatus

property to check whether the device is activated.

let status: ActivationStatus = await reader.activationStatus

switch status {
case .activated(let info):
    print("Merchant: \(info.merchantId)")
    print("Device:   \(info.deviceId)")
    print("Env:      \(info.environment)")
    print("Currencies: \(info.supportedCurrencies)")
case .notActivated:
    print("Device not activated. Please activate the device.")
}

Show Merchant Education Screens

When a device activation is completed successfully, the Merchant Education screens must show on the device. The Merchant Education screens also must be accessible in your app's Settings or Help section.

Use Apple's

ProximityReaderDiscovery

object to show the Merchant Education screens. This object provides the UI with information about how to use Tap to Pay on iPhone.