FILTER BY TAG

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.
  1. In the Xcode app, click
    File
    .
  2. Click
    Add Package Dependencies
    .
  3. In the search bar, enter this GitHub link: acceptance-devices-ios-sdk.
  4. Set the Dependency Rule to
    Up to Next Major Version
    .
  5. Open the
    Add to Target
    drop-down menu, then choose your app.
  6. Click
    Add 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.
  1. 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.
  1. See the Apple Developer documentation: Create a Sandbox Apple Account.
  2. 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
.
  1. In the
    Business Center
    , go to the left navigation panel and choose
    Payment Configuration > Key Management
    . The Key Management page appears.
  2. From the Merchant drop-down list, choose a merchant ID.
  3. Click
    Generate Key
    .
  4. In the Recommended Key Types list, scroll down and choose
    Acceptance Devices Secret Key
    .
  5. Click
    Generate Key
    . The Key Generation page appears.
  6. Click
    Generate Key
    . Your MID and secret key appear on the page.
  7. Click the
    Copy
    or
    Download
    icon to obtain the MID and secret key.

    ADDITIONAL INFORMATION

    IMPORTANT
    If you choose to copy the secret key instead of downloading it, save the information locally because you cannot return to the
    Business Center
    Key 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-pos
Production:
POST
https://api.cybersource.com
/kms/v2/keys-sym-pos

Required 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

Before 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.
  1. Import
    MposUI
    .
  2. Create a
    Credentials
    object.
  3. Set the
    merchant
    field value to the merchant ID that you obtained.
  4. Set the
    secret
    field value to the secret key that you obtained.
  5. Set the
    environment
    field value to
    test
    or to
    live
    .
    • Use the
      test
      setting 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 the
      live
      setting 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

To 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.
  1. Create the
    Configuration
    object.
    let configuration = Configuration(summaryFeatures: [.sendReceiptViaEmail, .refundTransaction, .captureTransaction, .incrementTransaction, .retryTransaction], resultConfiguration: .displayIndefinitely, signatureCapture: .onScreen, enrollmentConfiguration: .init(serialNumberInputMethod: deviceList, confirmationScreenOption: showWithSerialNumber) )

Create an
mposUI
Instance

Before you can create the
mposUI
instance, create and configure the
Credentials
and
Configuration
 objects.
Follow this step to create the
mposUI
instance.
  1. Create the
    mposUI
    instance.
    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.