Manage card payments
The following describes how to work with the iOS SDK payment operations charging, refunding, and fetching payment information.
Note: By default, after you add a card payment method in your integration, it's activated for your integration users.
- The SDK initialisation is completed. See Initialisation.
- Presenting Settings view is completed. See Present Settings view.
The following example describes how to perform a payment with an amount and a reference.
Note: Make sure that you securely store the reference. If the reference is lost, you will not able to do the refund or request payment information.
Objective-C
1- (void)chargeAmount:(NSDecimalNumber *)amount2tippingStyle:(IZSDKTippingStyle)tippingStyle3reference:(NSString *)reference4presentFromViewController:(UIViewController *)viewController5completion:(iZettleOperationCompletion)completion;
Swift
1open func charge(amount: NSDecimalNumber,2tippingStyle: IZSDKTippingStyle,3reference: String?,4presentFrom viewController: UIViewController,5completion: @escaping iZettleSDK.iZettleSDKOperationCompletion)
amount
: The amount to be charged in the logged in users currency.tippingStyle
: The style to be used with tipping. For information about tipping style and adding tipping, see Adding tipping.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.
If your market supports tipping, you can add tipping with charging. See Supported markets for tipping.
Depending on your market, you can add tipping with one or more of the following tipping styles:
- Total amount
- Extra amount
- Percentage
For more information about tipping in the SDK, see Tipping support.
To show the tipping flow when taking payment:
Make sure that card reader version is up-to-date.
Specify tipping style according to your market as follows:
Enum case (Objective-C) | Enum case (Swift) | Description |
---|---|---|
IZSDKTippingStyleNone | IZSDKTippingStyle.none | Disables tipping |
IZSDKTippingStyleMarketDefault | IZSDKTippingStyle.marketDefault | Enables tipping style based on the market |
IZSDKTippingStyleAmount | IZSDKTippingStyle.amount | Enables tipping with total amount or extra amount, depending on the market |
IZSDKTippingStylePercentage | IZSDKTippingStyle.percentage | Enables tipping with percentage |
- Set the tipping style to the
charge(amount:)
call. Total tipping amount is presented iniZettleSDKOperationCompletion
completion withgratuityAmount
property.
The following example describes how to add tipping with the percentage tipping style.
Objective-C
1NSDecimalNumber *amount = [NSDecimalNumber decimalNumberWithString:@"10"];2NSString *reference = [[NSUUID UUID] UUIDString];34[[iZettleSDK shared] chargeAmount:amount5tippingStyle:IZSDKTippingStylePercentage6reference:reference7presentFromViewController:self8completion:^(iZettleSDKPaymentInfo *paymentInfo, NSError *error) {910if (paymentInfo) {11NSLog(@"%@", paymentInfo.gratuityAmount);12}13}];
Swift
1let amount: NSDecimalNumber = 102let reference: String = UUID().uuidString34iZettleSDK.shared().charge(5amount: amount,6tippingStyle: .percentage,7reference: reference,8presentFrom: self) {9[weak self] paymentInfo, error in1011if (paymentInfo) {12print(paymentInfo.gratuityAmount)13}14}
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. Passingnil
will 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.
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)
When integrating with the SDK, you can test your integration for card in developer mode without a Zettle merchant account and real transactions.
If developer mode is not enabled, enable it by calling the following function in your integration project:
1[[iZettleSDK shared] startWithAuthorizationProvider:authorizationProvider2enableDeveloperMode:true];1iZettleSDK.shared().start(with: authenticationProvider,2enableDeveloperMode: true)Launch the payment flow.
Check the responses.
The example shows test case "Successfully paid".
1{2"amount" : 25.0, // amount passed to the flow. if `enableTipping` set to `true`, the gratuity amount `3.0` is added3"gratuityAmount" : 0.0, // if `enableTipping` set to `true`, the returned gratuity amount is `3.0`4"transactionId" : "bdcf72bc-6037-11ed-a055-e2294a8ade3d",5"referenceNumber" : "G5363OXS4K",6"entryMode" : "CONTACTLESS_EMV",7@"authorizationCode" : "123456",8"obfuscatedPan" : "**** **** **** 0119",9"panHash" : "01086BED527FDA321CC8718F44839CD909378B4C",10"cardBrand" : "VISA",11"AID" : "A0000000031010",12"TVR" : "0000000000",13"applicationName" : "Visa Credit"14}Launch the refund flow.
Check the responses.
The example shows test case "Successful refund".
1{2"amount" : -11.0, // if no amount passed to refund, then `-11.0` is returned, otherwise - the negative amount passed to the refund flow3"cardBrand" : "VISA",4"entryMode" : "NONE",5"obfuscatedPan" : "**** **** **** 0119",6"panHash" : "D764334F7EFECCA9E991F06A681B64F4905A9A160DB109561D3DBB547BE17E3E48",7"referenceNumber" : "K5YBAR6HLE",8"transactionId" : "2420db84-6041-11ed-a687-0fe1acbcd38a"9}
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 pantransactionId
- The ID for the transaction in the Zettle system. The ID is automatically generated by the Zettle system.cardBrand
authorizationCode
AID
TSI
TVR
applicationName
numberOfInstallments
installmentAmount
* 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
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.