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

Copy
1
- (void)chargeAmount:(NSDecimalNumber *)amount
2
        tippingStyle:(IZSDKTippingStyle)tippingStyle
3
           reference:(NSString *)reference
4
presentFromViewController:(UIViewController *)viewController
5
          completion:(iZettleOperationCompletion)completion;

Swift

Copy
1
open func charge(amount: NSDecimalNumber,
2
  tippingStyle: IZSDKTippingStyle,
3
  reference: String?,
4
  presentFrom viewController: UIViewController,
5
  completion: @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:

1. Make sure that card reader version is up-to-date.

2. Specify tipping style according to your market as follows:

3. Set the tipping style to the charge(amount:) call. Total tipping amount is presented in iZettleSDKOperationCompletion completion with gratuityAmount property.

The following example describes how to add tipping with the percentage tipping style.

Objective-C

Copy
1
NSDecimalNumber *amount = [NSDecimalNumber decimalNumberWithString:@"10"];
2
NSString *reference = [[NSUUID UUID] UUIDString];
3

4
[[iZettleSDK shared] chargeAmount:amount
5
                     tippingStyle:IZSDKTippingStylePercentage
6
                        reference:reference
7
        presentFromViewController:self
8
                       completion:^(iZettleSDKPaymentInfo *paymentInfo, NSError *error) {
9

10
    if (paymentInfo) {
11
      NSLog(@"%@", paymentInfo.gratuityAmount);
12
    }
13
}];

Swift

Copy
1
let amount: NSDecimalNumber = 10
2
let reference: String = UUID().uuidString
3

4
iZettleSDK.shared().charge(
5
  amount: amount,
6
  tippingStyle: .percentage,
7
  reference: reference,
8
  presentFrom: self) {
9
    [weak self] paymentInfo, error in
10

11
    if (paymentInfo) {
12
      print(paymentInfo.gratuityAmount)
13
    }
14
  }

The following example describes how to refund an amount from a payment with a given reference.

Objective-C

Copy
1
- (void)refundAmount:(nullable NSDecimalNumber *)amount
2
ofPaymentWithReference:(NSString *)reference
3
     refundReference:(nullable NSString *)refundReference
4
presentFromViewController:(UIViewController *)viewController
5
          completion:(iZettleSDKOperationCompletion)completion;

Swift

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

This example shows how to query Zettle for payment information for a payment with a given reference.

Objective-C

Copy
1
- (void)retrievePaymentInfoForReference:(NSString *)reference
2
              presentFromViewController:(UIViewController *)viewController
3
                             completion:(iZettleSDKOperationCompletion)completion

Swift

Copy
1
open func retrievePaymentInfo(for reference: String,
2
                                  presentFrom viewController: UIViewController,
3
                                  completion: @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.

1. If developer mode is not enabled, enable it by calling the following function in your integration project:

   Copy
   1
   [[iZettleSDK shared] startWithAuthorizationProvider:authorizationProvider
   2
                                   enableDeveloperMode:true];

   Copy
   1
   iZettleSDK.shared().start(with: authenticationProvider,
   2
                             enableDeveloperMode: true)

2. Launch the payment flow.

3. Check the responses.

   The example shows test case "Successfully paid".

   Copy
   1
   {
   2
       "amount" : 25.0, // amount passed to the flow. if `enableTipping` set to `true`, the gratuity amount `3.0` is added
   3
       "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
   }

4. Launch the refund flow.

5. Check the responses.

   The example shows test case "Successful refund".

   Copy
   1
   {
   2
       "amount" : -11.0, // if no amount passed to refund, then `-11.0` is returned, otherwise - the negative amount passed to the refund flow
   3
       "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 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
• transactionId - 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:

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

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

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

• Developer mode
• Tipping support
• Manage PayPal QRC payments