Authentication

note

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

Introduction

Feature in development

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

• loginWithPassword - Used to obtain an access token by providing username and password.

Use the following code to obtain an instance of AuthenticationService:

Kotlin

val authentication = Wallet.getInstance().getAuthenticationService()

Swift

import PaysafeWallet

let authentication = Wallet.instance.authenticationService

Login with password

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

info

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

note

If SCA is required, Wallet.WalletError.scaRequired(authenticationEvent: SCAAuthenticationEventResponse, errorID: String?) / ScaRequiredException(authenticationEvent: ScaAuthenticationEventResponse, errorId: String?) will be thrown. Follow the steps outlined in the section Handle Strong Customer Authentication (SCA) Challenges to confirm the event. After the SCA event is accepted, repeat the request providing the scaDetails parameter.

Parameter	Data type	Description	Example
clientIdentifier	String	Required. The client identifier token.	"C4JTpgmp3:XqIOmHdk"
brandIdentity	String	Required. The identity of the partner using the Embedded Wallet.	"finley"
request	PasswordTokenRequest	Required. An object containing the customer's credentials for authentication.	PasswordTokenRequest(username: "username", password: "password")
scaDetails	ScaAuthenticationEventRequest	SCA authentication properties used to complete the process.	ScaAuthenticationEventRequest(eventId: "7cebe19b-4a96-4d7b-badd-c07eaee786fc", walletOperationID: "03f44a74-937d-430d-b06e-09b42b0f2b0e")

PasswordTokenRequest

Parameter	Data type	Description	Example
username	String	Required. The username that is associated with the user's account.	"johnDoe123"
password	String	Required. The password that is associated with the user's account.	"Pa$$w0rd."

After calling loginWithPassword, you'll receive a Token object containing the access token, which should be used to authenticate the wallet.

Kotlin

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
}

Swift

let passwordTokenRequest = Wallet.PasswordTokenRequest(
    username: "johnDoe123",
    password: "Pa$$w0rd."
)

authentication.loginWithPassword(clientIdentifier: "C4JTpgmp3:XqIOmHdk",
                                 brandIdentity: "finley",
                                 request: passwordTokenRequest,
                                 completion: { loginResult in
    switch loginResult {
    case .success(let authToken):
        Wallet.instance.authenticate(with: .init(accessToken: authToken))
    case .failure(let error):
        if case .scaRequired(let authenticationEvent, _) = error as? Wallet.WalletError {
            // Solve Strong Customer Authentication challenge using authenticationEvent
            // Call loginWithPassword again, providing the scaDetails parameter
        } else {
            // Handle other errors
        }
    }
})

Handle Strong Customer Authentication (SCA) Challenges

Some wallet operations require Strong Customer Authentication and will trigger a process as described in Strong Customer Authentication. Once the eventId and walletOperationId parameters are available, initiate the SCA challenge with the method sendScaChallenge, specifying the preferred SCA method (e.g. One-time password - OTP) and channel (e.g. SMS or EMAIL) from the list of availableVerifications. Use the same method to resend the challenge if the customer does not receive the first one.

When the customer enters the requested SCA code, use the method submitScaAttempt to solve the SCA challenge. Provide the same eventId, walletOperationId, method, and channel. The response from submitScaAttempt is an object of type ScaAuthenticationEventAttemptEmbeddedHybridResponse, containing a status and statusReason fields. The status will be ScaAuthenticationEventAttemptStatus.VERIFIED for successful attempt and ScaAuthenticationEventAttemptStatus.FAILED for invalid value. A DataException/WalletError.dataError will be returned if the customer reaches the maximum number of unsuccessful attempts.

Once the SCA challenge is solved, repeat the requested wallet operation, providing the scaDetails optional parameter. Pass the same eventId and walletOperationId, that was used to solve the challenge.

Kotlin

// Obtain eventId and walletOperationId from the operation that requires SCA
val eventId = "..."
val walletOperationId = "..."

// Instruct the system to send an one-time password (OTP) code via SMS
authenticationService.sendScaChallenge(
    eventId = eventId,
    request = ScaAuthenticationEventChallengeEmbeddedHybridRequest(
        walletOperationId = walletOperationId,
        verification = ScaAuthenticationEventAttemptVerification(
            ScaAuthenticationEventAttemptVerificationMethod.OTP,
            ScaAuthenticationEventAttemptVerificationChannel.SMS
        )
    )
)

// Submit the one-time password entered by the customer
authenticationService.submitScaAttempt(
    eventId = eventId,
    request = ScaAuthenticationEventAttemptEmbeddedHybridRequest(
        walletOperationId = walletOperationId,
        verification = ScaAuthenticationEventAttemptVerification(
            ScaAuthenticationEventAttemptVerificationMethod.OTP,
            ScaAuthenticationEventAttemptVerificationChannel.SMS
        ),
        value = "123456" // Replace with actual OTP value
    )
)

// Retry the wallet operation, providing the scaDetails parameter with the same eventId and walletOperationId

Swift

// Obtain eventId and walletOperationId from the operation that requires SCA
let eventID = "..."
let walletOperationID = "..."

// Instruct the system to send an one-time password (OTP) code via SMS
authenticationService.sendSCAChallenge(
    eventID: eventID,
    request: Wallet.SCAAuthenticationEventChallengeEmbeddedHybridRequest(
        walletOperationID: walletOperationID,
        verification: Wallet.SCAAuthenticationEventAttemptVerification(
            method: .otp,
            channel: .sms
        )
    ),
    completion: { result in
        switch result {
        case .success(let scaEventChallenge):
            // Display information about scaEventChallenge
        case .failure(let error):
            // Handle error
        }
    }
)

// Submit the one-time password entered by the customer
authenticationService.submitSCAAttempt(
    eventID: eventID,
    request: Wallet.SCAAuthenticationEventAttemptEmbeddedHybridRequest(
        walletOperationID: walletOperationID,
        verification: Wallet.SCAAuthenticationEventAttemptVerification(
            method: .otp,
            channel: .sms
        ),
        value: "123456" // Replace with actual OTP value
    ),
    completion: { result in
        switch result {
        case .success(let scaEventAttempt):
            // Handle result of scaEventAttempt
        case .failure(let error):
            // Handle error
        }
    }
)