Getting startedRelease notes

API - Feb 26, 2025

Added

User endpoints to enable SCA enrollment

Mangopay is applying strong customer authentication (SCA) on the creation of Natural and Legal users with the UserCategory value OWNER.

SCA requires the Owner user to authenticate with Mangopay directly as they are the Mangopay account holder.

For Natural users, enrollment of the OTP factor is available to integrate, requiring the individual’s PhoneNumber and Email.

For Legal users, enrollment of the OTP factor is available to integrate for Soletraders. The individual’s phone number and email must be provided in LegalRepresentative.PhoneNumber and LegalRepresentative.Email and they must authenticate.

Mangopay started communicating by email about SCA on Owners during February 2025. Your platform will be required to complete the necessary integrations, with specific deadlines communicated during the year.

For any questions, please contact our teams via the Dashboard.

SCA is applicable to Owners in the following scenarios:

  1. Register an Owner for the first time
  2. Transition an existing Payer to Owner
  3. Enroll an existing Owner
  4. Re-enroll a User (if contact details change)

In each case, your platform must redirect the individual to a Mangopay-hosted webpage. The redirection URL for the SCA session is returned by the Mangopay API in the response property PendingUserAction.RedirectUrl. Before redirecting, you need to define, encode, and apprend a returnUrl to which the session returns the user afterwards (whatever the outcome).

For guidance, see the new Owner SCA section:

Guide

Owner SCA – Introduction, SCA session, enrollment


Endpoints

There are new SCA-enabled endpoints for the creation and modification of users, as well as a dedicated one to change the UserCategory. The data schema has also changed, see the details for Natural and Legal users.

Create a Natural User (SCA)

Register a Natural Payer (with SCA enrollment)

Update a Natural User (SCA)

Modify details for a Natural Payer or Owner without changing category

Categorize a Natural User

Transition a Natural Payer to Owner and enroll them in SCA

Create a Legal User (SCA)

Register a Legal Payer or Owner (with SCA enrollment)

Update a Legal User (SCA)

Modify details for a Legal Payer or Owner without changing category

Categorize a Legal User

Transition a Legal Payer to Owner and enroll them in SCA

There is a new endpoint for retrieving an enrollment link for legacy users (and new ones):

Enroll a User in SCA

Obtain an SCA redirection link to enroll an Owner user

There is a new GET endpoint for the new Legal User data schema:

View a User (SCA)

Retrieve a Natural or Legal User with SCA data schema


Webhooks

There are new webhook event types to be notified of Owner account SCA enrollment. They are triggered for existing and newly created users but only if UserCategory is OWNER:

EventType

USER_ACCOUNT_VALIDATION_ASKED

Description

The Owner User has triggered SCA enrollment or re-enrollment. Their access to Mangopay features is restricted until they enroll successfully.

The User’s UserStatus has changed to PENDING_USER_ACTION. This event is only triggered if UserCategory is OWNER.

RessourceId

UserId (Id of the Natural User (SCA) or Legal User (SCA))

EventType

USER_ACCOUNT_ACTIVATED

Description

The Owner User has been successfully enrolled in SCA. They can now access Mangopay features.

The User’s UserStatus has changed from PENDING_USER_ACTION to ACTIVE. This event is only triggered if UserCategory is OWNER.

RessourceId

UserId (Id of the Natural User (SCA) or Legal User (SCA))

Guide

Owner SCA – Introduction, SCA session, enrollment