​

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.

​

Legal user integration

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.

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:

• For existing PAYER users, when you change their category to OWNER using PUT Categorize a Natural User or PUT Categorize a Legal User (available now)
• For existing OWNER users, when you:
  • Enroll them proactively using POST Enroll a User (available now)
  • Register a Recipient (bank/payment account) for them (when SCA feature launched)
  • Request a user-initiated transfer for them to another OWNER (when SCA feature launched)
  • Request to access their wallet balance or transaction history (when SCA feature launched)

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.

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

​

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.

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.

​

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:

• Creation using the SCA-enabled POST endpoints if OWNER:
  • POST Create a Natural User (SCA)
  • POST Create a Legal User (SCA)
• Categorization as OWNER using the SCA-enabled endpoints:
  • PUT Categorize a Natural User
  • PUT Categorize a Legal User
• If already enrolled in SCA, modification Email (LegalRepresentative.Email) or PhoneNumber (LegalRepresentative.PhoneNumber) via the SCA-enabled PUT endpoints:
  • PUT Update a Natural User (SCA)
  • PUT Update a Legal User (SCA)

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.

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.

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:

{
    "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

​

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.

​

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).

​

Transition a Payer to Owner

​

Enroll an existing Owner

​

Re-enroll an enrolled Owner

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

​

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:

• POST Create a Natural User (SCA)
• PUT Update a Natural User (SCA)
• POST Create a Legal User (SCA)
• PUT Update a Legal User (SCA)

In this non-SCA scenario:

• UserCategory is PAYER
• UserStatus is ACTIVE
• PendingUserAction is null

These are the same endpoints that are used with Owners.

​

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.

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.

​

Related resources