Manage card payments
The following describes how to work with the iOS SDK payment operations charging, refunding, and fetching payment information.
About SDK operations
Important notice when calling the methods described here:
- In Objective C, only use the singleton instance returned from
[iZettleSDK shared]. - In Swift, only use the singleton instance returned from
iZettleSDK.shared().
The iOS SDK will handle presentation and dismissal of its views. Operations with UI will accept a UIViewController as an argument. From this the Zettle SDK will be presented. A login screen is displayed if the user has not yet been authenticated with Zettle.
Asynchronous operations have a completion block as an argument. This completion block is called when an operation is considered complete, cancelled or failed. See iZettleOperationCompletion.
Charging
The following example describes how to perform a payment with an amount and a reference.
Objective C
1- (void)chargeAmount:(NSDecimalNumber *)amount2enableTipping:(BOOL)enableTipping3reference:(NSString *)reference4presentFromViewController:(UIViewController *)viewController5completion:(iZettleOperationCompletion)completion;
Swift
1open func charge(amount: NSDecimalNumber,2currency: String?,3enableTipping: Bool,4reference: String?,5presentFrom viewController: UIViewController,6completion: @escaping iZettleSDK.iZettleSDKOperationCompletion)
amount: The amount to be charged in the logged in users currency.enableTipping: Perform payment with tipping flow.currency(optional): Only used for validation. If the value of this parameter doesn't match the user´s currency, the user is notified and then logged out. For a complete list of valid currency codes, see ISO 4217.reference(optional): The reference for identifying a Zettle payment. Used when retrieving payment information at a later time, or when performing a refund. Max length 128.
About tipping
It is not enough to pass enableTipping to the charge(amount:) call for the tipping flow to be displayed. This is because tipping is not supported by all accounts and all card readers. Tipping is only supported with the Zettle card reader. The function is introduced market by market. If the card reader software doesn’t support tipping, users are prompted to skip tipping. Alternatively, users are prompted to update the card reader software.
Total tip amount is presented in iZettleSDKOperationCompletion completion with gratuityAmount property. See Tipping support.
Refunding
The following example describes how to refund an amount from a payment with a given reference.
Objective C
1- (void)refundAmount:(nullable NSDecimalNumber *)amount2ofPaymentWithReference:(NSString *)reference3refundReference:(nullable NSString *)refundReference4presentFromViewController:(UIViewController *)viewController5completion:(iZettleSDKOperationCompletion)completion;
Swift
1open func refund(amount: NSDecimalNumber?,2ofPayment reference: String,3withRefundReference refundReference: String?,4presentFrom viewController: UIViewController,5completion: @escaping iZettleSDK.iZettleSDKOperationCompletion)
amount(optional): The amount to be refunded from the payment. Passingnilwill refund the full amount of the 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 are accounts that automatically revert performed payments. You cannot use these accounts to perform refunds. Instead, please use a standard production Zettle account to test refund functionality.
Retrieving payment info
This example shows how to query Zettle for payment information for a payment with a given reference.
Objective C
1- (void)retrievePaymentInfoForReference:(NSString *)reference2presentFromViewController:(UIViewController *)viewController3completion:(iZettleSDKOperationCompletion)completion
Swift
1open func retrievePaymentInfo(for reference: String,2presentFrom viewController: UIViewController,3completion: @escaping iZettleSDK.iZettleSDKOperationCompletion)
iZettleOperationCompletion
iZettlePaymentInfo
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- Zettles 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 pancardBrandauthorizationCodeAIDTSITVRapplicationNamenumberOfInstallmentsinstallmentAmount
* These fields are only available for some entry modes. Don't rely on them being present.
Example of a card reader chip payment:
1entryMode = EMV2obfuscatedPan = "**** **** **** 0640"3panHash = 0092C7D95900033B84CE08B43F7E973485FB70814cardBrand = MASTERCARD5authorizationCode = 0076026AID = A00000000410107TSI = 40008TVR = 80000000009applicationName = MasterCard
Example of a card reader contactless payment:
1entryMode = CONTACTLESS_EMV2obfuscatedPan = "**** **** **** 0640"3panHash = 0092C7D95900033B84CE08B43F7E973485FB70814cardBrand = MASTERCARD5authorizationCode = 0076026AID = A00000000410107TVR = 80000000008applicationName = MasterCard
Example of a card reader swipe payment:
1entryMode = MAGSTRIPE2obfuscatedPan = "**** **** **** 2481"3panHash = 99426D012C6740D9AEC8E26580E8640A196E3C274cardBrand = MASTERCARD5authorizationCode = 004601
Errors
Zettle will display any errors that occur during an operation to the end-user. The NSError-object returned in the operation completion block is only intended for developers. The object provides more detailed information useful for debugging, diagnostics and logging. You should never present errors returned in this format to the end-user.