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.
  • Hybrid SCA - Paysafe is responsible for handling the SCA process, excluding the communication with the end-user.
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​

  • Update а Prepaid Card
  • Get Prepaid Card Details
  • Handle Prepaid Card Secure Details

Transfers​

  • Transfer Money

Withdrawals​

  • Withdrawal Money

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, submitting 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)Strong Customer Authentication Process (Outsourced)Strong Customer Authentication Process (Outsourced)

Single vs. Multi-step Wallet Operations​

Overview​

Wallet Operations​

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.

SCA Process Structure​

The Strong Customer Authentication (SCA) process is initiated when a wallet operation is performed and remains valid for a predefined period of time. If it expires, the user must reinitiate the process by performing the wallet operation again, if still active (e.g., payments have a predefined expiration period within which they must be completed).

When an SCA process is initiated, a challenge (e.g., OTP via SMS) is sent, which has a 15 minutes validity period. If the challenge expires, a new one must be sent. The number of challenges that can be sent is limited, and exceeding this limit triggers a cooldown period before new challenges can be issued.

Users must submit each challenge for verification (e.g., entering the OTP). The number of allowed attempts is limited, and once this limit is reached, further attempts are blocked. The challenge is then marked as failed, and the user must request a new challenge to retry the process. The challenge status is based on the most recent attempt.

To summarize, the structure is as follows:

Strong Customer Authentication StructureStrong Customer Authentication StructureStrong Customer Authentication StructureStrong Customer Authentication Structure

A single wallet operation may initiate multiple SCA processes, with each process potentially requiring sending multiple challenges. Each challenge can be submitted for verification by the user multiple times. All of these elements are subject to the following limitations:

  • Process: May have a predefined expiration period.
  • Challenge: Must have a maximum number of initiation attempts and a predefined expiration period.
  • Attempt: Must have a maximum number of initiation attempts.

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="ewogICJzY2FEZXRhaWxzIjogewogICAgImV2ZW50SWQiOiAiMDZiZGMyYzAtY2NlLTRiMzYtOTdlYy0yODFjOGY1ZDc0M2MiLAogICAgIndhbGxldE9wZXJhdGlvbklkIjogImE1ODY1ZmQ2LTE4YzItNDVhOC05OTUzLTFjMDBlYWMzNmMzNiIsCiAgICAiYXV0aGVudGljYXRpb25Nb2RlIjogIk9VVFNPVVJDRUQiLAogICAgImF2YWlsYWJsZVZlcmlmaWNhdGlvbnMiOiBbCiAgICAgIHsKICAgICAgICAibWV0aG9kIjogIlBJTiIKICAgICAgfSwKICAgICAgewogICAgICAgICJtZXRob2QiOiAiT1RQIiwKICAgICAgICAiY2hhbm5lbCI6ICJTTVMiLAogICAgICAgICJ0YXJnZXQiOiAiam8qKipAZXhhbXBsZS5jb20iCiAgICAgIH0KICAgIF0sCiAgICAiY3JlYXRpb25UaW1lIjogIjIwMjEtMDctMTVUMTc6NTQ6MTJaIiwKICAgICJleHBpcmF0aW9uVGltZSI6ICIyMDIxLTA3LTE1VDE4OjA5OjEyWiIKICB9Cn0="
[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="ewogICJzY2FEZXRhaWxzIjogewogICAgImV2ZW50SWQiOiAiMDZiZGMyYzAtY2NlLTRiMzYtOTdlYy0yODFjOGY1ZDc0M2MiLAogICAgIndhbGxldE9wZXJhdGlvbklkIjogImE1ODY1ZmQ2LTE4YzItNDVhOC05OTUzLTFjMDBlYWMzNmMzNiIsCiAgICAiYXV0aGVudGljYXRpb25Nb2RlIjogIk9VVFNPVVJDRUQiLAogICAgImF2YWlsYWJsZVZlcmlmaWNhdGlvbnMiOiBbCiAgICAgIHsKICAgICAgICAibWV0aG9kIjogIlBJTiIKICAgICAgfSwKICAgICAgewogICAgICAgICJtZXRob2QiOiAiT1RQIiwKICAgICAgICAiY2hhbm5lbCI6ICJTTVMiLAogICAgICAgICJ0YXJnZXQiOiAiam8qKipAZXhhbXBsZS5jb20iCiAgICAgIH0KICAgIF0sCiAgICAiY3JlYXRpb25UaW1lIjogIjIwMjEtMDctMTVUMTc6NTQ6MTJaIiwKICAgICJleHBpcmF0aW9uVGltZSI6ICIyMDIxLTA3LTE1VDE4OjA5OjEyWiIKICB9Cn0="

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",
        "target": "+359***78"

      }
    ]
    "creationTime": "2021-07-15T17:54:12Z",
    "expirationTime": "2021-07-15T18:09:12Z"
  }
}

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, EMBEDDED or HYBRID).
  • availableVerifications - the available verification methods for the SCA authentication process. In an outsourced SCA scenario, this property will reflect the agreed-upon methods in the contract.
  • creationTime - the date and time when the SCA authentication event was created.
  • expirationTime - the date and time when the SCA authentication event will expire (if applicable).
info

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

Send an SCA Challenge​

The partner is fully responsible for sending the SCA challenge in the Outsourced SCA process, generating it using the agreed-upon verification mechanisms, delivering it securely to the end-user, verifying it, and reporting the outcome to Paysafe.

Send a Webhook Notification​

Webhooks are not available for the Outsourced SCA as the entire process is managed by the partner. Based on the wallet operation's result regarding SCA eligibility, the partner is responsible for executing and managing the process, from generating the SCA challenge (using the agreed-upon verification mechanisms), communicating it to the end-user, verifying it, and reporting the outcome to Paysafe.

Submit the 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.
  • HYBRID - Paysafe oversees the SCA process and uses the required verification methods (outlined by the availableVerifications property) to authenticate the user. The partner is responsible for notifying the end-user about the authentication.

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

Submitting 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:

Request​

Outsourced SCA Authentication Confirmation (Business APIs)
curl --location 'https://api.paysafe.com/digitalwallets/v1/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, embedded or hybrid.

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",
    "eventId": "06bdcd2c-0cce-4b36-97ec-281c8f5d743c",
    "walletOperationId": "a5865fd6-18c2-45a8-9953-1c00eac36c36",
    "authenticationMode": "OUTSOURCED",
    "verification": {
        "method": "OTP",
        "channel": "SMS",
        "target": "+359***78"
    },
    "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).
  • 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, EMBEDDED or HYBRID).
  • verification - the verification mechanism 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. In such case the wallet operation would be failed. A new one must be initiated and the SCA process must be repeated. 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 no SCA challenge was found, the following error response will be returned:

[404 Not Found] SCA Challenge Not Found
{
    "error": {
        "code": "DW-SCA-CHALLENGE-NOT-FOUND",
        "message": "SCA challenge was not found",
        "details": [
            "No SCA challenge matching the provided data was found. Possibly one has never been created or has already been finalized due to expiration or other reason."
        ]
    }
}

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.