Home

Awesome

SumUp mPOS SDK - iOS

Platform Created Supports License CocoaPods SPM compatible

This repository provides a native iOS SDK that enables you to integrate SumUp's proprietary card terminal(s) and its payment platform to accept credit and debit card payments (incl. VISA, MasterCard, American Express and more). SumUp's SDK communicates transparently to the card terminal(s) via Bluetooth (BLE 4.0) or an audio cable connection. Upon initiating a checkout, the SDK guides your user using appropriate screens through each step of the payment process. As part of the process, SumUp also provides the card terminal setup screen, along with the cardholder signature verification screen. The checkout result is returned with the relevant data for your records.

No sensitive card data is ever passed through to or stored on the merchant’s phone. All data is encrypted by the card terminal, which has been fully certified to the highest industry standards (PCI, EMV I & II, Visa, MasterCard & Amex).

For more information, please refer to SumUp API documentation..

Prerequisites

  1. Registered for a merchant account via SumUp's country websites (or received a test account).
  2. Received SumUp card terminal: Solo, Air, Air Lite, PIN+ terminal, Chip & Signature reader, or SumUp Air Register.
  3. Requested an Affiliate (Access) Key via SumUp Dashboard for Developers.
  4. Deployment Target iOS 14.0 or later.
  5. Recommended to use on Xcode 14.3.1 and iOS SDK 16 or later.
  6. iPhone, iPad or iPod touch.

Compatibility

Tipping

There are three modes for tipping:

  1. No tipping. Leave tipAmount set to nil when creating the SMPCheckoutRequest object.

  2. Programmatic tipping via the tipAmount property. Ask the user in your own UI for an appropriate tip amount and then set the tipAmount property on SMPCheckoutRequest. This will be added to the total amount, but will be displayed to the user separately during checkout.

  3. Tip on Card Reader. TCR prompts the customer directly on the card reader's display for a tip amount, rather than prompting for a tip amount on the iPhone or iPad display.

Tip on Card Reader (TCR)

Important: Not all card readers support this feature. To find out if the feature is supported for the last-used card reader, you should always check SMPSumUpSDK.isTipOnCardReaderAvailable. You must handle this case yourself in order to avoid no tip from being prompted.

To do this:

Before calling SMPSumUpSDK checkoutWithRequest:fromViewController:completion:, check SMPSumUpSDK.isTipOnCardReaderAvailable:

Table of Contents

Installation

Manual Integration

The SumUp SDK is provided as an XCFramework SumUpSDK.xcframework that contains the headers and bundles bundles containing resources such as images and localizations. Please follow the steps below to prepare your project:

  1. Drag and drop the SumUpSDK.xcframework to your Xcode project's "Frameworks, Libraries, and Embedded Content" on the General settings tab.
  2. Make sure the required Info.plist keys are present.

Note: You can use the sample app that is provided with the SumUp SDK as a reference project. The Xcode project contains sample apps written in Objective-C and Swift. See Test your integration for more information.

Integration via CocoaPods

The SumUp SDK can be integrated via CocoaPods.

target '<Your Target Name>' do
    pod 'SumUpSDK', '~> 4.0'
end

Make sure the required Info.plist keys are present.

To learn more about setting up your project for CocoaPods, please refer to the official documentation.

Integration via Carthage

