Skip to main content

Getting Started

Artifact access​

In order to seamlessly integrate with our Web SDK artifact, you are required to configure your package manager client by using the following steps.

Configure .npmrc file​

  1. Open or create a .npmrc file in the root directory of your project.
  2. Add the following line to the .npmrc file:
@paysafe:registry=https://repository.paysafe.com

Save Changes​

Save the changes to the .npmrc file.

Summary​

With the .npmrc file configured, your client will use the specified registry to access the Web SDK from our Artifactory registry.

If you encounter any issues or have "questions regarding artifact access, contact our team.

Installation​

Once you have set up your project to access the artifact, you can install it the SDK and start using it.

npm install @paysafe/paysafe-wallet-saas-web

Dependencies​

The SDK has the following peer dependencies to keep in mind:

  • @paysafe/paysafe-wallet-saas-screening-web

Usage​

First, you need to import the Wallet and get a reference to its instance.

import { Wallet } from '@paysafe/paysafe-wallet-saas-web/wallet';

const wallet = Wallet.getInstance();

Type declaration files are available as well and you can import them from the respective module! In this case you import the Wallet type from the wallet module.

Configure SDK​

In order to use the SDK, you need to configure it, so it can reuse the provided configuration for the lifecycle of your application. This is done by calling the configure method of the Wallet.

import { ApiEnvironment } from '@paysafe/paysafe-wallet-saas-web/wallet';

const sdkConfiguration = {
  apiEnvironment: ApiEnvironment.Production, /* the environment that directs the calls to the appropriate Paysafe Wallet API */
  configToken: 'demoConfigToken'             /* the config token you have received from Paysafe Wallet API */
};

wallet
  .configure(sdkConfiguration)
  .then(configureResult => console.log('Configure result', configureResult));

The values of ApiEnvironment and their respective base urls are:

The configToken is a token that you have received from Paysafe Wallet API in advance. This means that in order to configure the SDK, you must have already sent an HTTP request for fetching the configToken.

Authenticate User​

In order to use the Paysafe Wallet API, you need to authenticate the user for whom the wallet operations from the SDK would apply. This is done by calling the authenticate method of the Wallet.

const authenticationConfiguration = {
  accessToken: this.accessToken /* the user accessToken you have received from Paysafe Wallet API */
};

wallet
  .authenticate(authenticationConfiguration)
  .then(authenticationResult => console.log('Authentication result', authenticationResult));

The accessToken is a token that you have received from Paysafe Wallet API in advance. This means that in order to authenticate a user in the SDK, you must have already sent an HTTP request for fetching the accessToken.

note

Based on the partner configuration, the process for receiving the user accessToken is different.

Only one authentication type is allowed for a given user.

Authenticate User with Token Exchange​

In order to authenticate a user with a token that was generated through the Token Exchange process, the following steps are in place:

  1. Issue Token: The user is authenticated through the Paysafe Wallet API on the partner backend, which returns an accessToken.
  2. Authenticate User: The accessToken is passed to the SDK, which authenticates the user and returns an AuthenticationResult.
/* Async/Await syntax is used for better sequential readability */

/* 1. Issue Token */
const partnerBackendResult = await issueTokenOnPartnerBackend();

/* 2. Authenticate User */
const authenticationResult = await wallet.authenticate({
  accessToken: partnerBackendResult.accessToken
});

Authenticate User with Authorization Code​

In order to authenticate a user with a token that was generated through the Authorization Code process, the following steps are in place:

  1. Retrieve Authentication Details: The AuthenticationDetails are retrieved through the SDK by calling the getAuthenticationDetails method of the AuthenticationService.

    note

    The client-generated state parameter must be preserved by the client for later verification.

  2. Redirect user to Authentication UI: The user is redirected to the Paysafe Authentication UI through the authenticationDetails.authenticationUrl property.

  3. User Authentication: The user authenticates through the Paysafe Authentication UI by submitting their credentials and they are redirected back to the Partner Application with code and state parameters in the URL.

  4. (OPTIONAL) Configure SDK: If the partner application has been reloaded, the SDK must be configured again by calling the configure method of the Wallet.

  5. State Verification: The state parameter is verified by the client to ensure that it matches the one generated in step 1.

  6. Issue Token: The user is authenticated through the Paysafe Wallet API on the partner backend by providing the received code parameter, which results in receiving an accessToken.

  7. Authenticate User: The accessToken is passed to the SDK, which authenticates the user and returns an AuthenticationResult.

