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.

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 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:

123456789101112131415161718192021222324252627

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:

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253

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.

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:

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

1

Primer.configure(settings);

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.

1

Primer.showUniversalCheckout(clientToken);

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