Migrating from v1 to v2

The latest Android 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 Universal Checkout’s listener

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 Android SDK v2 now creates, resumes and handles payments under the hood 🎉

The automatic payment flow is activated by default.

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

12345678910

private val listener = object : PrimerCheckoutListener {
  override fun onCheckoutCompleted(checkoutData: PrimerCheckoutData) {     // show an order confirmation screen  }}
Primer.instance.configure(listener = listener)
Primer.instance.showUniversalCheckout(context, clientToken)

Earlier, the payment creation code was more complex:

1234567891011121314151617181920212223

private val listener = object: CheckoutEventListener {
   override fun onCheckoutEvent(e: CheckoutEvent) {      when(e) {         is CheckoutEvent.TokenizationSuccess - > {            // Create a payment            // If payment fails: show error message            // If payment succeeds: show a success message            // If payment has a required action: return the new client token         }         is CheckoutEvent.ResumeSuccess - > {            // Resume the payment            // If payment fails: show error message            // If payment succeeds: show a success message            // If payment has a required action: return the new client token         }      }   }}
Primer.instance.configure(listener = listener)
Primer.instance.showUniversalCheckout(context, clientToken)

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/callbacks from Android SDK.

Previously you had to use onCheckoutEvent callback that was receiving different events from the SDK. 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

Moreover, we have renamed CheckoutEventListener → PrimerCheckoutListener

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 "client session actions" via onClientsessionActions().

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
• Customer

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 PrimerConfig object to the SDK with various options:

1

Primer.instance.configure(PrimerConfig(...))

Now, you should be passing PrimerSettings :

1

Primer.instance.configure(PrimerSettings(...))

Miscellaneous Updates

• PrimerSettings structure has been refactored and PrimerTheme has been integrated within it. Check the PrimerSettings API Reference for details.

Resume handler updates

• handler.handleError(error: Error) → handler.handleFailure(message: String?)
• handler.handleNewClientToken(clientToken: String) → handler.continueWithNewClientToken(clientToken: String)

Removed Items

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

Class Primer:

Interface PrimerCheckoutListener:

• onClientSessionActions *→ Removed*
• onTokenAddedToVault → Removed

Class PrimerSettings:

All the deprecated classes in v1 have been removed:

• Order
• Customer

Also, we have removed:

• PrimerConfig
• Business
• Address