Search
K

Using the SDK

Learn how to use the SDK package to interact with Wayflyer's Embedded Finance API.

Partner Onboarding

As part of the onboarding process, Wayflyer will securely provide two parameters: a client_id and a client_secret. These credentials must be kept secure and must never be exposed to frontend code under any circumstances. If these values are leaked, contact us immediately.

Headless SDK

Installation

Install the package directly from NPM with npm install @wf-financing/headless-sdk.

To minimize bundle size and reduce the impact on partners' page load times, the SDK uses dynamic imports to load the required components of the SDK on demain.

Instantiation

Initialize the Wayflyer headless SDK using the loadSdk method, passing a companyToken for the current user.

import { type IHeadlessWayflyerSdk, WayflyerHeadlessCtaSdk } from '@wf-financing/headless-sdk';

const wayflyerSdk = (await WayflyerHeadlessCtaSdk.loadSdk('token')) as IHeadlessWayflyerSdk;

⚠️ The companyToken should be minted using the Company Token endpoint on the partner's backend. See the Authentication guide for more details.

SDK Methods

getCta()

Returns the configuration for the CTA to show to the user.

import type { CtaResponseType } from '@wf-financing/headless-sdk';

const cta: CtaResponseType = await wayflyerSdk.getCta();

startHostedApplication(applicationRequest)

Returns a URL to the Wayflyer landing page after the user has given consent for sharing personal data.

import type { StartHostedApplicationRequestType, StartHostedApplicationResponseType } from '@wf-financing/headless-sdk';

const merchantData: StartHostedApplicationRequestType = {
  company_data: {},
  user_data: {},
  partner_data: {},
};

const startHostedApplication: StartHostedApplicationResponseType = await wayflyerSdk.startHostedApplication(merchantData);

continueHostedApplication()

Use this to continue a hosted application when the getCta() method returns a Continue Hosted Application CTA, as described in the "Continuing a hosted application" guide.

import type { ContinueHostedApplicationResponseType } from '@wf-financing/headless-sdk';

const continueHostedApplication: ContinueHostedApplicationResponseType = await wayflyerSdk.continueHostedApplication();

Mocked Mode

To simplify the testing process, the SDK can be initialized in mock mode. To do so, pass a second argument with the value true.

In mocked mode, the SDK will not make any API calls to the Embedded Finance API. It will intercept network calls and return canned responses.

Instantiation

import { WayflyerHeadlessSdk, IHeadlessWayflyerSdk } from '@wf-financing/headless-sdk';

const wayflyerSdk = (await WayflyerHeadlessSdk.loadSdk('token', true)) as IHeadlessWayflyerSdk;

Configuring Canned Responses

Each SDK method has a corresponding method that lets developers configure it to return a specific canned response.

In mock mode, you can manually set responses for SDK methods via additional methods:

  1. setCtaResponse(responseType: CtaResponseTypes)
  2. setStartHostedApplicationResponse(responseType: StartHostedApplicationResponseTypes)
  3. setContinueHostedApplicationResponse(responseType: ContinueHostedApplicationResponseTypes)
  4. setSdkScenario(sdkScenario: SdkScenarios)

setCtaResponse(responseType: CtaResponseTypes)

Sets a mocked response for the getCta() method.

import { CtaResponseTypes } from '@wf-financing/headless-sdk';

wayflyerSdk.setCtaResponse(CtaResponseTypes.GENERIC_OFFER);
wayflyerSdk.setCtaResponse(CtaResponseTypes.INDICATIVE_OFFER);
wayflyerSdk.setCtaResponse(CtaResponseTypes.CONTINUE_HOSTED_APPLICATION);
wayflyerSdk.setCtaResponse(CtaResponseTypes.NO_CTA);
wayflyerSdk.setCtaResponse(CtaResponseTypes.INVALID_TOKEN);

setStartHostedApplicationResponse(responseType: StartHostedApplicationResponseTypes)

Sets a mocked response for the startHostedApplication(applicationRequest: StartHostedApplicationRequestType) method.

import { StartHostedApplicationResponseTypes } from '@wf-financing/headless-sdk';

