Migrating from v1 to v2

The latest iOS SDK has evolved significantly from the previous release SDK v1. This guide describes what is new in v2, what has changed from v1 and what you need to do to migrate to the latest Universal Checkout SDK v2.

Key Highlights

• Universal Checkout now creates payments automatically in a more secure manner
• Some of the earlier payment method options are no longer required, therefore removed or addressed via other calls or functions
• We’ve made major improvements to the SDK’s delegate and settings

For more details about the new features and to see specific code examples, refer to the other sections of this guide.

Automatic Payment Creation

Universal Checkout iOS SDK v2 now creates, resumes and handles payments under the hood 🎉

The automatic payment flow is activated by default.

When migrating to iOS SDK v2, you need to use the following simpler code for payment creation:

12345678910111213141516171819

import PrimerSDK
class MyViewController: UIViewController {    override func viewDidLoad() {        super.viewDidLoad()        // Initialize the SDK with the default settings.        Primer.shared.configure(delegate: self)    }
    func startUniversalCheckout() {        Primer.shared.showUniversalCheckout(clientToken: self.clientToken)    }}
extension MyViewController: PrimerDelegate {    func primerDidCompleteCheckoutWithData(_ data: CheckoutData) {        // Primer checkout completed with data    }}

Earlier, the payment creation code was more complex:

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465

import PrimerSDK
class MyViewController: UIViewController {   override func viewDidLoad() {      super.viewDidLoad()
      // Initialize the SDK with the default settings.      let settings = PrimerSettings(         amount: amount,         currency: currency      )
      Primer.shared.configure(settings: settings)      Primer.shared.delegate = self   }
   func startUniversalCheckout() {      Primer.shared.showUniversalCheckout(on: self)   }}
extension MyViewController: PrimerDelegate {
   func clientTokenCallback(_ completion: @escaping(String ? , Error ? ) - > Void) {      // API call to fetch client token from your backend.      fetchClientToken() {         (token, err) in         completion(token, err)      })}
func onTokenizeSuccess(_ paymentMethodToken: PaymentMethodToken, resumeHandler: ResumeHandlerProtocol) {   // Send the payment method token to your server to create a payment   sendPaymentMethodToken(token: paymentMethodToken) {      (res, err) in      if let err = err {         resumeHandler.handle(error: err)      } else if      let res = res {         guard         let requiredActionDic = res["requiredAction"] as ? [String: Any],            let clientToken = requiredActionDic["clientToken"] as ? String         else {            resumeHandler.handleSuccess()            return         }
         resumeHandler.handle(newClientToken: clientToken)      }   }}
func onResumeSuccess(_ resumeToken: String, resumeHandler: ResumeHandlerProtocol) {   // Resume the payment   sendResumeToken(resumeToken) {      (res, err) in      if let err = err {         resumeHandler.handle(error: err)      } else if      let res = res {         resumeHandler.handleSuccess()      }   }
}

In the earlier versions, you had to manually create and resume payments when receiving  CheckoutEvent.TokenizationSuccess and CheckoutEvent.ResumeSuccess. Not anymore.

We have redesigned and changed this callback and you will no longer have to listen to different events but rather to different callbacks.  But even now, you are no longer required to use onTokenizeSuccess and onResumeSuccess callbacks. This essentially means that you do not need to make any API calls for creating and resuming payments.

Those can be edited out of your integration code.

All this results in an even simpler integration to maintain!

With the new SDK, you can simply listen to the PAYMENT.STATUS webhook and the callback onCheckoutCompleted to process successful and even more secure payments as compared to the earlier versions.

Primer listener changes

We have completely changed how you are receiving events via the PrimerDelegate.

Previously you had to use the delegate functions that were returning different SDK events. We have updated it to a more natural approach and now all events are translated to different callbacks:

*Only relevant on the manual flow. Won’t be called if paymentHandling is AUTO, which is the default value

Client Session Actions Automation

Earlier versions of Primer Checkout SDK required you to integrate using onClientSessionActions.

Now, with the latest SDK v2, as the customer interacts with the UI, Universal Checkout takes care of setting up the "client session actions".

For more details, refer to the Universal Checkout Guide.

Payment Options Updates

The following payment method options in Primer Checkout SDK v1.x.x are no longer available in the latest Universal Checkout SDK v2.

• Order
• OrderItem
• Customer
• Address

Instead, developers must now specify the order and customer details when creating the client session with POST/client-session]

We have completely restructured how you are passing your local settings to SDK. Earlier, you would be passing PrimerSettings and a PrimerTheme object to the SDK with various options:

1

Primer.shared.configure(settings: settings, theme: theme)

Now, you should be passing PrimerSettings and set the delegate, as per the Quick Start Guide. In case you need more customization, you can find the PrimerSettings API reference here.

1

Primer.shared.configure(settings: settings, delegate: self)

Miscellaneous Updates

• PrimerSettings structure has been refactored and PrimerTheme has been integrated within it. Check the PrimerSettings API Reference for details.
• Renamed PaymentMethodToken → PrimerPaymentMethodTokenData
• Renamed ResumeHandler → PrimerResumeDecisionHandler
• showUniversalCheckout and showVaultManager receive different arguments. You can find documentation on them in the SDK API reference.

Resume handler updates

Some delegate functions provide a decision handler, e.g. primerWillCreatePaymentWithData(:decisionHandler:). You can process the data provided and once you’re ready you can call the decision handler with your relevant decision. Once you do, the SDK will continue the flow.

Removed Items

All the deprecated methods in v1 have been removed and replaced with other methods where applicable:

• tokenAddedToVault → Removed
• onClientSessionActions → Removed

All the deprecated classes in v1 have been removed. They are instead set on the backend when creating the client session.

• Order
• OrderItem
• Customer
• Address