Skip to main content

Standalone authentication

note

This API is available only to merchants with standaloneWallet access and walletSetup scope to the config token.

Introduction​

The Authentication service is responsible for issuing and managing access tokens.

Key Features:​

  • Provides a way to authenticate users through the login process with password, PIN, or biometric data.
  • Manages biometric credentials for secure authentication.
  • Refreshes access tokens using refresh tokens.
  • Performs device screening for security purposes.

Prerequisites​

Before integrating the Standalone Authentication service, ensure you have:

  • A valid Paysafe account with appropriate permissions.
  • Set up instructions for Paysafe SDK Android or iOS.

To get started, initialize the StandaloneAuthenticationService instance in your app as shown below:

import com.paysafe.wallet.android.core.wallet.Wallet

val authenticationService = Wallet.getInstance().getStandaloneAuthenticationService()

Login Workflow Overview​

Login workflow diagramLogin workflow diagramLogin workflow diagramLogin workflow diagram

Login steps​

info

These operations might require Strong Customer Authentication (SCA). Please read Strong Customer Authentication for more information on the process.

Step 1.​

Use loginWithPassword or loginWithPin to obtain an access token and then pass it to the authenticate method of the wallet. They requires two specific parameters clientIdentifier and brandIdentity, both of which are provided by Paysafe.

Step 2.​

If SCA is required, Wallet.WalletError.scaRequired / ScaRequiredException will be thrown. Follow the steps outlined in the section Handle Strong Customer Authentication (SCA) Challenges to confirm the event.

Step 3.​

After the SCA event is accepted, repeat the request providing the scaDetails parameter.

Login with PIN
try {

    // Login
    val token = authentication.loginWithPin(
        clientIdentifier = "C4JTpgmp3:XqIOmHdk",
        brandIdentity = "finley",
        request = PinTokenRequest(
            username = "johnDoe123@example.com",
            pin = "111222"
        )
    )

    // Authenticate the wallet sdk
    Wallet.getInstance().authenticate(AuthenticationConfiguration(token.accessToken))

    // Your are done. Start using the wallet services
} catch (e: DataException) {
    // Handle invalid credentials error
} catch (e: ScaRequiredException) {
    // Solve Strong Customer Authentication challenge using e.authenticationEvent
    // Call loginWithPin again, providing the scaDetails parameter
}
Login with password

A PasswordTokenRequest object.

try {

    // Login
    val token = authentication.loginWithPassword(
        clientIdentifier = "C4JTpgmp3:XqIOmHdk",
        brandIdentity = "finley",
        request = PasswordTokenRequest(
            username = "johnDoe123@example.com",
            password = "PaS#w0rd."
        )
    )

    // Authenticate the wallet sdk
    Wallet.getInstance().authenticate(AuthenticationConfiguration(token.accessToken))

    // Your are done. Start using the wallet services
} catch (e: DataException) {
    // Handle invalid credentials error
} catch (e: ScaRequiredException) {
    // Solve Strong Customer Authentication challenge using e.authenticationEvent
    // Call loginWithPassword again, providing the scaDetails parameter
}
Login with biometric
try {

    // Login
    val token = authentication.loginWithBiometric(
        clientIdentifier = "C4JTpgmp3:XqIOmHdk",
        brandIdentity = "finley",
        request = BiometricTokenRequest(
            username = "johnDoe123@example.com",
            biometricData = "biometric_data_string"
        )
    )

    // Authenticate the wallet sdk
    Wallet.getInstance().authenticate(AuthenticationConfiguration(token.accessToken))

    // Your are done. Start using the wallet services
} catch (e: DataException) {
    // Handle invalid credentials error
} catch (e: ScaRequiredException) {
    // Solve Strong Customer Authentication challenge using e.authenticationEvent
    // Call loginWithBiometric again, providing the scaDetails parameter
}

Biometric Credential Management​

The StandaloneAuthenticationService provides methods to manage biometric credentials for secure authentication.

Get biometric credential status​

Check the status of biometric credentials for the current device:

try {
    val status = authentication.getBiometricCredentialStatus()
    // Handle status: AVAILABLE, UNAVAILABLE, or ENROLLED
} catch (e: Exception) {
    // Handle error
}

Create biometric credential​

Generate a new biometric credential for the current device:

try {
    val credential = authentication.createBiometricCredential()
    // Handle credential.value for future authentication
} catch (e: ScaRequiredException) {
    // Solve Strong Customer Authentication challenge using e.authenticationEvent
    // Call createBiometricCredential again, providing the scaDetails parameter
} catch (e: Exception) {
    // Handle other errors
}

Delete biometric credential​

Remove an existing biometric credential from the current device:

try {
    val response = authentication.deleteBiometricCredential()
    // Handle response.isSuccess
} catch (e: ScaRequiredException) {
    // Solve Strong Customer Authentication challenge using e.authenticationEvent
    // Call deleteBiometricCredential again, providing the scaDetails parameter
} catch (e: Exception) {
    // Handle other errors
}

Token Management​

Refresh access token​

Obtain a new access token using a refresh token from previous authentication:

try {
    val newToken = authentication.refreshToken(
        clientIdentifier = "C4JTpgmp3:XqIOmHdk",
        brandIdentity = "finley",
        request = RefreshTokenRequest(
            refreshToken = "your_refresh_token_here"
        )
    )

    // Authenticate the wallet sdk with the new token
    Wallet.getInstance().authenticate(AuthenticationConfiguration(newToken.accessToken))

    // Continue using the wallet services
} catch (e: Exception) {
    // Handle error - may need to re-authenticate with credentials
}

Device Screening​

Get device screening​

Perform device screening to generate a unique digital fingerprint:

try {
    val screeningResult = authentication.getDeviceScreening(forceRefresh = false)
    // Handle screeningResult.digitalFingerprint
} catch (e: Exception) {
    // Handle error
}