Skip to main content

Strong Customer Authentication
Feature in development

Introduction

Strong Customer Authentication (SCA) is a requirement of the Payment Services Directive 2 (PSD2) in Europe. It mandates that electronic payments and sensitive wallet operations are performed with multi-factor authentication to increase the security.

SCA is designed to protect customers and reduce the risk of fraud by requiring them to provide two or more forms of identification. This helps to ensure that the user making the payment or sensitive wallet operation is the legitimate wallet owner and not a fraudster.

How SCA Works

Authentication Factors

SCA requires that electronic payments and sensitive wallet operations are performed with multi-factor authentication. This means that the user must provide at least two of the following three factors:

  • Something the user knows (e.g., a password or PIN).
  • Something the user has (e.g., a mobile phone or hardware token).
  • Something the user is (e.g., a fingerprint or facial recognition).

Responsibilities

There are two ways to handle SCA in Embedded Wallet based on the level of responsibility the partner takes:

  • Outsourced SCA - the partner is responsible for handling the SCA process.
  • Embedded SCA - Paysafe is responsible for handling the SCA process.
warning

Paysafe currently supports only Outsourced SCA. For more information on the different SCA methods, see Handling SCA in Embedded Wallet.

Wallet Operations Requiring SCA

The wallet operations listed below necessitate the implementation of Strong Customer Authentication (SCA):

Authentication

Prepaid Cards

Transfers

Withdrawals

Handling SCA in Embedded Wallet

Overview

Outsourced SCA refers to a process in which the responsibility for implementing and managing strong customer authentication is entirely delegated to the partner. The partner handles all aspects of the SCA process, including user authentication and compliance with regulations like PSD2.

Responsibilities

To successfully complete the wallet operation requiring SCA, the partner must perform the following tasks:

  • Initiate the SCA process when requested by Paysafe.
  • Authenticate the user using a secure method (e.g., PIN or OTP).
  • Audit the outcome of the SCA process to Paysafe.
  • Re-request the wallet operation resource, including the relevant SCA details.

How It Works

Users execute wallet operations that necessitate SCA authentication via the partner's front end using Paysafe's SDKs. Moreover, initiating the SCA process involves the partner's backend, which must initiate a business request to validate the authentication event execution.

The sequence of API calls will be as follows:

Strong Customer Authentication Process (Outsourced)Strong Customer Authentication Process (Outsourced)

Single vs. Multi-step Wallet Operations

Overview

The following examples demonstrate the flows for managing SCA for specific wallet operations. The wallet operations are split into two categories, based on the number of steps required:

  • Single-step - authentication and prepaid cards.
  • Multi-step - transfers and withdrawals.

Execute a Wallet Operation

When a customer performs a single-step wallet operation, such as user authentication, internal checks based on the brand, country, and operation details are conducted to determine if SCA is required.

Request

User Authentication
curl --location 'https://api.paysafe.com/digitalwallets/v1/auth/brands/{{brand}}/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic {{client-id:client-secret}}' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
--data-urlencode 'subject_token={{partner-customer-token}}' \
--data-urlencode 'digital_fingerprint=bb229878-c877-4cc3-91c4-2030c34be28a'

The initial wallet operation request does not include SCA-Authorization: {{sca-details}} header. Paysafe will decide if SCA authentication is necessary for the wallet operation by conducting internal checks on the details of the specific operation and adhering to PSD2 requirements.

Response

When the server receives a request for a protected resource that requires SCA, it responds with a 401 Unauthorized status code. It also includes the WWW-Authenticate header in the response to inform the client about the authentication methods that might be used to gain access to the specific resource.

[401 Unauthorized] User Authentication - Error Headers
WWW-Authenticate: SCA realm="Authentication" auth-param1="ewogICJzY2FEZXRhaWxzIjogewogICAgImV2ZW50SWQiOiAiMDZiZGNkMmMtMGNjZS00YjM2LTk3ZWMtMjgxYzhmNWQ3NDNjIiwKICAgICJ3YWxsZXRPcGVyYXRpb25JZCI6ICJhNTg2NWZkNi0xOGMyLTQ1YTgtOTk1My0xYzAwZWFjMzZjMzYiLAogICAgImF2YWlsYWJsZVZlcmlmaWNhdGlvbnMiOiBbCiAgICAgIHsKICAgICAgICAibWV0aG9kIjogIlBJTiIKICAgICAgfSwKICAgICAgewogICAgICAgICJtZXRob2QiOiAiT1RQIiwKICAgICAgICAiY2hhbm5lbCI6ICJTTVMiCiAgICAgIH0KICAgIF0KICB9Cn0="
[401 Unauthorized] User Authentication - Error Body
{
"error": {
"code": "DW-SCA-VERIFICATION-FAILED",
"message": "The wallet operation was unsuccessful.",
"details": [
"The wallet operation was declined because the SCA requirement is not completed."
]
}
}