wayflyerSdk.setStartHostedApplicationResponse(StartHostedApplicationResponseTypes.REDIRECT_URL);
wayflyerSdk.setStartHostedApplicationResponse(StartHostedApplicationResponseTypes.BAD_REQUEST);
wayflyerSdk.setStartHostedApplicationResponse(StartHostedApplicationResponseTypes.INVALID_TOKEN);

setContinueHostedApplicationResponse(responseType: ContinueHostedApplicationResponseTypes)

Sets a mocked response for the continueHostedApplication() method.

import { ContinueHostedApplicationResponseTypes } from '@wf-financing/headless-sdk';

wayflyerSdk.setContinueHostedApplicationResponse(ContinueHostedApplicationResponseTypes.REDIRECT_URL);
wayflyerSdk.setContinueHostedApplicationResponse(ContinueHostedApplicationResponseTypes.BAD_REQUEST);
wayflyerSdk.setContinueHostedApplicationResponse(ContinueHostedApplicationResponseTypes.INVALID_TOKEN);

setSdkScenario(sdkScenario: SdkScenarios)

Provides complex mocked scenarios for complete E2E testing. This ensures that you do not encounter incompatible responses for different methods, such as startHostedApplication(applicationRequest: StartHostedApplicationRequestType) and continueHostedApplication(), which cannot return valid responses at the same time.

import { SdkScenarios } from '@wf-financing/headless-sdk';

wayflyerSdk.setSdkScenario(SdkScenarios.INDICATIVE_NEW_APPLICATION);
wayflyerSdk.setSdkScenario(SdkScenarios.GENERIC_NEW_APPLICATION);
wayflyerSdk.setSdkScenario(SdkScenarios.CONTINUE_APPLICATION);
wayflyerSdk.setSdkScenario(SdkScenarios.NO_CTA);

Note: After calling setSdkScenario(sdkScenario: SdkScenarios), other methods for setting manual responses will no longer have any effect.

UI SDK

Leveraging our UI SDK allows you to directly render Wayflyer's embedded finance user interface within your application, significantly reducing your development and design efforts.

As part of your onboarding, you'll have the opportunity to define the look and feel of the Wayflyer banner and modal that will be displayed in your application's UI. Based on your theming choices, we'll generate a unique theme ID for you. You'll then use this theme ID to seamlessly integrate the customized banner and modal into your user interface, ensuring brand consistency with minimal setup.

Installation

Install the package directly from NPM with npm install @wf-financing/ui-sdk. To minimize the bundle size and reduce the impact on partners' page load times, the SDK uses dynamic imports to load only the required parts of the UI. It also allow Wayflyer to continuously improve the SDK transparently.

Instantiation

To initialize WayflyerUiSdk, call the static method loadSdk with the following parameters:

  1. targetId - The DOM element's ID where the CTA is supposed to be mounted.
  2. partnerDesignId - The ID of the your theme that needs to be applied to the CTA.
  3. partnerCallback - method to retrieve customer application data. The method will be called whenever a user clicks to start an application. The return value should be a StartHostedApplicationRequestType object.
  4. companyToken - The merchant identifier.
  • Note: The companyToken should be minted using the Company Token endpoint on the partner's backend. See the Authentication section here for more details.
import { type IWayflyerUiSdk, WayflyerUiSdk } from '@wf-financing/ui-sdk';

const wayflyerSdk = (await WayflyerUiSdk.loadSdk(targetId, partnerDesignId, partnerCallback, companyToken)) as IWayflyerUiSdk;

SDK methods

mountCta(responseType: CtaResponseTypes)

This function mounts the CTA banner once it's called.

wayflyerSdk.mountCta();

Mocked Mode

To simplify the testing process, the SDK can be initialized in mock mode. To do so, pass a fifth argument of type MockedModeType. In mock mode, the you can manually set responses for SDK methods via the sdkScenario field in the optional mockedMode argument.

In mocked mode, the SDK will not make any API calls to the Embedded Finance API. It will intercept network calls and return instead canned responses.

Instantiation

import { WayflyerUiSdk, type MockedModeType, SdkScenarios } from '@wf-financing/ui-sdk';

const mockedMode: MockedModeType = {
  isMockedMode: true,
  sdkScenario: SdkScenarios.NEW_APPLICATION,
};

const wayflyerSdk = (await WayflyerUiSdk.loadSdk(targetId, partnerDesignId, partnerCallback, companyToken, mockedMode)) as IWayflyerUiSdk;