Swiftpack.co - Package - sumup/sumup-ios-sdk

SumUp mPOS SDK - iOS

Platform Created Supports Version License CocoaPods Carthage 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's integration website.

Prerequisites

  1. Registered for a merchant account via SumUp's country websites (or received a test account).
  2. Received SumUp card terminal: 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 10.0 or later.
  5. Xcode 11 and iOS SDK 13 or later.
  6. iPhone, iPad or iPod touch.

Table of Contents

Installation

If you want to support the SumUp Air Register, please also read our additional Air Register setup guide.

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](https://raw.github.com/sumup/sumup-ios-sdk/blob/master/#privacy-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, Bluetooth peripherals and the device's microphone. 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)
    NSMicrophoneUsageDescription

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: 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.

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
}];

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.
                                                 }
                                               }];

Out of Scope

The following functions are handled by the SumUp APIs:

Community

  • Questions? Get in contact with our integration team by sending an email to integration@sumup.com.
  • Found a bug? Open an issue. Please provide as much information as possible.

Changelog

SumUp iOS SDK Changelog

License

SumUp iOS SDK License

Github

link
Stars: 28

Dependencies

Used By

Total: 0

Releases

4.0.0: Xcode 12 compatibility - 2020-09-16 10:23:06

  • [CHANGED] The SumUp SDK is now a dynamic framework and is shipped as an XCFramework. If you had previous versions installed, check out the Migration Guide.
  • [CHANGED] The SMPSharedResources.bundle is now part of the XCFramework and should not be added to the app target
  • [REMOVED] Payment options provided when creating a checkout request will be ignored and default to .any. Options presented will be governed by merchant settings.
  • [ADDED] Added Swift Package Manager support. See integration instructions.
  • [BUGFIX] Remove pre-release version from CFBundleShortVersionString in XCFramework's Info.plist to pass ASC validation which requires this to be a period-separated list of at most three non-negative integers.
  • [UPDATE] Deprecated method +[SMPSumUpSDK checkoutWithRequest:fromViewController:completionBlock:] has been removed from the interface, please use +[SMPSumUpSDK checkoutWithRequest:fromViewController:completion:] instead.

Sample application:

  • [UPDATE] Do not provide payment options when creating a checkout request.
  • [UPDATE] Remove -ObjC from Other Linker Flags

