Skip to main content

Trusted Entities

Introduction​

Trusted Entities are a key feature of the Embedded Wallets platform, designed to enhance user experience by reducing friction in secure operations. This SDK documentation provides a comprehensive guide on how to manage Trusted Entities, including devices, customers, merchants, and bank accounts. By leveraging the SDK, developers can seamlessly integrate Trusted Entities into their applications, ensuring both security and compliance with regulatory requirements.

Types of Trusted Entities​

  • Trusted Device: A device that has been previously verified and registered by the user, allowing future logins from this device to be treated as lower-risk.
  • Trusted Customer: A recipient (such as a payee) that has been marked as trusted by the user, enabling faster and smoother transfer flows to that recipient without triggering additional authentication steps.
  • Trusted Merchant: A merchant designated as trusted, either by the user or by business rules, reducing the need for repetitive security challenges during transactions with this merchant.
  • Trusted Bank Account: A financial institution that is recognized as trusted within the system, allowing certain operations - such as fund transfers involving this bank - to bypass additional security checks.
  • Trusted Mobile Recipient: A mobile recipient (such as phone contact) that has been marked as trusted by the user, enabling faster and smoother transfer flows to that recipient without triggering additional authentication steps.
  • Trusted Native Mobile App: A mobile application that has been previously verified and registered by the user, allowing future operations from this device to be treated as lower-risk.

Trusted Entities Service:​

The TrustedEntitiesService can be used for managing trusted entities related operations.

Get Trusted Entity Credentials​

Returns a list of AuthTrustedEntityCredential objects that represent the enrolled trusted entities of the provided AuthTrustedEntityCredentialType type for the current user.

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

Wallet.getInstance().getTrustedEntitiesService().getTrustedEntityCredentials(AuthTrustedEntityCredentialType.DEVICE)
  .then(response => console.log('Trusted entities info', response))
  .catch(error => console.error('Error fetching trusted entities info', error));

Create Trusted Entity Credential​

Creates a new trusted entity credential for the current user.

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

const request: AuthTrustedEntityCredentialCreationRequest = {
    entityType: AuthTrustedEntityCredentialType.DEVICE,
    entityKey: 'aca95ef6f10a49108b789b42121f29a2',
    entityDescription: 'My laptop',
    deviceInfo: {
        threatMetrixSessionId: 'a71a475b-1956-4814-9c92-7faa8226b218',
        appType: 'WEB_APP'
    }
};

Wallet.getInstance().getTrustedEntitiesService().createTrustedEntityCredential(request)
  .then(response => console.log('Created trusted entity', response))
  .catch(error => console.error('Error creating trusted entity', error));

Delete Trusted Entity Credential​

Deletes a trusted entity credential for the current user.

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

const request: AuthTrustedEntityCredentialDeletionRequest = {
    id: '824abe75-7f04-4562-be30-8533f5b9f7db',
    deviceInfo: {
        threatMetrixSessionId: 'a71a475b-1956-4814-9c92-7faa8226b218',
        appType: 'WEB_APP'
    }
};

Wallet.getInstance().getTrustedEntitiesService().deleteTrustedEntityCredential(request)
  .then(response => console.log('Deleted trusted entity', response))
  .catch(error => console.error('Error deleting trusted entity', error));

Strong Customer Authentication​

In some regions, all trusted entities operations are subject to Strong Customer Authentication (SCA) requirements. The necessity for SCA Authentication arises when customers need to adhere to the particular regulations outlined in the PSD2 directive. In addition to this requirement, SCA is required to strengthen security and prevent any information disclosure during the credential management process.

Please refer to the Strong Customer Authentication documentation for in-depth details about the flow.

Send SCA Challenge​

If a trusted entities operation gets SCA challenged, the user has to select a method of authentication (e.g. OTP via SMS, etc.).

import { Wallet } from '@paysafe/paysafe-wallet-saas-web/wallet';
import {
  ScaAuthenticationEventAttemptVerificationChannel,
  ScaAuthenticationEventAttemptVerificationMethod,
  ScaAuthenticationEventChallengeEmbeddedHybridRequest
} from "@paysafe/paysafe-wallet-saas-web/common";

/*
...Some code that executes a trusted entities operation that requires SCA
*/

// Obtain eventId and walletOperationId from the operation that requires SCA
const eventId = 'c9fceaf7-2cf8-4092-af70-6ddbe1d4d8c1'
const scaChallengeRequest: ScaAuthenticationEventChallengeEmbeddedHybridRequest = {
    walletOperationId: 'EklfNtWJ8H61aS7rX9VpTfwfcaufAQwAVMu7rtmM97M=',
    verification: {
        method: ScaAuthenticationEventAttemptVerificationMethod.OTP,
        channel: ScaAuthenticationEventAttemptVerificationChannel.SMS
    }
}

Wallet.getInstance().getAuthenticationService().sendScaChallenge(eventId, scaChallengeRequest)
    .then(response => console.log('Send SCA challenge', response))
    .catch(error => console.error('Error sending SCA challenge', error));

Submit SCA Attempt​

To resolve the SCA challenge, the user has to submit the requirements for the selected authentication method.

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

const eventId = 'c9fceaf7-2cf8-4092-af70-6ddbe1d4d8c1'
const scaAttemptRequest: ScaAuthenticationEventAttemptEmbeddedHybridRequest = {
    walletOperationId: 'EklfNtWJ8H61aS7rX9VpTfwfcaufAQwAVMu7rtmM97M=',
    verification: {
        method: ScaAuthenticationEventAttemptVerificationMethod.OTP,
        channel: ScaAuthenticationEventAttemptVerificationChannel.SMS
    },
    value: '123456'
}

Wallet.getInstance().getAuthenticationService().submitScaAttempt(eventId, scaAttemptRequest)
    .then(response => console.log('Submit SCA attempt', response))
    .catch(error => console.error('Error submitting SCA attempt', error));

Retry the trusted entities operation​

After the SCA challenge is resolved, the user can retry the trusted entities operation that was previously challenged.

All trusted entities operations accept an optional scaDetails parameter of type ScaAuthenticationEventRequest, which you need to fill with accordingly.

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

const scaDetails: ScaAuthenticationEventRequest = {
    eventId: 'c9fceaf7-2cf8-4092-af70-6ddbe1d4d8c1',
    walletOperationId: 'EklfNtWJ8H61aS7rX9VpTfwfcaufAQwAVMu7rtmM97M='
};

Wallet.getInstance().getTrustedEntitiesService().getTrustedEntityCredentials(AuthTrustedEntityCredentialType.DEVICE, scaDetails)
  .then(response => console.log('Trusted entities info', response))
  .catch(error => console.error('Error fetching trusted entities info', error));