On This Page
Getting Started with the Tap to Pay on iPhone Solution
Use this information to get started with integrating the Tap to Pay on iPhone Solution.
After completing the integration, you can start accepting payments. For more
information, see Tap to Pay on iPhone Payment Services.
Configuring the Tap to Pay on iPhone SDK
Use this information to configure the Tap to Pay on iPhone SDK.
Add the Tap to Pay on iPhone SDK to Your Xcode Project
To complete this task, the ThinClient framework must be available to be copied. To
obtain the framework, contact your implementation manager.
Follow these steps to add the Tap to Pay on iPhone SDK to your Xcode project.
IMPORTANT
Stay current with the latest SDK. The SDK repository is
continuously updated to make available the six latest versions. When a new version
is released, the oldest is removed and can no longer be used for new application
builds. Establish a regular process for updating to the newest available SDK version
to avoid potential build failures and to ensure that your application runs with the
latest features, performance enhancements, and security updates.
- In the Xcode app, clickFile.
- ClickAdd Package Dependencies.
- In the search bar, enter this GitHub link: acceptance-devices-ios-sdk.
- Set the Dependency Rule toUp to Next Major Version.
- Open theAdd to Targetdrop-down menu, then choose your app.
- ClickAdd Package.
Request the Tap to Pay on iPhone Entitlement
You must have an Apple Developer account to complete this task. Use this link to create an account or to sign in to your existing account.
To use the Tap to Pay on iPhone solution, you must request the Tap to Pay on iPhone
entitlement from Apple and configure your application to use it.
- Configure your application to use the Tap to Pay on iPhone entitlement. For more information, see Setting up Tap to Pay on iPhone in the Apple Developer documentation.
Create a Sandbox Apple Account to Test Your Integration
Before you can test your Tap to Pay on iPhone integration in a sandbox environment,
you must create a Sandbox Apple account.
Follow these steps to create a Sandbox Apple Account.
- See the Apple Developer documentation: Create a Sandbox Apple Account.
- Sign in to your Sandbox Apple account from the device on which you will test transactions.
Generating a Secret Key for an Existing Merchant ID
Use this information to generate a secret key for an existing merchant ID (MID) in the
Business Center
or by using a REST API request. The secret key and MID are
required values that you must enter in the mposUi
instance that you
create. For more information, see Creating an mposUI Instance.Generate a Secret Key for an Existing Merchant ID in the Business Center
You can generate a secret key for an existing merchant ID (MID) in the
Business Center
. You must enter this value in the
mposUi
instance that you create. For more information, see Creating an mposUI Instance.Follow these steps to generate a secret key for an existing MID in the
Business Center
.- In theBusiness Center, go to the left navigation panel and choosePayment Configuration > Key Management. The Key Management page appears.
- From the Merchant drop-down list, choose a merchant ID.
- ClickGenerate Key.
- In the Recommended Key Types list, scroll down and chooseAcceptance Devices Secret Key.
- ClickGenerate Key. The Key Generation page appears.
- ClickGenerate Key. Your MID and secret key appear on the page.
- Click theCopyorDownloadicon to obtain the MID and secret key.
ADDITIONAL INFORMATION
IMPORTANTIf you choose to copy the secret key instead of downloading it, save the information locally because you cannot return to theBusiness CenterKey Generation page to obtain the same secret key. You must restart the process to obtain a new secret key.
Generate a Secret Key for an Existing Merchant ID Using a REST API Request
You can use a REST API request to generate a secret key for an existing merchant ID
(MID). You must enter this value in the
mposUi
instance you create. For
more information, see Creating an mposUI Instance.You must authenticate each request that you send to a
Cybersource
API. To
authenticate an API request, you can use a REST shared secret key or a REST certificate.
For more information about authentication requirements, see the .Endpoints:
Test:
POST
https://apitest.cybersource.com
/kms/v2/keys-sym-posProduction:
POST
https://api.cybersource.com
/kms/v2/keys-sym-posRequired Fields to Generate a Secret Key for an Existing Merchant ID Using a REST API
Request
This field is required to generate a secret key for an existing merchant ID when using a REST API
request:
- keyInformation.organizationId
REST Example: Generate a Secret Key for an Existing Merchant ID Using a REST API
Request
Request
{ "keyInformation": [ { "organizationId": "transacting_MID" } ] }
Response to a Successful Request
{ "submitTimeUtc": "2023-08-07T13:07:17Z", "status": "ACCEPTED", "keyInformation": [ { "organizationId": "transacting_MID", "externalOrganizationId": "MerchantId", "key": "SecretKey", "keyId": "af922a42-6d2c-41fd-92f7-09d908647de4", "status": "ACTIVE", "expirationDate": "2033-08-07T13:07:17Z" } ] }
Creating an mposUI Instance
Use this information to create and configure an
mposUI
instance. Before
creating an mposUI
instance, you must create the
Credentials
and Configuration
objects.Create an mposUI Credentials Object
mposUI
Credentials ObjectBefore starting this task, obtain a merchant ID and secret key. For more
information, see Generating a Secret Key for an Existing Merchant ID.
The
mposUI Credentials
object is required in order to access the
functionality of the Tap to Pay on iPhone SDK. You must create this object before you
can create an mposUI
instance. Follow these steps to create the
mposUI Credentials
object.- ImportMposUI.
- Create aCredentialsobject.
- Set themerchantfield value to the merchant ID that you obtained.
- Set thesecretfield value to the secret key that you obtained.
- Set theenvironmentfield value totestor tolive.
- Use thetestsetting to test your integration without charging a real payment card. Use the merchant ID and secret key that you obtained from the test environment.
- Use thelivesetting to process live transactions. Use the merchant ID and secret key that you obtained from the production environment.
import MposUI let credentials = Credentials(merchant: "MerchantId", secret: "SecretKey", environment: .live)
Create an mposUI Configuration Object
mposUI
Configuration ObjectTo create and use the
mposUI
instance with the Tap to Pay on
iPhone SDK, you must create the mposUI Configuration
object.Use the
Configuration
object to configure these parameters for the
mposUI
instance:- Configure these Summary screen features:
- Refund a transaction (.refundTransaction).
- Send a receipt by email (.sendReceiptViaEmail).
- Capture a transaction (.captureTransaction).
- Increment a transaction (.incrementTransaction).
- Re-try a failed transaction (.retryTransaction).
- Configure the Summary screen so that it can be skipped (.skipSummaryScreen). The default setting is to show the Summary screen (.displayIndefinitely).
- Configure the signature capture so that it prints on the paper receipt (.onReceipt) or is skipped (.none). The default setting is on-screen signature capture.
- Configure the enrollment process to prompt the merchant to enter the serial number of a previously enrolled device (.manualInput). The default setting is to show a list of previously enrolled devices and prompt the merchant to choose a device from the list (.deviceList).
- Configure the Serial Number Confirmation screen to be skipped (.skip). The default setting is to show the screen (.showWithSerialNumber).
Follow this step to create the
mposUI Configuration
object.- Create theConfigurationobject.let configuration = Configuration(summaryFeatures: [.sendReceiptViaEmail, .refundTransaction, .captureTransaction, .incrementTransaction, .retryTransaction], resultConfiguration: .displayIndefinitely, signatureCapture: .onScreen, enrollmentConfiguration: .init(serialNumberInputMethod: deviceList, confirmationScreenOption: showWithSerialNumber) )
Create an mposUI Instance
mposUI
InstanceBefore you can create the
mposUI
instance, create and configure the
Credentials
and Configuration
objects.Follow this step to create the
mposUI
instance.- Create themposUIinstance.let mposUi = await mposUiBuilder(credentials: credentials, configuration: configuration)
Managing Device Enrollment
Use this information to manage device enrollment in the Tap to Pay on iPhone SDK. The
enrollment workflow guides you through the device enrollment activity.
Enroll a New Device
Use the
enroll
function to enroll a new device. This function shows
options in a merchant-facing UI for enrolling a new device.switch await mposUi.enroll() { case .success(let deviceId): print("Enrollment successful with device id: %@", deviceId) case .cancelledByUser: print("Enrollment cancelled.") case .error(let developerInfo): print("Enrollment failed. Info: %@", developerInfo) }
Enroll a Previously Enrolled Device
Use the
enroll
function to enroll a previously enrolled device. This
function enables you to perform device re-enrollment through the SDK by supplying a
stored serial number. The streamlined workflow eliminates the need for the merchant
to manually select or enter the serial number during re-enrollment.switch await mposUi.enroll(with: "serialNumber") { case .success(let deviceId): print("Enrollment successful with device id: %@", deviceId) case .cancelledByUser: print("Enrollment cancelled.") case .error(let developerInfo): print("Enrollment failed. Info: %@", developerInfo) }
View the Device Enrollment Result
Before you can view the device enrollment result, you must enroll a device.
Use the
enrollmentStatus
function to view the device enrollment result.switch await mposUi.enrollmentStatus() { case .enrolled: print("Device enrolled.") case .enrolling: print("Enrollment in progress. Please do not start a new one.") case .notEnrolled: print("Device not enrolled. Please enroll device.") }
Show Merchant Education Screens
When a device enrollment 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. For more information about the object, see the Apple Developer
documentation: ProximityReaderDiscovery.