Migrating from v1 to v2

The latest React Native (RN) 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 RN 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 deprecated.

Key Highlights

For more details about the new features and to see specific code examples, refer to the the sections below.

Automatic Payment Creation

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

The automatic payment flow is activated by default.

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

import {    Primer,    PrimerSettings,    PrimerCheckoutData} from '@primer-io/react-native';
const CheckoutScreen = async (props: any) => {
    const onCheckoutComplete = (checkoutData: PrimerCheckoutData) => {        // Show a success screen    };
    const onUniversalCheckoutButtonTapped = async () => {        const settings: PrimerSettings = {            onCheckoutComplete: onCheckoutComplete        };
        // Configure the SDK        await Primer.configure(settings);
        // Ask your backend to create a client session        const clientToken = await createClientSession(clientSessionRequestParams);
        // Present Universal Checkout        await Primer.showUniversalCheckout(clientToken);    };}

Earlier, the payment creation code was more complex:

import {   Primer} from '@primer-io/react-native';
const CheckoutScreen = (props: any) => {
   const onTokenizeSuccess = (req, res) =>      createPayment({         paymentMethod: req.token      })      .then((payment) => {         // handle required actions if present.         if (payment.requiredAction?.name) {            // ensure the result id is stored somewhere.            setPaymentId(result.id);            // resume the SDK with the result clientToken.            res.handleNewClientToken(result.requiredAction?.clientToken);         } else {            // resume the SDK passing a null object.            res.handleSuccess();         }      })      .catch((_) => res.resumeWithError(errorMessage));
   const onResumeSuccess = (req, res) =>      resumeSession({         id: paymentId,         resumeToken: req      })      .then((payment) => {         if (payment.status in ['FAILED', 'DECLINED', 'CANCELLED', 'PENDING']) {            res.handleError(errorMessage);         } else {            res.handleSuccess();         }      })      .catch((_) => res.handleError(errorMessage));
   const onUniversalCheckoutButtonTapped = async () => {      try {         const clientToken = await createClientSession(clientSessionRequestParams);
         // Present Universal Checkout         Primer.showUniversalCheckout(clientToken, {            onTokenizeSuccess,            onResumeSuccess         });
      } catch (err) {         // Handle error      }   }}

In the earlier versions, you had to manually create and resume payments when the delegate functions onTokenizeSuccess and onResumeSuccess were called. 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 callback will be called.

SDK Flow

Primer listener changes

We have completely changed how you are receiving events, now you can add your callbacks in the SDK’s settings when you configure the SDK.

Previously you had to separately add callbacks in the showUniversalCheckout function.

We have updated it to a more natural approach and now all events are translated to different callbacks:

Earlier v1.x.xLatest v2 SDK
onTokenizeSuccessonTokenizeSuccess *
onResumeSuccessonResumeSuccess *

*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".


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

  • onClientSessionUpdate
  • onBeforeClientSessionUpdate

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 React Native 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
  • 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 a PrimerConfig object -that contained the SDK settings and callbacks- to the SDK in the showUniversalCheckout function.


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


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.

Removed Items

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

  • onVaultSuccess → 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