:warning: The latest Carthage (0.35.0) is not yet compatible with XCFrameworks (#2799)

4.0.0-beta.1: Publish as an XCframework - 2020-09-01 15:35:32

  • [CHANGED] The SumUp SDK is now a dynamic framework and is shipped as an XCFramework. If you had previous versions installed, check out the Migration Guide.
  • [CHANGED] The SMPSharedResources.bundle is now part of the XCFramework and should not be added to the app target
  • :warning: The latest Carthage (0.35.0) is not yet compatible with XCFrameworks (#2799)

Sample application:

  • [UPDATE] Remove -ObjC from Other Linker Flags

3.5: Do not link against UIWebView, deployment target iOS 10.0 - 2020-08-26 16:53:26

This is the last version published as a static library. Upcoming versions will be provided as an xcframework to be compatible with future versions of Xcode.

  • [UPDATE] Deployment target raised to iOS 10.0
  • [UPDATE] This version of the SumUp SDK is built on Xcode 11.3.1 against iOS SDK 13.2
  • [UPDATE] Does not link against UIWebView to be compliant with ASC policy
  • [UPDATE] Sample apps' deployment target raised to iOS 10.0

Do not link against UIWebView, deployment target iOS 10.0 - 2020-05-17 23:44:31

  • [UPDATE] Deployment target raised to iOS 10.0
  • [UPDATE] This version of the SumUp SDK is built on Xcode 11.3.1 against iOS SDK 13.2
  • [UPDATE] Does not link against UIWebView to be compliant with ASC policy
  • [UPDATE] Sample apps' deployment target raised to iOS 10.0

3.4: Address an issue with trusted certificates on iOS 13 - 2019-11-13 17:52:58

SDK versions v3.3 and earlier are currently not able to connect to SumUp on iOS 13.3 Beta 1 and Beta 2.

3.3: Support for iOS 13 - 2019-09-12 16:43:49

  • [UPDATE] This version of the SumUp SDK is ready to be used with Xcode 11 and the iOS 13 SDK
  • [ADDED] Added support for the latest generation of SumUp's Air and PIN+ readers
  • [BUGFIX] Fix a crash in checkout preferences when trying to disable all options

3.2: Style updated to match our iOS app v2.0 - 2019-04-09 14:25:22

  • [UPDATE] Style updated to match our iOS app v2.0
  • [UPDATE] Base SDK updated to iOS 12, built with Xcode 10.1
  • [IMPROVEMENT] Location permissions are handled when presenting the login view controller. The merchant is asked to grant location permissions if needed and restricted from logging in when denied.
  • [IMPROVEMENT] Added a section to the README on how to integrate with Carthage. Heavily inspired by Zyphrax's help in PR #42 addressing issue #37.
  • [BUGFIX] Fix a crash in checkout when trying to use an audio connection to a PIN+ or C&S readers when microphone permissions have been denied.
  • [ADDED] Added support for the SumUp 3G reader

3.2b1: Style updated to match our iOS app v2.0 - 2019-02-04 09:47:49

  • [UPDATE] Style updated to match our iOS app v2.0
  • [UPDATE] Base SDK updated to iOS 12, built with Xcode 10.1
  • [IMPROVEMENT] Location permissions are handled when presenting the login view controller. The merchant is asked to grant location permissions if needed and restricted from logging in when denied.
  • [IMPROVEMENT] Added a section to the README on how to integrate with Carthage. Heavily inspired by Zyphrax's help in PR #42 addressing issue #37.
  • [BUGFIX] Fix a crash in checkout when trying to use an audio connection to a PIN+ or C&S readers when microphone permissions have been denied.

3.1: Deployment target raised to iOS 9 - 2018-08-20 16:06:34

  • [CHANGED] If you integrate the SDK manually, please link to the ExternalAccessory framework
  • [UPDATE] Deployment target raised to iOS 9.0
  • [CHANGED] The login mask does not show the "Reveal password" button anymore
  • [ADDED] SumUp Air Register support
  • [IMPROVEMENT] Dedicated error code for currency mismatches – please refer to our README for hints regarding correct currency handling
  • [IMPROVEMENT] Populate NSLocalizedDescriptionKey in SDK errors – you can still access NSUnderlyingErrorKey for more details regarding the underlying error
  • [ADDED] New currency code constant (CLP) and new languages (es-CL, et)

3.0: Support for iPhone X - 2017-12-14 15:02:54

  • [UPDATE] Update target SDK to iOS 11, deployment target raised to iOS 8.0
  • [REMOVED] Drop support for audio connection to first generation PIN+ devices. This implies that the YTLibResources.bundle has been removed.
  • [IMPROVEMENT] Add module map for Swift integration without bridging headers
  • [IMPROVEMENT] Prefer readonly properties over methods to improve Swift signatures
  • [ADDED] Add CocoaPods integration support – use pod SumUpSDK in your Podfile

Sample application:

  • [UPDATE] Update deployment target of Obj-C app to iOS 8
  • [UPDATE] AVFoundation is linked as required since weak linking was only needed when running on iOS 5
  • [IMPROVEMENT] Swift sample app uses modular imports instead of bridging headers

3.0b2: Target SDK iOS 11, deployment target iOS 8 - 2017-11-03 17:44:02

  • Added module map for Swift integration without bridging headers inspired by https://github.com/sumup/sumup-ios-sdk/pull/42

3.0b1: Target SDK iOS 11, deployment target iOS 8 - 2017-10-27 16:08:51

  • Drop support for audio connection to first generation PIN+ devices. This implies that the YTLibResources.bundle has been removed.
  • Add CocoaPods support, see SumUpSDK.podspec

Sample application:

  • Update deployment target of Obj-C app to iOS 8
  • AVFoundation is linked as required as weak linking was only needed when running on iOS 5

Transition Guide to 3.0

When improving imported Swift names we took the opportunity to rename and prefix some classes and enums. We've also renamed the SDK to SumUpSDK to make it easier to integrate with CocoaPods. Migrating your code base is easy.

  • Remove the SumupSDK.embeddedframework and add the new one called SumUpSDK.embeddedframework.
  • Rename your imports <SumupSDK/SumupSDK.h> to <SumUpSDK/SumUpSDK.h>
  • Rename all occurrences of SumUpCompletionBlock to SMPCompletionBlock
  • In Obj-C: rename all case-sensitive occurrences of SumupSDK to SMPSumUpSDK
  • In Swift: rename all case-sensitive occurrences of SumupSDK and SMPSumupSDK to SumUpSDK

Fix a crash on iPad Pro - 2017-09-27 13:51:35

  • [BUGFIX] Fix a crash in checkout on iPad Pro when building against iOS 11. See issue #51.
  • [IMPROVEMENT] Fix an outdated link to API docs. See issue #49.

Fix layout issues when building against iOS 11 - 2017-09-26 09:38:21

  • [IMPROVEMENT] Fix layout issues in login and checkout when building against iOS 11
  • [IMPROVEMENT] Add comment to point out that setupWithAPIKey: needs to be called on the main thread. See https://github.com/sumup/sumup-ios-sdk/issues/46

Add option add tip and skip the success screen - 2017-06-08 17:59:38

  • [IMPROVEMENT] Support for future SumUp terminal.
  • [ADDED] Add SMPSkipScreenOptions to allow for skipping the screen shown at the end of a successful transaction.
  • [ADDED] Add -[SMPCheckoutRequest tipAmount] to provide an additional tip amount to be added to the total in checkout.

Sample application:

  • [ADDED] Add option to skip the receipt screen by setting the appropriate SMPSkipScreenOptions of the checkout request.
  • [ADDED] Add option to specify tip amount.
  • [IMPROVEMENT] Convert to Auto Layout

Add method to prepare a checkout - 2017-03-24 09:06:57

  • [BUGFIX] Fix a crash when trying to re-connect to an Air/PIN+ terminal, see issue #33
  • [ADDED] Add +[SumupSDK prepareForCheckout] to prepare the SDK when a checkout attempt is imminent.
  • [ADDED] Add +[SumupSDK testSDKIntegration] to validate your integration. Please do not call in Release builds but only in development.
  • [IMPROVEMENT] Speed up wake on Bluetooth
  • [IMPROVEMENT] Fix an issue where subsequent checkout attempts would keep failing when BT connection to Air/PIN+ Terminal has been lost during checkout

Sample application:

  • [ADDED] Tapping "Next" on the keyboard when entering an amount will wake a connected terminal by calling +[SumupSDK prepareForCheckout].
  • [ADDED] Run +[SumupSDK testSDKIntegration] when building in Debug configuration.

Add method to present checkout preferences - 2017-02-02 15:18:25

  • [ADDED] Provide method to let merchants change their checkout preferences +[SumupSDK presentCheckoutPreferencesFromViewController:animated:completion:]

Sample application:

  • [ADDED] Add button to present checkout preferences
  • [BUGFIX] Add missing -ObjC linker flag to Swift sample app

Layout improvements for iPhone 6, 6 Plus and iPad Pro - 2016-12-22 08:16:16

Deployment target changed to iOS 6.

  • [UPDATE] Base SDK is iOS 9.3, deployment target is iOS 6
  • [ADDED] Provide additional information on transaction and payment instrument in -[SMPCheckoutResult additionalInfo].
  • [ADDED] New terminal including US support
  • [BUGFIX] Fix an issue where some C&S transactions and mobile payments would incorrectly be reported as failed
  • [IMPROVEMENT] Improve layout on iPhone 6, iPhone 6 Plus, and iPad Pro
  • [IMPROVEMENT] Match style of SumUp iOS app version 1.60 and later
  • [IMPROVEMENT] Improve support of Wake-on-Bluetooth PIN+ readers
  • [IMPROVEMENT] Add nullability annotations
  • [IMPROVEMENT] Prefix some internal classes to avoid duplicated symbols

Support latest Air and Air Lite terminals - 2016-12-22 08:14:12

Important: This release includes an updated certificate - Certificates included in any previous SDK version will expire Friday, 24th Feb 2017. Please make sure to update to this version until then.

  • [IMPROVEMENT] Support latest Air and Air Lite terminals
  • [IMPROVEMENT] Hosting app is no longer required to support any landscape device orientation on iPhone
  • [IMPROVEMENT] Assert that SMPSharedResources is available when setting up SDK on simulator
  • [ADDED] Includes upcoming SSL certificate - Certificates included in any previous SDK version will expire Friday, 24th Feb 2017
  • [ADDED] Swift sample app