​
Introduction

When a Mangopay Account is created, the account holder must enroll in SCA. A Mangopay account is created when a Natural or Legal user is assigned the 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.

​
Natural user integration

For Natural users, SCA redirection is fully available to integrate, using the individual’s phone number and email. The 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. For Legal users, SCA redirection is fully available to integrate for Soletraders. The individual’s email must be provided via the API, in the 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.
Note – Integrate the new endpoints for all Legal User typesYour platform should still implement the new endpoints and SCA redirection logic if you only have Legal Users whose LegalPersonType is BUSINESS, PARTNERSHIP or ORGANIZATION.The legacy user endpoints will be deprecated in 2026.
To simulate the PendingUserAction.RedirectUrl during your integration, set the LegalPersonType to SOLETRADER to get the RedirectUrl in the response.

​
Existing user integration

Existing users will not be immediately restricted by the introduction of SCA (see below). For existing Natural users and SOLETRADER users (see note on legal users), SCA redirection will be triggered in the following scenarios: Mangopay’s SCA session allows the user to enroll or authenticate as required. We recommend inviting your active Owner users to enroll when they interact with your platform, which you can do using the POST Enroll a User endpoint.
Caution – Legal representative’s email requiredThe 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.
Mangopay may be required to start introducing consequences on users if they haven’t enrolled in SCA, but this will be done with sufficient notice to platforms. You will also be informed of the consequences of non-enrollment, which may include removing certain permissions, blocking the account, reverting the category to 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.

​
Integration action required on Users

Action required now:For new Natural and Legal Users (of all types):
  • Integrate the new endpoints for user creation. Read how →
  • Integrate the new endpoints for changing a PAYER to an OWNER. Read how →
  • Integrate the new endpoints for re-enrollment of enrolled users. Read how →
The new endpoints must be integrated for PAYER users too, regardless of whether they are likely to be come OWNER.For existing users (Natural and Legal Soletrader):
  • Integrate SCA enrollment existing OWNER users at an appropriate moment in your user journey using the dedicated endpoint. Read how →
Possible exemptions on Users:
  • None, because these actions are enrollment or re-enrollment.

​
User status

The new user endpoints for SCA introduce a new possible value for the 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 valueWithout SCA and for all PAYER
ACTIVE (default)The user is active and can access Mangopay features.
CLOSEDThe user is permanently deactivated (Mangopay use only).
For the 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 valueOWNER with SCA
PENDING_USER_ACTION (default)The user must successfully enroll in SCA before for their account to become ACTIVE.
ACTIVEThe 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).
CLOSEDThe user is permanently deactivated (Mangopay use only).

​
Pending user action

The new 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: Set up a webhook notification for the event type 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.
Note – POST Enroll a User endpoint doesn’t change UserStatusA call to the dedicated enrollment endpoint (POST Enroll a User in SCA) does not change the user’s status to 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.
The 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.
Caution – Changing category with legacy PUTThe 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.
When the user’s 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:
400
{
    "Message": "This endpoint is not allowed for User with your current status",
    "Type": "not_allowed_for_pending_user_action_status",
    "Id": "57f871d3-f467-4360-ae74-6af4dac4fb02#1743583911",
    "Date": 1743583912,
    "errors": null
}
If your user is stuck in a PENDING_USER_ACTION status, then you can use POST Enroll a User in SCA to retrieve a new SCA session for them to enroll.

​
Restrictions on existing users

Note – Existing users not restrictedInitially, existing users will not be restricted by the introduction of SCA.Existing users, who already have 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.

​
Webhooks

There are two new event types for which you can create webhook notifications. In both cases the 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.
Note – Webhooks not triggered for non-SCA OwnersThe user account webhooks are not triggered for:
  • Payers
  • Owners if they are created or categorized with the non-SCA endpoints

​
Enrollment in the user lifecycle

The following scenarios describe how you can enroll your users in SCA to create their Owner user account. For an overview, see the diagram below. In each case, the API call triggers SCA and returns the 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.

​
Testing

​
SCA triggers in Sandbox

In Sandbox, SCA is triggered on the SCA-enabled creation (POST) and categorization (PUT) endpoints when all of the following are true:
  • UserCategory is OWNER
  • The type of the user is Natural or Soletrader
In Sandbox, SCA is not triggered if any of the following are true:
  • UserCategory is PAYER
  • The legal user’s LegalPersonType is BUSINESS, PARTNERSHIP, or ORGANIZATION
Notes:
  • POST Enroll a User returns PendingUserAction.RedirectUrl regardless of the user type
  • The PUT endpoints only trigger SCA redirection if PhoneNumber, PhoneNumberCountry, or Email are changed

​
OTP test number and code

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.

​
Postman

The Mangopay API Postman collection contains a dedicated folder for the SCA-enabled User endpoints ready for you to test the solution. See the Postman guide for details on how to fork the collection and set up your environment with your ClientId and API key.

​
Register an Owner for the first time

The following flow should be used to create new Owners and enroll them in SCA at the same time. Any users Owner created on the non-SCA endpoints will need to be enrolled separately (in the flow described below).
1

Call the Mangopay API to provide user data and trigger SCA

