The iZettle SDK makes it possible to accept card payments with an iZettle card reader from any iOS app. When triggered, it will display a screen over the host application where all interaction takes place. It is designed to be easy to implement and use.
- Take card payments with an iZettle card reader.
- Refund card payments.
- Receive information about a payment.
- Login/logout of iZettle accounts and simple switching between multiple accounts.
- Settings screen where the user can handle card readers and access help and support.
- The SDK will only work on markets where iZettle is operating, please visit iZettle.com for more information.
- It does not currently support other payment methods than cards.
- iOS 8 or later
- Xcode 7 (iOS 9 SDK)
- An iZettle API Key. Visit iZettle Developer Page in order to obtain one. Note: SDK API keys work only for bundle identifiers which they were issued for.
You can install iZettle SDK in several ways:
CocoaPods is an easy way to install iZettleSDK.
- Add following pod to your
Podfile
:
platform :ios, '8.0'
target 'Your App' do
pod 'iZettleSDK'
end
- Create a new “Run Script Phase” in your app’s target’s “Build Phases” and paste the following snippet in the script text field:
bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/iZettleSDK.framework/strip-frameworks.sh"
This step is required to work around an App Store submission bug when archiving universal binaries.
Since iZettle SDK is distributed as a binary, you need to use custom binary
rule in your Cartfile
.
- Add following to your
Cartfile
:
binary "https://raw.githubusercontent.com/iZettle/sdk-ios/master/Carthage/iZettleSDK.json" >= 1.6.1
- Fetch frameworks by running:
$ carthage update iZettleSDK
- Add the iZettle frameworks to Embedded Frameworks for your target:
iZettleSDK.framework
iZettlePayments.framework
iZettleShared.framework
- Make sure you link with the following frameworks and libraries:
iZettleSDK.framework
iZettlePayments.framework
iZettleShared.framework
Accelerate.framework
AudioToolbox.framework
AVFoundation.framework
CoreData.framework
CoreLocation.framework
ExternalAccessory.framework
libc++.tdb
libz.tdb
MediaPlayer.framework
MessageUI.framework
SystemConfiguration.framework
QuartzCore.framework
- Create a new “Run Script Phase” in your app’s target’s “Build Phases” and paste the following snippet in the script text field:
bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/iZettleSDK.framework/strip-frameworks.sh"
This step is required to work around an App Store submission bug when archiving universal binaries.
To be able to use iZettle SDK you need to setup several things first
Add/modify the property "Supported external accessory protocols" and add com.miura.shuttle.izettle and com.izettle.cardreader-one
This is what it should look like in the "source code" view of your info.plist:
<key>UISupportedExternalAccessoryProtocols</key>
<array>
<string>com.izettle.cardreader-one</string>
<string>com.miura.shuttle.izettle</string>
</array>
Important
The iZettle bluetooth card readers are part of the Apple MFi program. In order to release apps supporting accessories that are part of the MFi Program, you have to apply at Apple. Please contact us at sdk@izettle.com and we will help you with this process.
Enable support for external accessory communication from the Background modes section of the Capabilities tab in your Xcode project.
You can also enable this support by including the UIBackgroundModes key with the external-accessory
value in your app’s Info.plist file:
<key>UIBackgroundModes</key>
<array>
<string>external-accessory</string>
</array>
iZettle will prompt the user for permission during the first payment if the merchant haven't already
granted your app this permission. On iOS8, iZettle will execute CLLocationManagers method
requestWhenInUseAuthorization
.
Add the keys:
NSLocationUsageDescription
(iOS7)NSLocationWhenInUseUsageDescription
(iOS8)
Suggested value for the keys above is "You need to allow this to be able to accept card payments."
iZettle won't accept payments without these texts implemented.
Make sure to include the iZettle SDK framework:
Objective C:
@import iZettleSDK;
Swift:
import iZettleSDK
Before you execute any operations in iZettle SDK, you have to start the SDK with your API key. This is
typically done in your AppDelegates method application:didFinishLaunchingWithOptions:
.
Objective C:
- (void)startWithAPIKey:(NSString *)apiKey;
Swift:
open func start(with APIKey: String)
For example:
Objective C:
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
[[iZettleSDK shared] startWithAPIKey:@"API_KEY"];
return YES;
}
Swift:
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
iZettleSDK.shared().start(with: "API_KEY")
return true
}
Important: Only use the singleton instance returned from [iZettleSDK shared]
(in Objective C) or iZettleSDK.shared()
(in Swift) when calling the methods below.
Asynchronous operations have a completion block as an argument, the completion block is called when an operation is considered complete, cancelled or failed. See iZettleOperationCompletion for more information.
iZettle SDK will handle presentation and dismissal of its views. Operations with UI will accept a UIViewController as an argument from which iZettle SDK will be presented.
If the user isn't yet authenticated with iZettle when an operation is presented, a login screen will automatically be displayed.
Perform a payment with an amount and a reference:
- (void)chargeAmount:(NSDecimalNumber *)amount
currency:(NSString *)currency
reference:(NSString *)reference
presentFromViewController:(UIViewController *)viewController
completion:(iZettleOperationCompletion)completion;
open func charge(amount: NSDecimalNumber,
currency: String?,
enableTipping: Bool,
reference: String?,
presentFrom viewController: UIViewController,
completion: @escaping iZettleSDK.iZettleSDKOperationCompletion)
amount
: The amount to be charged in the logged in users currency.enableTipping
: Perform payment with tipping flowcurrency
(optional): Only used for validation. If the value of this parameter doesn't match the users currency the user will be notified and then logged out. For a complete list of valid currency codes, see ISO 4217reference
(optional): The payment reference. Used to identify an iZettle payment, used when retrieving payment information at a later time or performing a refund. Max length 128.
Passing enableTipping
to the charge(amount:)
call does not guarantee that tipping flow will be displayed. This is because tipping is not supported by all accounts and all card readers. Tipping is only supported with the iZettle Card Reader. The function is introduced market by market. If card reader software doesn’t support tipping, users will be prompted to either skip tipping or update card reader software.
Total tip amount is presented in iZettleSDKOperationCompletion
completion with gratuityAmount
property.
More documentation on the tipping flow can be found here
Refund an amount from a payment with a given reference.
- (void)refundAmount:(nullable NSDecimalNumber *)amount
ofPaymentWithReference:(NSString *)reference
refundReference:(nullable NSString *)refundReference
presentFromViewController:(UIViewController *)viewController
completion:(iZettleSDKOperationCompletion)completion;
open func refund(amount: NSDecimalNumber?,
ofPayment reference: String,
withRefundReference refundReference: String?,
presentFrom viewController: UIViewController,
completion: @escaping iZettleSDK.iZettleSDKOperationCompletion)
amount
(optional): The amount to be refunded from the payment (passingnil
will refund full amount of original payment)reference
: The reference of the payment that is to be refunded.refundReference
(optional): The reference of the refund. Max length 128.
Note: Demo accounts (accounts that automatically revert performed payments) cannot be used to perform refunds. To test refund functionality please use a standard production iZettle account.
Query iZettle for payment information of a payment with a given reference.
- (void)retrievePaymentInfoForReference:(NSString *)reference
completion:(iZettleOperationCompletion)completion;
open func retrievePaymentInfo(for reference: String,
presentFrom viewController: UIViewController,
completion: @escaping iZettleSDK.iZettleSDKOperationCompletion)
Present iZettle settings view. The user can switch account, access the iZettle FAQ, view card reader settings etc.
- (void)presentSettingsFromViewController:(UIViewController *)viewController;
open func presentSettings(from viewController: UIViewController)
Attempt aborting the ongoing operation. Only use this if absolutely necessary. The state of the payment will be unknown to the user after this call.
- (void)abortOperation;
open func abortOperation()
enforcedUserAccount
(optional): If set, operations will be restricted to only work for the specified iZettle username.
By setting the shared instance property enforcedUserAccount
to an iZettle username, subsequent operations will be restricted to only be performed on that account. If the set enforced user account was not previously logged in, an iZettle login prompt will be presented with a readonly email field prefilled with the enforced user account. If the enforced user account was already logged in (even though another account has been used in between), the account will be switched to use the enforced user account instead.
If enforcedUserAccount
is set to nil, any iZettle account can be used, and the email field will be editable.
Enforced user account can be changed between operations to allow switching between different users for different operations. This is useful for integrators supporting multiple accounts.
Preferably integrating apps will provide a settings page where the user can enter their iZettle account (used to set the enforced user account).
Object that contains information about a payment and the card used.
amount
- Total transaction amount (also includes tip amount if applicable)gratuityAmount
- Contains total tip amount if tipping is performedreferenceNumber
- iZettles reference to the payment (not to be confused with the reference provided by you during a charge or refund operation)entryMode
- EMV, CONTACTLESS_EMV, MAGSTRIPE_CONTACTLESS, MAGSTRIPE etc. More entry modes might be added independent of SDK versionobfuscatedPan
- e.g. "**** **** **** 1111"panHash
- a hash of the pancardBrand
authorizationCode
AID
TSI
TVR
applicationName
numberOfInstallments
installmentAmount
* These fields are only available for some entry modes. Don't rely on them being present.
entryMode = EMV
obfuscatedPan = "**** **** **** 0640"
panHash = 0092C7D95900033B84CE08B43F7E973485FB7081
cardBrand = MASTERCARD
authorizationCode = 007602
AID = A0000000041010
TSI = 4000
TVR = 8000000000
applicationName = MasterCard
entryMode = CONTACTLESS_EMV
obfuscatedPan = "**** **** **** 0640"
panHash = 0092C7D95900033B84CE08B43F7E973485FB7081
cardBrand = MASTERCARD
authorizationCode = 007602
AID = A0000000041010
TVR = 8000000000
applicationName = MasterCard
entryMode = MAGSTRIPE
obfuscatedPan = "**** **** **** 2481"
panHash = 99426D012C6740D9AEC8E26580E8640A196E3C27
cardBrand = MASTERCARD
authorizationCode = 004601
iZettle will display any errors that occur during an operation to the user, the NSError-object returned in the operation completion block is only intended to be used by developers for debugging, diagnostics and logging to be able to better communicate errors to iZettle. You should never present the returned errors to the end user.