The introduction of SCA requires a user to enroll (that is, provide credentials and authenticate them) when the Mangopay account is created. The account is created when the user is assigned the UserCategory of OWNER and their UserStatus is ACTIVE.

For SCA enrollment, Mangopay has developed new User endpoints to facilitate this process.

These endpoints allow your platform to redirect the user for SCA when you:

  1. Register an Owner for the first time
  2. Transition a Payer to Owner
  3. Enroll an existing Owner
  4. Re-enroll an enrolled Owner if they change their credentials

This page describes the enrollment scenario (providing and authenticating device details) and how it impacts the user lifecycle – see the diagram below for an overview.

​
User status

In the new user endpoints for SCA, the need for a user to enroll in SCA is indicated by the response parameter UserStatus.

SCA introduces a new possible value for the UserStatus response parameter for User objects that are assigned the OWNER category.

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.

CLOSED

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

ACTIVE

The user account is active and can access Mangopay features.

CLOSED

The user is permanently deactivated (Mangopay use only).

​
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 Owners

The user account webhooks are not triggered for:

  • Payers
  • Owners created with the non-SCA endpoints

​
Enrollment actions triggering SCA

The following scenarios describe how you can enroll your users in SCA to create their Owner user account.

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, see:

SCA session

Read about how to redirect a user for an SCA session

​
Testing

Note – LastName must finish “Review”

To trigger SCA on a user in Sandbox, you need ensure the LastName (or LegalRepresentative.LastName) value finishes with the word “Review”, as shown below.

{
...
	"LastName": "Smith Review"
...
}

In Sandbox, you can use the PhoneNumber +33611111111 (or 0611111111 and FR) and the passcode 702100 to simulate a successful flow.

You can also test by using a real phone number to receive the SMS OTP.

​
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 and actionStatus query parameters 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 users

You 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 and actionStatus query parameters 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 users

You can use this flow to transition of Owner users created before the introduction of SCA, meaning any Owner user created on the non-SCA endpoint (POST Create a Natural User or POST Create a Legal User).

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 and actionStatus query parameters 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 API

The 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 and actionStatus query parameters 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.

​
SCA endpoints usable for Payers

SCA is not applicable to Payers.

However, the SCA endpoints can be used to register and update Payer users:

In this non-SCA scenario:

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

Note that the same endpoints are used with Owners (but UserCategory is OWNER).

Best practice – Integrate these endpoints to manage Payers

Payers are not subject to SCA. However, we strongly recommend that you implement 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 versions

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

​
Diagram: Lifecycle of SCA enrollment

The introduction of SCA to create an Owner user changes the lifecycle of a user because they cannot become an Owner without enrollment. The following diagram shows how SCA impacts the user lifecycle for setting up Payers and Owners. Once an Owner, a user can request KYC/B verification, which is not shown below.

SCA session

Read more about redirecting users for an SCA session

SCA introduction

Read more about SCA

Was this page helpful?

SCA sessionBlocked users