Call the POST Create a Natural User (SCA) endpoint to register an Owner and enroll them in SCA:
  • Set UserCategory to OWNER
  • Set TermsAndConditionsAccepted to true (ensuring you have obtained the user’s acceptance of Mangopay’s T&Cs)
  • Provide the required data for Owners
If you provide the 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.
In the API response:
  • UserCategory is OWNER
  • UserStatus is PENDING_USER_ACTION
  • PendingUserAction.RedirectUrl contains the unique URL for the user’s SCA session
The PENDING_USER_ACTION status triggers a webhook notification for the USER_ACCOUNT_VALIDATION_ASKED event type – set up this Hook to be notified.
2

Redirect the user to the SCA session

Define a URL to which the user will be redirected after the SCA session. Encode the URL and append it to the 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.
3

Confirm success or retry the session

After the SCA session, when the user is returned on your 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.

​
Transition a Payer to Owner

Note – Flow for all existing Payer usersYou can use this flow to transition users Payer created before the introduction of SCA as well as those created on the new endpoint.
1

Call the Mangopay API to provide user data and trigger SCA

Call the PUT Categorize a Natural User (SCA) endpoint to transition an existing Payer:
  • Set UserCategory to OWNER
  • Set TermsAndConditionsAccepted to true (ensuring you have obtained the user’s acceptance of Mangopay’s T&Cs)
  • Provide the required data for Owners
If you provide the 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.
In the API response:
  • UserCategory is OWNER
  • UserStatus is PENDING_USER_ACTION
  • PendingUserAction.RedirectUrl contains the unique URL for the user’s SCA session
The PENDING_USER_ACTION status triggers a webhook notification for the USER_ACCOUNT_VALIDATION_ASKED event type – set up this Hook to be notified.
2

Redirect the user to the SCA session

Define a URL to which the user will be redirected after the SCA session. Encode the URL and append it to the 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.
3

Confirm success or retry the session

After the SCA session, when the user is returned on your 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.

​
Enroll an existing Owner

Note – Flow for existing Owner usersYou can use this flow to transition of Owner users created before the introduction of SCA, meaning any Owner user:Read more about integrating SCA for existing users.
1

Call the Mangopay API to trigger SCA

Call the POST Enroll a User in SCA endpoint to obtain an SCA session link for the user to enroll in SCA.If the 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.
2

Redirect the user to the SCA session

Define a URL to which the user will be redirected after the SCA session. Encode the URL and append it to the 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.
3

Confirm success or retry the session

After the SCA session, when the user is returned on your 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.

​
Re-enroll an enrolled Owner

Re-enrollment is required when the PhoneNumber, PhoneNumberCountry, or Email user properties are modified.
1

Call the Mangopay API, triggering SCA

Call the PUT Update a Natural User (SCA) endpoint setting the required parameters:
  • UserCategory to OWNER
  • TermsAndConditionsAccepted to true
If you modify the 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.
In the API response:
  • UserCategory is OWNER
  • UserStatus is PENDING_USER_ACTION
  • PendingUserAction.RedirectUrl contains the unique URL for the user’s SCA session
The PENDING_USER_ACTION status triggers a webhook notification for the USER_ACCOUNT_VALIDATION_ASKED event type – set up this Hook to be notified.
Note – PhoneNumber entered during SCA session not updated in APIThe phone number provided during the SCA session is not updated retroactively in the API user object. This also applies if the 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.
2

Redirect the user to the SCA session

Define a URL to which the user will be redirected after the SCA session. Encode the URL and append it to the 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.
3

Confirm success or retry the session

After the SCA session, when the user is returned on your 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.

​
Integrate new user endpoints for Payers

SCA is not applicable to PAYER users. However, the SCA endpoints must be integrated to register and update PAYER users: In this non-SCA scenario:
  • UserCategory is PAYER
  • UserStatus is ACTIVE
  • PendingUserAction is null
These are the same endpoints that are used with Owners.
Note – Integrate new endpoints to manage PayersPayers are not subject to SCA. However, you must integrate the new SCA-enabled endpoints above to register new Payers and update existing ones, regardless of whether they are likely to become Owners in the future.Mangopay intends to deprecate the legacy User endpoints, because they will have been made redundant by the new SCA-enabled versions.

​
View and list users

There is a new version of the GET View a User (SCA). For Natural users, the response object is the same as the legacy one with the addition of 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.
Note – UserStatus values apply on both versionsThe 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/).
There is no new version of the GET List Users because it only returns a summary of key user data, rather than the full object, so no new endpoint is necessary.

​
User lifecycle diagram: Categories

The introduction of SCA to create an Owner user changes the lifecycle of a user because they cannot become an Owner without SCA. The following diagram shows how SCA impacts the user lifecycle for setting up Payers and Owners.
Note – Not shown in diagramThe diagram below doesn’t show:
  • The PUT Update a User endpoints in all their use cases (e.g. updating Payers)
  • KYC/B verification, which a user can request once they are an Owner
  • The possibility of a user being blocked (which may happen to Payer or Owner)

SCA session

Read more about redirecting users for an SCA session

SCA introduction

Read more about SCA