Skip to content

Migrating From v2

Overview

The Embedded SDK v3 introduces several improvements and changes compared to v2.

Compared to v2, where the SDK is initialised via the constructor of the Ryft class, in SDK v3, you create instances of the payment components directly using factory functions. This allows for more flexibility and better separation of concerns.

Nevertheless, the new checkout component in SDK v3 still provides a similar all-in-one solution for handling the entire checkout process, including card payments, Google Pay, and Apple Pay. You can choose to use the checkout component for a streamlined integration or create individual components for more customization.

This guide will help you understand the key differences and how to migrate your existing implementation to the new version.

Controller Initialization

In SDK v2, any configuration options (e.g., for the card form, Google Pay, Apple Pay) are passed directly to the Ryft.init() method.

In SDK v3, you create a controller instance using the createController() factory function, and then pass the necessary configuration options when creating individual components or the checkout component.

Here's how you can initialize the controller in SDK v3:

SDK v3 Controller Initialization
// Create a controller instance
const controller = createController({
    publicKey,
    clientSecret,
    // accountId  // Uncomment if using the Platform Fee model
});

You can find more details on controller initialization in the createController page of the documentation.

Card Form Initialization

In SDK v3, you create a controller instance and then use factory functions to create the card form or checkout components.

SDK v2 Card Form Initialization
// Initialize the Ryft SDK
Ryft.init({
    publicKey,
    clientSecret,
    // accountId  // If using the Platform Fee model
});

You can find more details on card form initialization and configuration in the Card Form documentation page.

Field Collection

In SDK v2, there is no separation between the card form and the field collection form.

In SDK v3, the field collection form is a separate component that can be used in conjunction with the card form or other payment method components. This allows for more flexibility in how you collect and manage payment information.

SDK v2 Field Collection
Ryft.init({
    publicKey,
    clientSecret,
    // accountId  // If using the Platform Fee model
    fieldCollection: {
        billingAddress: {
            display: "full"
        },
    }
});

You can find more details on field collection configuration in the Field Collection documentation page.

Wallet Payment Methods

In SDK v3, you can either create individual components for each wallet payment method using their respective factory functions (e.g., createGooglePay(), createApplePay()) or include them in the checkout component configuration.

This provides more flexibility in how you integrate wallet payment methods into your checkout flow, allowing you to choose the approach that best fits your needs.

SDK v2 Wallet Payment Methods
Ryft.init({
    publicKey,
    clientSecret,
    googlePay: {
        merchantName: "Ryft",
        merchantCountryCode: "GB"
    },
    applePay: {
        merchantName: "Ryft",
        merchantCountryCode: "GB"
    },
});

Please note that in SDK v2, a expressCheckout: { enabled: true }, option is required to enable wallet payment methods (see here). In SDK v3, this is no longer necessary, and you can directly create wallet components or include them in the checkout configuration without needing an additional flag.

Required Actions

In SDK v2, required actions (e.g., 3D Secure authentication) that you handle yourself, either because manuallyHandleActions is enabled or because the payment was attempted using the Server-to-Server approach, are completed by calling Ryft.handleRequiredAction().

In SDK v3, the equivalent method lives on the controller: controller.handleRequiredAction(). The manuallyHandleActions flag is passed to createController() in the same way as before.

SDK v2 Required Actions
Ryft.handleRequiredAction(paymentSession)
    .then((updatedPaymentSession) => {
        handlePaymentResult(updatedPaymentSession);
    });

// Server-to-Server
Ryft.handleRequiredAction(requiredAction, publicKey, clientSecret)
    .then((paymentSession) => {
        handlePaymentResult(paymentSession);
    });

The key differences are:

  • Argument: SDK v2 accepts either a whole payment session or a requiredAction object. SDK v3 accepts only the requiredAction object, exactly as returned by the API. When manuallyHandleActions is enabled, attemptPayment resolves with { type: "action-required", requiredAction } and you pass attempt.requiredAction to the method.
  • Credentials: SDK v2 takes positional publicKey, clientSecret and accountId arguments. SDK v3 reads the publicKey and accountId from the controller and takes an optional { clientSecret } options object, which is only needed when the controller was created without a clientSecret or serves more than one Payment Session.
  • Result: SDK v2 resolves with the updated payment session. SDK v3 resolves with { type: "final", paymentSession, userFacingErrorMessage }, the same shape as a payment attempted through a component, so there is no need to call getUserFacingErrorMessage() yourself.

You can find more details, including the full worked examples, in the Handling Required Actions section.