The WWW-Authenticate header will include the authentication scheme required by the server and any additional information necessary for the client to authenticate. The format is as follows:

WWW-Authenticate: <auth-scheme> realm="<realm>" auth-param1="<auth-param1>"

The key elements of the WWW-Authenticate header are:

  • auth-scheme - defines the method by which clients verify their identities (always SCA).
  • realm - describes the protected area (e.g. Authentication, Withdrawal, Transfer, etc.).
  • auth-param1 - base64-encoded parameter containing comprehensive SCA authentication properties which the partner should use to complete the process. It must include the unique identifiers related to the SCA authentication process, the necessary authentication mode, as well as the available verification methods.

To better understand the base64-encoded blob of data referred to by auth-param1, here's an example of what it contains:

SCA Authentication Properties
{
"scaDetails": {
"eventId": "06bdc2c0-cce-4b36-97ec-281c8f5d743c",
"walletOperationId": "a5865fd6-18c2-45a8-9953-1c00eac36c36",
"authenticationMode": "OUTSOURCED",
"availableVerifications": [
{
"method": "PIN"
},
{
"method": "OTP",
"channel": "SMS"
}
]
}
}

The scaDetails property encompasses the following elements:

  • eventId - the unique identifier of the SCA authentication event.
  • walletOperationId - the unique identifier of the wallet operation, used to associate it with the SCA authentication event.
  • authenticationMode - the mode of the Strong Customer Authentication (SCA) authentication process (OUTSOURCED or EMBEDDED).
  • availableVerifications - the available verification methods for the SCA authentication process. In an outsourced SCA scenario, this property will not appear in the response because the partner manages the entire SCA process according to the agreed-upon methods in the contract.
info

For more information on the SCA authentication properties, refer to SCA Details.

Initiate a SCA Authentication

The authenticationMode property specifies the particular SCA authentication process that is required to authorize the user to complete the wallet operation and indicates who is responsible for managing it. The potential options are:

  • OUTSOURCED - The partner is responsible for managing the SCA process and must verify the customer's identity using a secure method. This can include using a previously established PIN or a one-time password (OTP) sent to the customer's mobile phone or email address. Other verification methods agreed-upon in the contract are also acceptable.
  • EMBEDDED - Paysafe is responsible for managing the SCA process and employs the necessary verification methods (specified by the availableVerifications property) to authenticate the user. The partner does not participate in the execution of the SCA process.

Regardless of the outcome of the SCA authentication process conducted, the partner must report the result to Paysafe via an HTTP request. Paysafe will then perform additional internal security checks related to both successful and unsuccessful SCA attempts to ensure enhanced security and prevent fraud.

info

Initiating the SCA process necessitates the involvement of the partner's backend, which should trigger a B2B request. This ensures that the SCA authentication process cannot be abused by malicious actors.

For more information on performing SCA authentication, see Initiate an Outsourced SCA Authentication Event Attempt.

Request

Outsourced SCA Authentication Confirmation (Business APIs)
curl --location 'https://api.paysafe.com/digitalwallets/v1/customers/1100000001080714/sca/events/06bdcd2c-0cce-4b36-97ec-281c8f5d743c/attempts' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic {{api-key-username:api-key-password}}' \
--data-raw '{
"walletOperationId": "a5865fd6-18c2-45a8-9953-1c00eac36c36",
"verification": {
"method": "OTP",
"channel": "SMS"
}
"status": "VERIFIED"
}'

The SCA authentication confirmation request should contain the eventId and walletOperationId properties to ensure that the authentication attempt is directly associated with the specific customer operation. Paysafe verifies this unique relationship to prevent fraudulent activity. In addition to these properties, the verification must be also included to ensure compliance with the SCA rule requiring at least two factors from different categories. The incorporation of the remaining properties - status, statusReason, and value, may differ based on whether the SCA authentication mode is outsourced or embedded.

Response

If Paysafe successfully accepts and handles the SCA authentication confirmation API request, the response will be as outlined below:

