Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mangopay.com/llms.txt

Use this file to discover all available pages before exploring further.

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, their integration, 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).
Note – SCA only triggered for Natural and Soletrader usersSCA is not triggered for Legal users whose LegalPersonType is BUSINESS, PARTNERSHIP, or ORGANIZATION, but the endpoints can still be integrated for them. For more details, see the section about legal user integration.
See Users – SCA triggers in Sandbox for current testing information.
ActionEndpointsCriteria
Register a Owner user for the first timePOST Create a Natural User (SCA) or POST Create a Legal User (SCA)If UserCategory is OWNER
Transition an existing Payer to OwnerPUT Categorize a Natural User or PUT Categorize a Legal UserNone (always returned)
Enroll an existing OwnerPOST Enroll a User in SCANone (always returned)
Re-enroll a UserPUT Update a Natural User (SCA) or PUT Update a Legal User (SCA)If UserCategory is OWNER and any of these are changed:
  • Natural
    • PhoneNumber
    • PhoneNumberCountry
    • Email
  • Legal
    • LegalRepresentative.PhoneNumber
    • LegalRepresentative.PhoneNumberCountry
    • LegalRepresentative.Email

​
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.
For example, in the API response for user endpoints, recipient creation, and transfer initiation:
200 response body
{
  ...
	"PendingUserAction": {
    "RedirectUrl": "https://sca.mangopay.com?token=0193d02f30df7a188c51cf890a191d21"
    },
  ...
}
The URL of the unique SCA session is:
https://sca.mangopay.com?⁠token=0193d02f30df7a188c51cf890a191d21

​
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:
https://sca.mangopay.com?⁠token=0193d02f30df7a188c51cf890a191d21&returnUrl=https%3A%2F%2Fexample.com
Caution – Add your return URL before redirectionYou must add your returnUrl before you redirect the user on the RedirectUrl value. If you don’t, the hosted web page displays an error because it cannot return the user 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. Use your defined branding colors (optional)

By default, the SCA session users your platform’s trading name and logo (if provided). At the point of redirection, you can add two query parameters to your encoded returnUrl to further customize the colors of the SCA session:
  • Add &primary=true to use the PrimaryThemeColour
  • Add &cta=true to use the PrimaryButtonColour
You must set the PrimaryThemeColour and PrimaryButtonColour hex values using the PUT Update a Client endpoint in order for them to be usable (for example, using Postman). Note that you need to wait about an hour for the API colors to appear in the SCA session. Read more about SCA customization options →

​
5. Set the session language (optional)

By default, the SCA session detects the user’s browser language if it is one of those listed in the table below. Regional variants for the same language resolve to the single translation supported by Mangopay: e.g. es-419 (Latin American Spanish) resolves to es, en-US (American English) resolves to en. If the user’s browser is in a language (or variant) not listed below, the session is in English by default. You can override the default localization behavior by manually setting the language of the session using the lang query parameter, with one of the values below. For example, to set the session to Spanish, regardless of the user’s browser language, you can add &lang=es to your URL. If the OTP passcode factor is used, then the wording of the SMS is also localized based on the browser language or your override. Supported lang values:
Languagelang value
Bulgarianbg
Dutchnl
Englishen
Frenchfr
Germande
Greekel
Italianit
Polishpl
Portuguesept
Spanishes
Swedishsv

​
6. Redirect the user to the hosted webpage

The final string to use to redirect the user includes:
  • Mangopay’s full RedirectUrl API response value, including host, path, and the unique token query parameter
  • Your URL-encoded returnUrl value, for example &returnUrl=https%3A%2F%2Fexample.com – mandatory, so the session can return the user upon completion
  • Color customization options: &primary=true and &cta=true – both optional, otherwise defaults used
  • Language override, for example &lang=en – optional, otherwise the user’s browser language, if supported, or else English
Example of the final URL on which to redirect the user, with all elements added:
https://sca.mangopay.com?⁠token=0193d02f30df7a188c51cf890a191d21&returnUrl=https%3A%2F%2Fexample.com&primary=true&cta=true&lang=en

​
7. 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.
Note – Session timeout after 10 minutesThe session of the RedirectUrl is valid for 10 minutes. If the user does not complete the necessary steps during this time, the session can no longer be used and they are returned on your return URL.If this happens, you need to retry the SCA session using the relevant endpoint (see Step 7 below) to obtain a new RedirectUrl.
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.

​
8. Receive the user on return

Once the user completes authentication (successfully or not) they are redirected to your returnUrl to continue their experience on your platform. On redirection, Mangopay adds an indicative query parameter to your returnUrl: controlStatus. For example:
https://example.com/?controlStatus=VALIDATED
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.
Best practice – Rely on webhooksYour integration should asynchronously rely on webhooks for event status changes as far as possible, as described below. The controlStatus query parameter is only indicative of the SCA session, not the enrollment or authentication attempt.
When Mangopay introduced SCA, there was a second query parameter, actionStatus, that was added to the returnUrl on redirection. This was subsequently removed for consistency across all SCA redirection scenarios, and to encourage reliance on webhooks.

​
9. 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.
Status changeWebhook event
SuccessUserStatus changed from PENDING_USER_ACTION to ACTIVEUSER_ACCOUNT_ACTIVATED, SCA_ENROLLMENT_SUCCEEDED
FailureNone, UserStatus stayed as PENDING_USER_ACTIONNone for user account status; SCA_ENROLLMENT_FAILED or SCA_ENROLLMENT_EXPIRED for SCA enrollment
ConfirmGET View a User (SCA)
RetryPOST Enroll a User

Enrollment

Read about enrollment scenarios in the user lifecycle

Endpoints

See the SCA-enabled user endpoints