SCA session
Mangopay’s SCA feature relies on Mangopay-hosted web page where the individual can complete all necessary steps, whether that’s providing credentials or authenticating actions.
To deliver this 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.
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 scenario.
1. Call an endpoint that triggers SCA
Your platform needs to redirect the user for SCA authentication when you take one of the following actions and call the relevant endpoint (see linked guides for details):
| Action | Endpoints |
|---|---|
POST Create a Natural User (SCA) or POST Create a Legal User (SCA) if | |
PUT Categorize a Natural User or PUT Categorize a Legal User | |
PUT Update a Natural User (SCA) if the |
2. Retrieve the SCA RedirectUrl
In the API response from an endpoint triggering SCA, the PendingUserAction object contains a RedirectUrl value. For example:
The URL of the unique SCA session is:
https://sca.mangopay.com?token=0193d02f30df7a188c51cf890a191d21 |
3. Add your returnUrl and redirect the user
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 a query parameter, being sure to percent-encode any non-ASCII characters.
Redirect the user on the new URL string which now comprises Mangopay’s full RedirectUrl response value and your added returnUrl.
For example, if your returnUrl is https://example.com, you need to redirect the user on:
https://sca.mangopay.com?token=0193d02f30df7a188c51cf890a191d21&returnUrl=https%3A%2F%2Fexample.com |
Caution – Add your return URL before redirection
You must add your returnUrl before you redirect the user on the RedirectUrl value, otherwise the hosted web page cannot return them upon completion.
The returnUrl parameter name is case-sensitive.
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. Let the user authenticate
Once on the RedirectUrl, the user can perform the necessary actions for SCA.
For the OTP authentication method, this means requesting and submitting a code via SMS.
Note – Session timeout after 10 minutes
The session of the RedirectUrl is valid for 10 minutes. If the user does not submit a successful SMS OTP before this time, the session can no longer be used and they are returned on your return URL.
If this happens, you need to obtain a new RedirectUrl for them using the endpoint POST Enroll a User in SCA.
5. Retrieve the returnUrl query parameters
Once the user completes authentication (successfully or not) they are redirected to your returnUrl.
On redirection, Mangopay adds two query parameters to your returnUrl: controlStatus and actionStatus.
For example:
https://example.com/?controlStatus=VALIDATED&actionStatus=SUCCEEDED |
6. Check the status of the user and the action
The controlStatus parameter indicates the values of the control:
VALIDATED- The control was successful.FAILED- The control was unsuccessful and cannot be reused.
If the controlStatus is not VALIDATED, call the POST Enroll a User in SCA to obtain a new SCA RedirectUrl and retry the authentication session.
The actionStatus parameter indicates the status of the action being controlled:
SUCCEEDED- The action was successful.FAILED- The action was not determined to be successful by the session or the outcome was otherwise unknown.
If the actionStatus is not SUCCEEDED, call the GET View a User to check the UserStatus of the user. If it is still PENDING_USER_ACTION, then call the POST Enroll a User in SCA to retry the authentication.
Related resources
Was this page helpful?