[201 Created] SCA Authentication Confirmed
{
"id": "13121989",
"customerId": "1100000001080714",
"eventId": "06bdcd2c-0cce-4b36-97ec-281c8f5d743c",
"walletOperationId": "a5865fd6-18c2-45a8-9953-1c00eac36c36",
"verification": {
"method": "OTP",
"channel": "SMS"
},
"status": "VERIFIED",
"currentAttempts": 1,
"allowableAttempts": 5,
"creationTime": "2024-01-01T19:14:12.642938Z"
}

Regardless of the status of the SCA authentication attempt, the response will include:

  • id - the unique identifier of the SCA authentication event attempt (each attempt will possess a distinct identifier but will be associated with the same SCA event).
  • customerId - the unique identifier of the customer.
  • eventId - the unique identifier of the SCA authentication event.
  • walletOperationId - the unique identifier of the wallet operation, used to associate it with the SCA authentication event.
  • verification - the verification method and channel used for the SCA authentication attempt.
  • status - the status of the SCA authentication attempt.
  • statusReason - the reason for the status of the unsuccessful SCA authentication attempt.
  • currentAttempts - the number of current SCA authentication attempts.
  • allowableAttempts - the number of allowable SCA authentication attempts, before the invalidating the associated SCA authentication event.
  • creationTime - the date and time when the SCA authentication attempt was created.

Throughout the SCA authentication process, specific exceptions may arise. Detailed information regarding these exceptions is available in the SCA Authentication Errors section.

An example of such an error concerns a non-existing SCA authentication event or an incorrect link to the requested wallet operation:

[404 Not Found] SCA Authentication Event Not Found
{
"error": {
"code": "DW-SCA-EVENT-NOT-FOUND",
"message": "SCA authentication event was not found",
"details": [
"No SCA authentication event matching the provided data was found."
]
}
}

In case the SCA authentication attempts exceed the allowed limit, the following error response will be returned:

[429 Too Many Requests] SCA Authentication Attempts Exceeded
{
"error": {
"code": "DW-SCA-ATTEMPTS-EXCEEDED",
"message": "SCA authentication attempts exceeded",
"details": [
"SCA authentication attempts exceeded the allowed limit."
]
}
}

Finalize the Wallet Operation

After Paysafe accepts and processes the SCA authentication confirmation request, the partner's system should proceed to re-request the same wallet resource, including the relevant details concerning the SCA authentication. These details are required to verify that the user is authorized to complete the requested wallet operation.

Request

User Authentication, SCA Verified
curl --location 'https://api.paysafe.com/digitalwallets/v1/auth/brands/{{brand}}/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic {{client-id:client-secret}}' \
--header 'SCA-Authorization: {{sca-details}}' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
--data-urlencode 'subject_token={{partner-customer-token}}' \
--data-urlencode 'digital_fingerprint=bb229878-c877-4cc3-91c4-2030c34be28a' \

The SCA authorization header name adheres to the convention established by the authentication scheme indicated in the WWW-Authenticate response header. The scheme employed is SCA, and consequently, the corresponding authorization header is denoted as SCA-Authorization.

The specific authorization header must be included in the subsequent request to verify if the required SCA authentication was successfully verified and the user is authorized to complete the requested wallet operation.

If the request lacks this authorization header, or if the provided SCA properties are incorrect or unconfirmed, the outcome will follow the procedure outlined in step 1, necessitating the partner to repeat the process.

The {{sca-details}} value should be a base64-encoded string containing the unique identifiers related to the SCA authentication process, extracted from the auth-param1 value in the WWW-Authenticate response header:

{
"scaDetails": {
"eventId": "06bdc2c0-cce-4b36-97ec-281c8f5d743c",
"walletOperationId": "a5865fd6-18c2-45a8-9953-1c00eac36c36"
}
}

The primary components of the scaDetails property are:

  • eventId - the unique identifier of the SCA authentication event.
  • walletOperationId - the unique identifier of the wallet operation, used to associate it with the SCA authentication event.

For more information on the SCA authentication attributes, refer to SCA Details.

If the SCA authentication is successfully completed and the wallet operation is processed, the response will be as described below:

Response

[200 OK] User Authentication Completed
{
"access_token": "{{customer-token}}",
"expires_in": 900,
"refresh_token": "{{refresh-token}}",
"refresh_expires_in": 1800,
"token_type": "Bearer",
"scope": "whitelabelWallet"
}

Conclusion

The wallet operation is now complete, and the partner can proceed with the next steps. If the SCA authentication process wasn't successful, the partner should repeat the entire process as already outlined.