Read about how SCA impacts user endpoints
UserCategory
of OWNER
, because these users accept and are bound by Mangopay’s T&Cs and are being provided with Mangopay payment and/or e-money services.
To facilitate SCA enrollment in the User objects, Mangopay has released new endpoints. These endpoints create the same kind of resource as the legacy ones, but they return a PendingUserAction.RedirectUrl
and apply a new UserStatus
value.
Your platform needs to use the RedirectUrl
to redirect the individual to Mangopay’s hosted-webpage so they can enroll. See SCA session for more details on how to do this.
Email
is already required for Natural users. To simplify adoption, your users can provide their phone number during the SCA session – you don’t have to send it via the API.
LegalRepresentative.Email
property, but the phone number can be entered by the individual during the SCA session.
For the other Legal user types (Business, Partnership, Organization), Mangopay is developing functionality to designate additional authorized individuals who can complete SCA on behalf of the entity.
Until then, if LegalPersonType
is BUSINESS
, PARTNERSHIP
or ORGANIZATION
, then the SCA-enabled user endpoints do not return the SCA redirection link.
LegalPersonType
is BUSINESS
, PARTNERSHIP
or ORGANIZATION
.The legacy user endpoints will be deprecated in 2026.PendingUserAction.RedirectUrl
during your integration, set the LegalPersonType
to SOLETRADER
to get the RedirectUrl
in the response.
SOLETRADER
users (see note on legal users), SCA redirection will be triggered in the following scenarios:
PAYER
users, when you change their category to OWNER
using PUT Categorize a Natural User or PUT Categorize a Legal UserOWNER
users, when you:
OWNER
LegalRepresentative.Email
address is required for SCA to build a behavioral biometrics profile and as a backup communication channel.Prior to SCA, it was possible to create a Legal OWNER
without the LegalRepresentativeEmail
, so this data may be missing. Calling the POST Enroll a User in SCA endpoint without this data will return an error.PAYER
, or closing the account.
Mangopay’s objective is to protect your users when they benefit from our services, via an authentication solution that is easy for your platform to adopt in its integration. We remain committed to maintaining the highest standards of security and compliance.
Mangopay will also be shortly providing an endpoint that allows you to close inactive user accounts.
PAYER
to an OWNER
. Read how →PAYER
users too, regardless of whether they are likely to be come OWNER
.For existing users (Natural and Legal Soletrader):OWNER
users at an appropriate moment in your user journey using the dedicated endpoint. Read how →UserStatus
response parameter.
For users created prior to or without SCA, UserStatus
has two possible values, which were the same for PAYER
and OWNER
.
UserStatus value | Without SCA and for all PAYER |
---|---|
ACTIVE (default) | The user is active and can access Mangopay features. |
CLOSED | The user is permanently deactivated (Mangopay use only). |
OWNER
category with SCA, the property can have a new value, PENDING_USER_ACTION
, which is assigned by default. Once the user has completed SCA, their status changes to ACTIVE
.
UserStatus value | OWNER with SCA |
---|---|
PENDING_USER_ACTION (default) | The user must successfully enroll in SCA before for their account to become ACTIVE . |
ACTIVE | The user account is active and can access Mangopay features, such as wallets and KYC/B verification.Note that ACTIVE does not mean that the user is SCA-enrolled. This is because pre-SCA existing users have the ACTIVE value, and it is possible to change the UserCategory on the legacy endpoint (see caution below). |
CLOSED | The user is permanently deactivated (Mangopay use only). |
PENDING_USER_ACTION
status value prevents the user from accessing Mangopay services until they enroll in SCA.
The user’s UserStatus
becomes PENDING_USER_ACTION
after the following events:
OWNER
:
OWNER
using the SCA-enabled endpoints:
Email
(LegalRepresentative.Email
) or PhoneNumber
(LegalRepresentative.PhoneNumber
) via the SCA-enabled PUT endpoints:
USER_ACCOUNT_VALIDATION_ASKED
to be notified when the user’s UserStatus
changes to PENDING_USER_ACTION
.
The USER_ACCOUNT_ACTIVATED
event type sends a notification when the UserStatus
changes from PENDING_USER_ACTION
to ACTIVE
.
PENDING_USER_ACTION
(it stays as ACTIVE
), and no USER_ACCOUNT_VALIDATION_ASKED
webhook notification is sent.This ensures that legacy users do not become blocked if they are unable to complete SCA successfully.PENDING_USER_ACTION
value for UserStatus
and the webhook USER_ACCOUNT_VALIDATION_ASKED
are not triggered if the user is a Legal Business, Partnership, or Organization, as SCA is not yet available for these user types.
PENDING_USER_ACTION
status is only returned on the SCA-enabled endpoints, but it is possible to change the UserCategory
using the legacy PUT Update a Natural/Legal User.If you do this (for example, in the Mangopay Dashboard), then you need to use the POST Enroll a User endpoint to enroll them as an existing OWNER
.UserStatus
is PENDING_USER_ACTION
, they are unable to access Mangopay features. For example, a call to POST Create a Wallet for this user returns an error:
PENDING_USER_ACTION
status, then you can use POST Enroll a User in SCA to retrieve a new SCA session for them to enroll.
ACTIVE
as their UserStatus
, will not be restricted or transitioned to PENDING_USER_ACTION
if you attempt to enroll them using POST Enroll a User and the SCA session is not successful. This means that currently there is no way to distinguish an SCA-enrolled user from one that is not – both have UserStatus
of ACTIVE
.On Recipients, Transfers, and Account Access they will also not be restricted (their status remains ACTIVE
), but the relevant action will not succeed. In this case, you need to retry the Recipient creation or Transfer to allow the user to complete SCA successfully.In future, Mangopay may be required by regulators to start introducing consequences on users if they haven’t enrolled in SCA, but this will be done with sufficient notice to platforms. These consequences may include removing certain permissions, blocking the account, reverting the category to Payer, or closing the account.RessourceId
of the notification received is the UserId
.
USER_ACCOUNT_VALIDATION_ASKED
– The Owner user has triggered SCA enrollment, meaning that their UserStatus
has changed to PENDING_USER_ACTION
.USER_ACCOUNT_ACTIVATED
– The Owner user has been successfully enrolled in SCA and their UserStatus
has changed from PENDING_USER_ACTION
to ACTIVE
.PendingUserAction.RedirectUrl
redirection link. And in each case, the way you need to redirect the user and handle the outcome is the same. For more detailed guidance on this redirection process, SCA session.
UserCategory
is OWNER
UserCategory
is PAYER
LegalPersonType
is BUSINESS
, PARTNERSHIP
, or ORGANIZATION
PendingUserAction.RedirectUrl
regardless of the user typePhoneNumber
, PhoneNumberCountry
, or Email
are changedPhoneNumber
+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.
ClientId
and API key.
Call the Mangopay API to provide user data and trigger SCA
UserCategory
to OWNER
TermsAndConditionsAccepted
to true
(ensuring you have obtained the user’s acceptance of Mangopay’s T&Cs)See required data for Natural Owners
FirstName
LastName
Email
Birthday
Nationality
CountryOfResidence
PhoneNumber
, it will be pre-populated in the hosted SCA experience for them to confirm or change; otherwise, they will be asked to provide it.UserCategory
is OWNER
UserStatus
is PENDING_USER_ACTION
PendingUserAction.RedirectUrl
contains the unique URL for the user’s SCA sessionPENDING_USER_ACTION
status triggers a webhook notification for the USER_ACCOUNT_VALIDATION_ASKED
event type – set up this Hook to be notified.Redirect the user to the SCA session
RedirectUrl
value as the returnUrl
query parameter (for details see How to redirect a user for an SCA session (Step 2 onwards)). Then, redirect the user.Confirm success or retry the session
returnUrl
, check the controlStatus
query parameter attached by Mangopay (as described in Step 5 and 6).The Owner user is successfully SCA enrolled and their account created when the UserStatus
changes from PENDING_USER_ACTION
to ACTIVE
.Set up a webhook notification for the USER_ACCOUNT_ACTIVATED
event type to be notified of this.Call the Mangopay API to provide user data and trigger SCA
UserCategory
to OWNER
TermsAndConditionsAccepted
to true
(ensuring you have obtained the user’s acceptance of Mangopay’s T&Cs)See required data for Natural Owners
FirstName
LastName
Email
Birthday
Nationality
CountryOfResidence
PhoneNumber
, it will be pre-populated in the hosted SCA experience for them to confirm or change; otherwise, they will be asked to provide it.UserCategory
is OWNER
UserStatus
is PENDING_USER_ACTION
PendingUserAction.RedirectUrl
contains the unique URL for the user’s SCA sessionPENDING_USER_ACTION
status triggers a webhook notification for the USER_ACCOUNT_VALIDATION_ASKED
event type – set up this Hook to be notified.Redirect the user to the SCA session
RedirectUrl
value as the returnUrl
query parameter (for details see How to redirect a user for an SCA session (Step 2 onwards)). Then, redirect the user.Confirm success or retry the session
returnUrl
, check the controlStatus
query parameter attached by Mangopay (as described in Step 5 and 6).The Owner user is successfully SCA enrolled and their account created when the UserStatus
changes from PENDING_USER_ACTION
to ACTIVE
.Set up a webhook notification for the USER_ACCOUNT_ACTIVATED
event type to be notified of this.Call the Mangopay API to trigger SCA
PhoneNumber
(Natural Users) or LegalRepresentative.PhoneNumber
(Legal Users) is already present in the user object, it will be pre-populated in the hosted SCA experience for them to confirm or change; otherwise, they will be asked to provide it.On the enrollment endpoint, the API returns only the PendingUserAction.RedirectUrl
property containing the unique URL for the user’s SCA session.The user’s UserStatus
still changes to PENDING_USER_ACTION
, which triggers the a USER_ACCOUNT_VALIDATION_ASKED
webhook.Redirect the user to the SCA session
RedirectUrl
value as the returnUrl
query parameter (for details see How to redirect a user for an SCA session (Step 2 onwards)). Then, redirect the user.Confirm success or retry the session
returnUrl
, check the controlStatus
query parameter attached by Mangopay (as described in Step 5 and 6).The Owner user is successfully SCA enrolled and their account created when the UserStatus
changes from PENDING_USER_ACTION
to ACTIVE
.Set up a webhook notification for the USER_ACCOUNT_ACTIVATED
event type to be notified of this.PhoneNumber
, PhoneNumberCountry
, or Email
user properties are modified.
Call the Mangopay API, triggering SCA
UserCategory
to OWNER
TermsAndConditionsAccepted
to true
PhoneNumber
and/or PhoneNumberCountry
, then the SCA session pre-populates the phone number value for the user to confirm and enroll.If you modify only the Email
, then the new email is confirmed using the PhoneNumber
which was previously enrolled. In this case, the user is not given the opportunity to modify their phone number during the session.UserCategory
is OWNER
UserStatus
is PENDING_USER_ACTION
PendingUserAction.RedirectUrl
contains the unique URL for the user’s SCA sessionPENDING_USER_ACTION
status triggers a webhook notification for the USER_ACCOUNT_VALIDATION_ASKED
event type – set up this Hook to be notified.PhoneNumber
is already present and the user changes it during the SCA session.Any PUT call that changes the PhoneNumber
value triggers SCA, even if the user just completed SCA.Redirect the user to the SCA session
RedirectUrl
value as the returnUrl
query parameter (for details see How to redirect a user for an SCA session (Step 2 onwards)). Then, redirect the user.Confirm success or retry the session
returnUrl
, check the controlStatus
query parameter attached by Mangopay (as described in Step 5 and 6).The Owner user is successfully SCA enrolled and their account created when the UserStatus
changes from PENDING_USER_ACTION
to ACTIVE
.Set up a webhook notification for the USER_ACCOUNT_ACTIVATED
event type to be notified of this.PAYER
users.
However, the SCA endpoints must be integrated to register and update PAYER
users:
UserCategory
is PAYER
UserStatus
is ACTIVE
PendingUserAction
is null
PendingUserAction
(which is always null
on the GET endpoint).
For Legal users, the new GET View a User (SCA) endpoint returns the same data as the legacy one but in the new format: with the LegalRepresentative
parent object.
PENDING_USER_ACTION
value for UserStatus
can be returned on both versions of the GET endpoint.On the POST and PUT, it can be only be triggered by the new SCA endpoint routes (with /sca/
).