Manage PayPal QRC payments

The following describes how to manage payment operations using PayPal QRC. If you add PayPal QRC payments for your users in the US, you can provide them options to use either PayPal QRC or Venmo QRC when acquiring payments.

Prerequisites

Initialising the SDK for QRC

To accept PayPal QRC payments with the SDK integration, enable the payment method after initialising the SDK.
1
[[iZettleSDK shared] setEnabledAlternativePaymentMethod:@[@(IZSDKAlternativePaymentMethodPayPalQRC)]];
1
let enabledAPMs = [NSNumber(value: IZSDKAlternativePaymentMethod.payPalQRC.rawValue)]
2
iZettleSDK.shared().setEnabledAlternativePaymentMethods(enabledAPMs)
When using PayPal QRC payments, merchants located in the US can choose to use either PayPal or Venmo when acquiring payments.
To initialise the SDK to use both PayPal and Venmo QRC types, you need to specify an NSNumber for the setEnabledAlternativePaymentMethod function. Passing in "0" enables both PayPal and Venmo QRC, since the Venmo QRC is a subtype of PayPal QRC.

Using PayPal QRC

After the PayPal QRC payment method is enabled, a PayPal QRC screen will be added in the SDK Settings view. The screen is for your users to activate the payment method.
By default, if your integration is used in the UK or Germany, it's not activated for your integration users. Make sure that you remind them to activate PayPal QRC payment in the PayPal QRC screen before they use it.

Charging

The following example describes how to perform a payment with an amount and a reference.
  • amount: The amount to be charged in the logged-in user's currency.
  • reference: Non-nullable payment reference. Used to identify a Zettle payment when retrieving payment information at a later time, or performing a refund. Max length 128.
1
- (void)chargePayPalQRCWithAmount:(NSDecimalNumber *)amount
2
reference:(NSString *)reference
3
appearance:(IZSDKPayPalQRCAppearance)appearance
4
presentedFromViewController:(UIViewController *)viewController
5
completion:(IZSDKPayPalQRCCompletion)completion
1
func chargePayPalQRC(amount: NSDecimalNumber,
2
reference: String,
3
appearance: IZSDKPayPalQRCAppearance,
4
presentFrom viewController: UIViewController,
5
completion: IZSDKPayPalQRCCompletion)

Refunding

Refund an amount from a PayPal QRC payment with a given reference.
1
- (void)refundPayPalQRCAmount:(nullable NSDecimalNumber *)amount
2
ofPaymentWithReference:(NSString *)paymentReference
3
refundReference:(NSString *)refundReference
4
presentFromViewController:(UIViewController *)viewController
5
completion:(IZSDKPayPalQRCCompletion)completion
1
func refundPayPalQRC(amount: NSDecimalNumber?,
2
ofPayment paymentReference: String,
3
withRefundReference refundReference: String,
4
presentFrom viewController: UIViewController,
5
completion: IZSDKPayPalQRCCompletion)
  • amount (optional): The amount to be refunded from the payment (passing nil will refund the full amount of the original payment).
  • paymentReference: The reference of the payment that is to be refunded.
  • refundReference: The reference of the refund. Max length 128.

Retrieving payment info

Query the Zettle SDK for payment information for a PayPal QRC payment with a given reference.
1
- (void)retrievePayPalQRCPaymentInfoForReference:(NSString *)reference
2
presentFromViewController:(UIViewController *)viewController
3
completion:(IZSDKPayPalQRCCompletion)completion
1
func retrievePayPalQRCPaymentInfo(for reference: String,
2
presentFrom viewController: UIViewController,
3
completion: IZSDKPayPalQRCCompletion)

IZSDKPayPalQRCCompletion

The completion callback will be called when an operation is completed, canceled, or failed.

Success payload

Successful completion of the payment will provide IZSDKPayPalQRCPaymentInfo with the following details about the transaction.
NameTypeDescription
amountNSDecimalNumberTotal transaction amount
typeIZSDKPayPalQRCTypeWhich QRC type was used to perform the payment PayPal or Venmo (USA Only)
referenceNumberNSStringZettle's reference to the payment (not to be confused with the reference provided by you during a charge or refund operation)
paypalTransactionIdNSStringTransaction Identifier that should be displayed on receipts
transactionIdNSStringThe ID for the transaction in the Zettle system. The ID is automatically generated by the Zettle system.
The enumeration for the QRC type is in the completion object IZSDKPayPalQRCType. All enumerations must be backed up with the integers in Objective-C. This means the type you get back from the completion handler is not a standard string of "PayPal" or "Venmo". Therefore you need to implement logic that checks the QRC type and displays whether it was "PayPal" or "Venmo".

Testing payment and refund

When integrating with the SDK, you can test your integration in developer mode for PayPal QRC and Venmo QRC 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:
    1
    [[iZettleSDK shared] startWithAuthorizationProvider:authorizationProvider
    2
    enableDeveloperMode:true];
    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 with PayPal".
    1
    {
    2
    "paypalTransactionId" : "5RD45483J23141148",
    3
    "referenceNumber" : "JR2QTMYU5E",
    4
    "amount" : 25.0, // amount passed to the flow
    5
    "type" : IZSDKPayPalQRCTypePayPal,
    6
    "transactionId" : "3702b69c-5b53-11ed-bb53-e32a574ae480"
    7
    }
  4. Launch the refund flow.
  5. Check the responses.
    The example shows test case "Successful PayPal refund".
    1
    {
    2
    "paypalTransactionId" : "6VE826082H938612A",
    3
    "referenceNumber" : "JR2QTMYU5E",
    4
    "amount" : 25.0, // if no amount passed to refund, then `-11.0` is returned, otherwise - the negative amount passed to the refund flow
    5
    "type" : IZSDKPayPalQRCTypePayPal,
    6
    "transactionId" : "c1ee606d-5b54-11ed-8c7e-9873cea95625"
    7
    }

Handling failure

Failure in completing a payment will generate an NSError. The error message describes the failure, and can contain any of the reasons listed in the following.
NameDescription
IZSDKPayPalQRCNetworkErrorNetwork error
IZSDKPayPalQRCLocationFailedUnable to fetch user's location
IZSDKPayPalQRCFeatureNotEnabledPayment method is not available for the user
IZSDKPayPalQRCOnboardingNotCompletedPayment method activation is in progress
IZSDKPayPalQRCSellerDataErrorSomething is wrong with the user's data
IZSDKPayPalQRCPaymentCancelledByMerchantPayment was canceled by the seller
IZSDKPayPalQRCPaymentCancelledByBuyerPayment was canceled by the buyer
IZSDKPayPalQRCPaymentTimeoutPayment session has timed out
IZSDKPayPalQRCNotAuthorizedUser is not authorised for this action
IZSDKPayPalQRCNotFoundNo payment could be found for this reference
IZSDKPayPalQRCRetrievalCancelledPayment info retrieval has been canceled by the seller
IZSDKPayPalQRCRefundAmountTooHighRequested amount couldn't be refunded for the payment
IZSDKPayPalQRCRefundInsufficientFundsThere are not enough funds to perform refund in the seller's account
IZSDKPayPalQRCRefundFailedPayment is not refundable
IZSDKPayPalQRCRefundCancelledPayment refund has been canceled by the seller
IZSDKPayPalQRCInvalidAmountProvided amount is invalid
IZSDKPayPalQRCAmountBelowMinimumProvided amount is below the minimum amount
IZSDKPayPalQRCAmountAboveMaximumProvided amount is above the maximum amount
IZSDKPayPalQRCTechnicalErrorUnexpected technical error