import { AuthenticationDetails, AuthenticationDetailsParameters } from '@paysafe/paysafe-wallet-saas-web/authentication';

/* Async/Await syntax is used for better sequential readability */

const wallet = Wallet.getInstance();
const authenticationService = Wallet.getInstance().getAuthenticationService();

/* 1. Retrieve Authentication Details */
const brandIdentity = 'brand-identity'; /* The partner brand identity */
const parameters: AuthenticationDetailsParameters = { ... };
const authenticationDetails: AuthenticationDetails = authenticationService.getAuthenticationDetails(brandIdentity, parameters);

/* 2. Redirect user to Authentication UI */
window.location.href = authenticationDetails.authenticationUrl;

/* 3. User Authentication */
/* Happens in another window */

/* 4. (OPTIONAL) Configure SDK */
/* Configure the SDK if the partner application has been reloaded */

/* 5. State Verification */
const state = 'state'; /* The state parameter received from the redirect URL */
/* Verify that the received state parameter matches the one generated in step 1 */

/* 6. Issue Token */
const code = 'code'; /* The code parameter received from the redirect URL */
const partnerBackendResult = await issueTokenOnPartnerBackend(code);

/* 7. Authenticate User */
const authenticationResult = await wallet.authenticate({
  accessToken: partnerBackendResult.accessToken
});

Wallet Operations​

If the Configure SDK and the Authenticate operations were successful, you can start using the SDK for wallet operations!

Example:

wallet.getProfileService().getProfile()
  .then(customerInfo => console.log('Customer info', customerInfo))
  .catch(error => console.error(error));

Examples for Angular / React​

Examples of integrating the Web SDK with Angular or React applications.

import { Component, OnInit } from '@angular/core';
import { ApiEnvironment, AuthenticationResult, ConfigurationResult, Wallet } from '@paysafe/paysafe-wallet-saas-web/wallet';
import { Account, CustomerInfo } from '@paysafe/paysafe-wallet-saas-web/profile';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent implements OnInit {

  private wallet: Wallet = Wallet.getInstance();
  private customerInfo: CustomerInfo;
  private accounts: Account[];

  ngOnInit(): void {
    this.setupSdk();
  }

  private async setupSdk(): Promise<void> {
    try {
      // Configure the wallet and log the result
      const configurationResult = await this.configureWallet();
      console.log('Configuration result', configurationResult);

      // Authenticate the wallet and log the result
      const authenticationResult = await this.authenticateWallet();
      console.log('Authentication result', authenticationResult);

      // Fetch customerInfo and accounts concurrently using Promise.all
      const [fetchedCustomerInfo, fetchedAccounts] = await Promise.all([this.getCustomerInfo(), this.getAccounts()]);

      // Set state with the fetched data
      this.customerInfo = fetchedCustomerInfo;
      this.accounts = fetchedAccounts;
    } catch (error) {
      // Handle errors during the asynchronous operations
      console.error('Error in setupSdk:', error);
    }
  }

  configureWallet(): Promise<ConfigurationResult> {
    return this.wallet.configure({
      apiEnvironment: ApiEnvironment.Production,
      configToken: 'configToken'
    });
  };

  authenticateWallet(): Promise<AuthenticationResult> {
    return this.wallet.authenticate({
      accessToken: 'accessToken'
    });
  };

  getCustomerInfo(): Promise<CustomerInfo> {
    return this.wallet.getProfileService().getProfile();
  };

  getAccounts(): Promise<Account[]> {
    return this.wallet.getProfileService().getAccounts();
  };
}

Wallet​

The Wallet module is the main module of the SDK. It provides the implementation for the Wallet instance, along with the necessary models.

All SDK features are exposed through the Wallet instance. All services and API operations are accessible through it.

import { Wallet } from '@paysafe/paysafe-wallet-saas-web/wallet';

const wallet = Wallet.getInstance();