:warning: Distributing XCFrameworks with the latest Carthage version (0.35.0) is not yet available. There is an open issue (#2799) to solve this. Once that issue is fixed, we expect Carthage to work again.

The SumUp SDK can be integrated with Carthage by following the steps below:

  1. Add the following line to your Cartfile:

     github "sumup/sumup-ios-sdk"

  2. Run carthage update sumup-ios-sdk

  3. Drag and drop the Carthage/Build/iOS/SumUpSDK.xcframework to your Xcode project's "Frameworks, Libraries, and Embedded Content" on the General settings tab.

  4. Make sure the required Info.plist keys are present.

To learn more about setting up your project for Carthage, please refer to the official documentation.

Note: See Test your integration for more information.

Integration via Swift PM

The latest Swift Package Manager version added support to distribute binary frameworks as Swift Packages. Unfortunately there is a bug (Bug Report SR-13343), that adds the framework as a static library, not as an embedded dynamic framework. Follow this workaround to manage SumUp SDK versions via Swift PM:

Requirement: Xcode 12 beta 6 (swift-tools-version:5.3)

  1. Add the package dependency to the repository https://github.com/sumup/sumup-ios-sdk (File > Swift Packages > Add Package Dependency...) with the version Up to Next Major: 4.0.0
  2. Leave the checkbox unchecked for the SumUpSDK at the integration popup (Add Package to ...:) Swift PM - do not auto-integrate SDK
  3. From the Project Navigator, drag and drop the SumUpSDK/Referenced Binaries/SumUpSDK.xcframework to your Xcode project's "Frameworks, Libraries, and Embedded Content" on the General settings tab.
  4. Make sure the required Info.plist keys are present.

To learn more about adding Swift Package dependencies, please refer to the official documentation.

Test your integration

In your debug setup you can call +[SMPSumUpSDK testSDKIntegration]. It will run various checks and print its findings to the console. Please do not call it in your Release build.

Supported device orientation

The SDK supports all device orientations on iPad and portrait on iPhone. Feel free to support other orientations on iPhone but please keep in mind that the SDK's UI will be presented in portrait on iPhone. See UISupportedInterfaceOrientations in the sample app's Info.plist or the "General" tab in Xcode's Target Editor.

Privacy Info plist keys

The SumUp SDK requires access to the user's location and Bluetooth peripherals. If your app has not asked for the user's permission, the SumUp SDK will ask at the time of the first login or checkout attempt. Please add the following keys to your info plist file:

    NSLocationWhenInUseUsageDescription
    NSBluetoothAlwaysUsageDescription
    NSBluetoothPeripheralUsageDescription (unless your deployment target is at least iOS 13)

Note:

Getting started

Import the SDK

To import the SDK in Objective-C source files, you can use #import <SumUpSDK/SumUpSDK.h>. If module support is enabled in your project, you can use @import SumUpSDK; instead.

In Swift, use import SumUpSDK. You do not have to add any headers to your bridging header.

Authenticate app

Before calling any additional feature of the SumUp SDK, you are required to set up the SDK with your Affiliate (Access) Key:

[SMPSumUpSDK setupWithAPIKey:@"MyAPIKey"];

Note: setupWithAPIKey: checks for the user's location permission. Consequently, do not call this method as part of the app launch. This method must be called on the main queue.

Login

Following app authentication, a registered SumUp merchant account needs to be logged in. Present a login screen from your UIViewController, using the following method:

[SMPSumUpSDK presentLoginFromViewController:vc
                                   animated:YES
                            completionBlock:nil];

Note: It is also possible to login an account with a token, without the user entering their SumUp login credentials in the SDK. Please refer to section Transparent Authentication.

To log out of the SDK, please refer to logoutWithCompletionBlock:.

Accept card payments

Once logged in, you can start using the SumUp SDK to accept card payments.

Prepare checkout request

Prepare a checkout request that encapsulates the information regarding the transaction.

For this, you will need to create an instance of SMPCheckoutRequest:

SMPCheckoutRequest *request = [SMPCheckoutRequest requestWithTotal:[NSDecimalNumber decimalNumberWithString:@"10.00"]
                                                             title:@"your title"
                                                      currencyCode:[[SMPSumUpSDK currentMerchant] currencyCode]];

Please note that you need to pass an NSDecimalNumber as the total value. While NSDecimalNumber is a subclass of NSNumber it is not advised to use the convenience method of NSNumber to create an NSDecimalNumber.

Additional checkout parameters

When setting up the SMPCheckoutRequest object, the following optional parameters can be included:

Tip amount

A tip amount can be processed in addition to the totalAmount using the tipAmount parameter. The tip amount will then be shown during the checkout process and be included in the response. Please note that a tip amount cannot be changed during/after the checkout. Just like the totalAmount it is an NSDecimalNumber so make sure to not accidentally pass an NSNumber.

Transaction identifier

The foreignTransactionID identifier will be associated with the transaction and can be used to retrieve details related to the transaction. See API documentation for details. Please make sure that this ID is unique within the scope of the SumUp merchant account and sub-accounts. It must not be longer than 128 characters.

// set an optional identifier
[request setForeignTransactionID:@"my-unique-id"];
Skip success screen

To skip the screen shown at the end of a successful transaction, the SMPSkipScreenOptionSuccess option can be used. When setting this option your application is responsible for displaying the transaction result to the customer. In combination with the Receipts API, your application can also send your own receipts, see API documentation for details. Please note that success screens will still be shown when using the SumUp Air Lite readers.

Skip failed screen

To skip the screen shown at the end of a failed transaction, the SMPSkipScreenOptionFailed option can be used. When setting this option your application is responsible for displaying the transaction result to the customer. Please note that failed screens will still be shown when using the SumUp Air Lite readers.

Prepare the SumUp Card terminal in advance

In order to prepare a SumUp card terminal for checkout, prepareForCheckout can be called in advance. A registered SumUp merchant account needs to be logged in, and the card terminal must already be setup. You should use this method to let the SDK know that the user is most likely starting a checkout attempt soon; for example when entering an amount or adding products to a shopping cart. This allows the SDK to take appropriate measures, like attempting to wake a connected card terminal.

Transparent Authentication

To authenticate an account without the user typing in their SumUp credentials each time, you can generate an access token using OAuth2.0 and use it to transparently login to the SumUp SDK.

[SMPSumUpSDK loginWithToken:@"MY_ACCESS_TOKEN" 
                 completion:nil];

For information about how to obtain a token, please see the API Documentation.

If the token is invalid, SMPSumUpSDKErrorInvalidAccessToken will be returned.

Initiate Checkout Request

Start a payment by using the checkout request below:

[SMPSumUpSDK checkoutWithRequest:request
              fromViewController:vc
                      completion:^(SMPCheckoutResult *result, NSError *error) {
                      // handle completed and failed payments here
                      // retrieve information via result.additionalInfo
}];

Checkout Error Codes

Possible values of error code received in the checkoutWithRequest: completion block.

Update checkout preferences

When logged in you can let merchants check and update their checkout preferences. Merchants can select their preferred card terminal and set up a new one if needed. The preferences available to a merchant depend on their respective account settings.

[SMPSumUpSDK presentCheckoutPreferencesFromViewController:self
                                                 animated:YES
                                               completion:^(BOOL success, NSError * _Nullable error) {
                                                 if (!success) {
                                                   // there was a problem presenting the preferences
                                                 } else {
                                                   // next checkout will reflect the merchant's changes.
                                                 }
                                               }];

Tap to Pay on iPhone

With Tap to Pay on iPhone merchants can accept contactless card payments on their iPhone without needing a card reader.

To add Tap to Pay on iPhone to your app:

In your code:

Check feature availability

Perform activation if needed

Code example: checking availability and activation status

Objective-C

[SMPSumUpSDK checkTapToPayAvailability:^(BOOL isAvailable, BOOL isActivated, NSError * _Nullable error) {
    if (error == nil) {
        if (!isAvailable) {
            // Tap to Pay on iPhone is not available for the merchant
            return;
        }

        if (!isActivated) {
            // Tap to Pay on iPhone needs activation - call presentTapToPayActivation
            return;
        }

    // The app is ready to take Tap to Pay on iPhone payments!

    } else {
        // An error occurred
    }
}];

Swift

SumUpSDK.checkTapToPayAvailability { isAvailable, isActivated, error in

    if let error {
        // An error occurred
        return
    }

    if !isAvailable {
        // Tap to Pay on iPhone is not available for the merchant
        return
    }

    if !isActivated {
        // Tap to Pay on iPhone needs activation - call presentTapToPayActivation
        return
    }

    // The app is ready to take Tap to Pay on iPhone payments!
}

Do the checkout

Objective-C

SMPCheckoutRequest request = [SMPCheckoutRequest requestWithTotal:total
                                                            title:itemDescription
                                                     currencyCode:SMPSumUpSDK.currentMerchant.currencyCode
                                                    paymentMethod:SMPPaymentMethodTapToPay];

Swift

let request = CheckoutRequest(total: total, 
                              title: itemDescription,
                              currencyCode: SumUpSDK.currentMerchant?.currencyCode,
                              paymentMethod: .tapToPay)

Background initialization

When SMPSumUpSDK initializes, it triggers a background initialization process. This can take about 10-15 seconds and must be completed before the first Tap to Pay on iPhone card-read can occur. If the user quickly initiates a transaction after your app launches, it may take longer than usual as it first waits for the initialization to complete. For subsequent transactions, however, (until the app is relaunched) this delay should not happen.

Card Verification Method

Tap to Pay on iPhone supports contactless payments with physical cards or wallets (eg. Apple or Google Pay). When accepting payments with physical cards, additional card holder verification in a form of PIN may be required. In the majority of such cases, the UI will display a PIN pad where the customer can enter and confirm the digits. However, not every physical card allows this type of PIN processing. Some can only be processed by inserting the card into a physical card reader, which is not possible in the case of Tap to Pay on iPhone. In such an instance, the merchant should ask the customer to try a different card or payment method.

Best practices

Known issues

Out of Scope

The following functions are handled by the SumUp APIs:

Community

Changelog

SumUp iOS SDK Changelog

License

SumUp iOS SDK License