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 *)amount
2
enableTipping:(BOOL)enableTipping
3
reference:(NSString *)reference
4
presentFromViewController:(UIViewController *)viewController
5
completion:(iZettleOperationCompletion)completion;

Swift

1
open func charge(amount: NSDecimalNumber,
2
currency: String?,
3
enableTipping: Bool,
4
reference: String?,
5
presentFrom viewController: UIViewController,
6
completion: @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 *)amount
2
ofPaymentWithReference:(NSString *)reference
3
refundReference:(nullable NSString *)refundReference
4
presentFromViewController:(UIViewController *)viewController
5
completion:(iZettleSDKOperationCompletion)completion;

Swift

1
open func refund(amount: NSDecimalNumber?,
2
ofPayment reference: String,
3
withRefundReference refundReference: String?,
4
presentFrom viewController: UIViewController,
5
completion: @escaping iZettleSDK.iZettleSDKOperationCompletion)
  • amount (optional): The amount to be refunded from the payment. Passing nil 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.

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 *)reference
2
presentFromViewController:(UIViewController *)viewController
3
completion:(iZettleSDKOperationCompletion)completion

Swift

1
open func retrievePaymentInfo(for reference: String,
2
presentFrom viewController: UIViewController,
3
completion: @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 performed
  • referenceNumber - 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 version
  • obfuscatedPan - e.g. "**** **** **** 1111"
  • panHash - a hash of the pan
  • 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:

1
entryMode = EMV
2
obfuscatedPan = "**** **** **** 0640"
3
panHash = 0092C7D95900033B84CE08B43F7E973485FB7081
4
cardBrand = MASTERCARD
5
authorizationCode = 007602
6
AID = A0000000041010
7
TSI = 4000
8
TVR = 8000000000
9
applicationName = MasterCard

Example of a card reader contactless payment:

1
entryMode = CONTACTLESS_EMV
2
obfuscatedPan = "**** **** **** 0640"
3
panHash = 0092C7D95900033B84CE08B43F7E973485FB7081
4
cardBrand = MASTERCARD
5
authorizationCode = 007602
6
AID = A0000000041010
7
TVR = 8000000000
8
applicationName = MasterCard

Example of a card reader swipe payment:

1
entryMode = MAGSTRIPE
2
obfuscatedPan = "**** **** **** 2481"
3
panHash = 99426D012C6740D9AEC8E26580E8640A196E3C27
4
cardBrand = MASTERCARD
5
authorizationCode = 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.