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.


The latest version v2 of Universal Checkout Android SDK introduces a few breaking changes.


Universal Checkout v2 SDK is super efficient and simpler to integrate. Going forward, the prior Primer Checkout SDK v1.x.x will be no longer supported.

Key Highlights

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:

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:

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

Android SDK Flow

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:

Earlier v1.x.xLatest v2 SDK
CheckoutEvent.TokenizationSuccessonTokenizeSuccess *
CheckoutEvent.ResumeSuccessonResumeSuccess *

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

Moreover, we have renamed CheckoutEventListenerPrimerCheckoutListener

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().


Developers are no longer required to call this function anymore and it has been removed from the SDK. Instead, now you can set up the following callbacks:

  • onClientSessionUpdated
  • onBeforeClientSessionUpdated

Earlier release of SDK had Primer Checkout functionality that was sending you Client session actions in order to enable you to update the client session according to the merchant checkout requirements. This is now completely managed automatically by the Primer Universal Android SDK v2.

The latest SDK can now collect various customer data such as the billing addresscustomer contact details and update the client session by itself. It no longer requires any explicit developer initiated actions or function calls to update these details while integrating with Primer.

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:


Now, you should be passing PrimerSettings :


Miscellaneous Updates

  • PrimerSettings structure has been refactored and PrimerTheme has been integrated within it. Check the PrimerSettings API Reference for details.
Earlier v1.x.xLatest v2 SDK

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:

Earlier v1.x.xLatest v2 SDK

Interface PrimerCheckoutListener:

  • onClientSessionActions *Removed*
  • onTokenAddedToVaultRemoved

Class PrimerSettings:

All the deprecated classes in v1 have been removed:

  • Order
  • Customer

Also, we have removed:

  • PrimerConfig
  • Business
  • Address