Migrating from v1 to v2

The latest Web 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

• There is a brand new way to initialize checkout
• Universal Checkout now creates payments automatically in a more secure manner.
• Some of the earlier payment method options and methods are no longer required, therefore removed or addressed via other calls or functions.
• The way to customize merchant branding through styling has changed.

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

Initializing Universal Checkout

In the new Primer Universal Checkout Web SDK, you’ll find that the boilerplate for initializing is reduced to just one line of code!

123

/* v2 */// To initialize Universal Checkoutconst universalCheckout = await Primer.showUniversalCheckout(clientToken, options)

Compare with previous v1 SDK that required you to write more code:

1234

/* v1 */const Primer = await loadPrimer() // If the package is loaded from npmconst primer = new Primer({ credentials: { clientToken } })const checkout = await primer.checkout(options)

Initialize Vault Manager

In the v2 SDK, you can initialize the vault manager using the following function:

123

/* v2 */// to intialize Vault Managerconst vaultManager = await Primer.showVaultManager(clientToken, options)

Other Initialization Changes

The new Universal Checkout initialization makes integration much simpler and easier. As a result, developers are no longer required to construct the Primer object using new Primer() call. Instead, you need to use Primer.showUniversalCheckout() or Primer.showVaultManager().

Another set of changes that you need to take into account is when the package is loaded from npm:

• The loadPrimer() call is now removed from the latest SDK. When the user approaches checkout, if you need to preload Primer Universal Checkout SDK, use preloadPrimer() instead. Under the hood, loadPrimer() is automatically called by Primer.showUniversalCheckout() so you do not need to call loadPrimer() explicitly anymore.
• It is no longer required to import the CSS file anymore. Primer.showUniversalCheckout() will automatically load it.

To find out more about Universal Checkout initialization process, checkout the Web Get Started Guide.

Automatic Payment Creation

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

The automatic payment flow is activated by default.

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

123456

/* v2 */Primer.showUniversalCheckout(token, {    onCheckoutComplete({ payment }) {        // e.g. Show a success message, give access to the service, fulfil the order, ...    },})

Earlier, the payment creation code was more complex:

123456789101112131415

/* v1 */primer.checkout({    onTokenizeSuccess(paymentMethodTokenData) {        // 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    },    onResumeSuccess(resumeTokenData) {        // 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    },})

In the earlier versions, you had to manually create and resume payments using onTokenizeSuccess and onResumeSuccess. Not anymore.

The functions onTokenizeSuccess and onResumeSuccess are no longer required to be used. 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.

No complex integrations to maintain anymore!

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

1234567891011121314

/* v2 */Primer.showUniversalCheckout({    paymentHandling: 'MANUAL',
    onTokenizeSuccess(data, handler) {        // To implement    },
    onResumeSuccess(data, handler) {        // To implement    },
    /* Other options */})

onTokenizeSuccess and onResumeSuccess change

In the earlier version, onTokenizeSuccess and onResumeSuccess had to return specific data to trigger various scenarios. This proved to be quite error-prone and not self-explanatory.

12345678910

/* v2 */async onTokenizeSuccess(paymentMethodTokenData) {  return true; // Handle success
  throw new Error("Error message") // Handle error message
  return { clientToken: "..." } // Continue the flow with a new client token}
// Same for onResumeSuccess

This logic has been greatly improved in v2 by introducing a handler argument that contains the functions to continue.

12345678910111213141516

/* v2 */async onTokenizeSuccess(paymentMethodTokenData, handler) {  return handler.handleSuccess(); // Handle success
  return handler.handleFailure("Error message") // Handle failure with a custom error message
  return handler.continueWithNewClientToken("...") // Continue the flow with a new client token}
async onResumeSuccess(paymentMethodTokenData, handler) {  return handler.handleSuccess(); // Handle success
  return handler.handleFailure("Error message")  // Handle failure with a custom error message
  return handler.continueWithNewClientToken("...") // Continue the flow with a new client token}

Improved 3DS

In the latest SDK, the 3DS feature can be accessed without writing a single line of integration code by simply using workflows. You can be fully SCA-ready with a unified checkout across all your payments services including 3D Secure 2.0.

Once you add a 3DS pre-authorization Primer Connections to your Workflow, the Universal Checkout feature will just do the right thing for you. It will present to your customer a fully in-context Workflow that is optimized with 3D Secure flow on both web or mobile.

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.

Developers must now specify the order and customer details when creating the client session with POST/client-session

Setters Removed

The Setters in Web SDK v1 listed in the table below have been removed. Now this information is retrieved by Universal Checkout through the client session.

Developers need to migrate their integration backend to use the latest Universal Checkout SDK v2 and update order details using the API PATCH/client-session. The token obtained through the client-session API needs to be passed to the SDK with setClientToken(newClientToken) API call.

1234

const universalCheckout = await Primer.showUniversalCheckout(clientToken, options)
// Update client tokenuniversalCheckout.setClientToken('...')

allowedPaymentMethods Removed

In the previous Primer Checkout v1.x.x, the option allowedPaymentMethods was used to filter and display the payment methods as required by a specific merchant integration. This is no longer necessary and has been completely removed in the latest SDK v2.

The recently introduced Checkout section in the Dashboard enables display of merchant specific payment methods, based on the conditions defined by them.

All of this happens without a single line of code as part of merchant integration!

See here for details on how Universal Checkout works.

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

As a side effect of this usage change, the following callbacks have also been removed from the SDK in addition to onClientSessionActions. These callbacks are now replaced by the client session update call.

• onAmountChange
• onAmountChanging
• onAmountChangeError

For more details, refer to the Universal Checkout Guide.

Submit Button Updates

If you have setup a custom submit button in the checkout user interface here is what you need to do in order to migrate from previous Primer Checkout Web SDK:

• Use the function submit() to implement a custom submit button. For details, see Universal Checkout Submit button usage guide.
• The submitButton.visible option is now renamed to submitButton.useBuiltInButton.

Styling Customization Changes

Earlier, the card input fields could be customized as per merchant checkout requirements using card.css.

Now, you can instead use the style option to customize the style 🎨 for the entire Universal Checkout SDK and align with the merchant branding in a more cohesive and unified way!

For more details, refer to the Primer Universal Checkout Web SDK Styling Guide

Miscellaneous Updates

• Card holder name display option

  The option card.cardholderName.visible available in the previous version of Primer Checkout SDK has been removed altogether. You can continue to configure this setting through the Dashboard in the forthcoming release. Stay tuned!

  In the meantime, if you need to show or hide the cardholder name field, please get in touch with us.

• Renamed CheckoutOptions

  The typescript CheckoutOptions is now renamed to UniversalCheckoutOptions.

• Checkout object updates

  The checkout object functions tokenize() and validate() are no longer available in the Universal Checkout SDK v2.

Deprecated Items

• Checkout Components

  Checkout Components are now sunset and no longer supported. The new Universal Checkout SDK does not contain primer.render() function. Make sure you clean that up!