SCA session redirection

Mangopay’s SCA feature relies on Mangopay-hosted webpage where the individual can complete all necessary steps for all authentication factors, whether that’s first-time SCA enrollment or authenticating actions.

To deliver this hosted SCA session, Mangopay provides a unique URL in the RedirectUrl response parameter on relevant actions across its API. The RedirectUrl is returned as part of the PendingUserAction response object.

This guide describes how to redirect users for the SCA session. For more details about the factors, how they work, and the experience for users, see the factors guide.

​

Overview of the flow

The following diagram provides an overview of how the Mangopay-hosted SCA session works. See the how-to guide below for step-by-step guidance.

​

How to redirect a user for SCA

This section describes how to handle the SCA redirection when required by an SCA enrollment or authentication scenario.

​

Differences between scenarios

While the redirection mechanism is the same in all cases, there are the following differences:

• The redirect URL is returned in a response header for wallet access, whereas the others are in the response body (Step 2)
• There is no webhook for a failed enrollment outcome, nor for wallet access outcomes (Step 7)

​

1. Call an endpoint that triggers SCA redirection

Your platform needs to redirect the user for an SCA session when your platform calls one of several endpoints to initiate an SCA-triggering action.

The following actions and endpoints trigger SCA redirection (see the linked guides for details).

​

2. Retrieve the SCA redirect URL

The API response contains the redirect URL containing a unique token query parameter. You need to retrieve the full value dynamically, meaning the host and the query, for the next step.

{
  ...
	"PendingUserAction": {
    "RedirectUrl": "https://sca.mangopay.com?token=0193d02f30df7a188c51cf890a191d21"
    },
  ...
}

{
  ...
	"PendingUserAction": {
    "RedirectUrl": "https://sca.mangopay.com?token=0193d02f30df7a188c51cf890a191d21"
    },
  ...
}

WWW-Authenticate: PendingUserAction redirectUrl=https://sca.mangopay.com?token=0193d02f30df7a188c51cf890a191d21 

The URL of the unique SCA session is:

​

3. Encode and add your returnUrl

Define a returnUrl to which the user will be returned after they authenticate on the Mangopay-hosted page, regardless of the outcome.

Append your URL to the RedirectUrl response value as the returnUrl query parameter, being sure to percent-encode any non-ASCII characters.

Continuing the previous example, if your returnUrl is https://example.com, the full URL you will need to redirect the user on is:

Note that the concatenation of Mangopay’s RedirectUrl and your encoded returnUrl must be less than 2,000 characters, which is the limit of most web browsers.

​

4. Redirect the user to the hosted webpage

Redirect the user on the new URL string which now comprises Mangopay’s full RedirectUrl response value (including the unique token) and your added returnUrl.

​

5. Let the user complete the session

Once on the session URL, the user can perform the necessary actions for the SCA session. This includes enrollment or authentication, as well as all required authentication factors.

To test the OTP factor in Sandbox, you can use the PhoneNumber +33611111111 (or 0611111111 and FR) and the passcode 702100 to simulate a successful flow. You can also use a real phone number to receive the SMS OTP.

​

6. Retrieve the returnUrl query parameters

Once the user completes authentication (successfully or not) they are redirected to your returnUrl.

On redirection, Mangopay adds two indicative query parameters to your returnUrl: controlStatus and actionStatus.

For example:

The controlStatus parameter indicates the outcome of the SCA session itself:

• VALIDATED - The SCA session was successful.
• FAILED - The SCA session was unsuccessful and cannot be reused.

The actionStatus parameter indicates the status of the action being controlled by the session (e.g. Recipient registration, transfer request):

• SUCCEEDED - The action was successful.
• FAILED - The action was not determined to be successful by the session or the outcome was otherwise unknown.

​

7. Confirm the session outcome and retry if required

The query parameters appended to the returnUrl are indicative.

You should listen for the webhooks events listed below, and confirm the outcome of the action that triggered the SCA session by calling the relevant endpoint of the Mangopay API.

​

Related resources