SCAProxy and mTLS

Proxy management

Some platforms, due to their activity and integration workflow, may wish to take actions on behalf of users in certain circumstances.

If the action is one that is subject to SCA, then it is possible for the platform to perform the action on the user’s behalf, but Mangopay must ensure that the user consents.

In order to be allowed to perform an SCA-triggering action on a user’s behalf:

  • The legal documentation (e.g. terms and conditions) between your platform and the user must include the actions that you take on their behalf by proxy
  • Mangopay must have the user’s consent to the proxy that allows your platform to act on the user’s behalf for the specific action

Note – Acting under proxy requires approval by Mangopay

The use of USER_NOT_PRESENT, user consent, and a proxy requires explicit approval by Mangopay.

For compliance reasons, implementing this feature requires authorization by Mangopay and is not necessarily available for all platforms. If your platform wishes to take advance of proxy for SCA-triggering actions, contact our teams via the Dashboard.

Based on the information you will be asked to provide, Mangopay will either approve or deny your request to use a proxy and user consent for SCA-triggering actions.

Acting under proxy will also require additional authentication by your platform when you call the Mangopay API. To satisfy SCA on your platform directly, Mangopay is implementing a new authentication factor, an mTLS certificate, to be used in addition to your existing API key.

Read more in the provisional guide →

How Mangopay’s proxy management system works

As explained in the rest of this guide, Mangopay’s system for managing proxy involves:

  1. User consent on authorized actions under proxy

Mangopay will collect and manage consent from end users using the existing SCA session redirection and hosted experience (proxy management system).

Mangopay has released a new consent endpoint to manage user consent independently of SCA-triggering actions (but consent can also be first collected at the moment of an SCA action).

  1. SCA context

The ScaContext parameter is used to orchestrate the logic of whether:

  • The user is taking the action: they are on-session and able to perform SCA and your platform redirects them to the SCA hosted experience (if SCA redirection link is returned by the API, which doesn’t happen if Mangopay applies an exemption). This is indicated by the USER_PRESENT value.
  • The platform is taking the action under proxy from the user and the user has given consent to Mangopay to allow the action. This is indicated by the USER_NOT_PRESENT value.

Integration timeline

Integration actionAvailableDeadline
Request activation of the proxy management systemNowDec 15, 2025
Integrate consent management endpoint to collect consent and enable users to revoke itNowDec 15, 2025
Start collecting user consent for proxy (via dedicated endpoint and other SCA sessions)Once proxy activated in productionDec 15, 2025

Ensure you send the relevant ScaContext value on all endpoints:

  • Transfers (ensure correct value sent)
  • Wallet access (ensure correct value sent)
  • Users (new, needed for proxy)
  • Recipients (new, needed for proxy)

Now

Dec 15, 2025

SCA actions under proxy

Provided UserCategory is OWNER and therefore SCA applies, the actions for which the user can grant proxy to your platform, and consent to Mangopay, are:

ActionRelevant endpoint(s)

Change SCA contact information (Email or PhoneNumber)

Retrieve account balances and transactions

Register or change external accounts

Initiate payment transactions

The consent to each action above requires explicit consent from the user by way of a checkbox via the proxy management system in the hosted experience.

Note that the action for recipients includes creation and modification, as modification is planned in future even if it is not possible now.

Note – Proxy consent must reflect your legal documentation

The actions consented to by the user must reflect the legal documentation that your platform has in place with the user (for example, terms and conditions or a separate document for power of attorney or similar).

Mangopay is not party to the proxy and only collects user consent.

During integration and activation, your platform needs to inform Mangopay which of the 4 SCA-triggering actions for which Mangopay collects consent are included in your proxy.

Dashboard actions under proxy

Platforms using the Dashboard to complete SCA-triggering actions also need to ensure that a proxy is in place for the action, and they need to collect and manage user consent via the API.

The consent status for a given user will be available in the Dashboard (only, not the API).

To manage the consent of the user, Mangopay is leveraging its hosted SCA experience, to which you redirect the user to complete SCA enrollment and authentication.

New proxy management screen in hosted SCA experience

Mangopay is adding a proxy consent collection screen with a series of checkboxes that allow the user to give consent.

The screenshot below shows the 4 possible SCA-triggering actions under proxy, but only those relevant to the scope of your platform’s proxy agreed with the user will be shown.

A version of the consent screen is displayed in the SCA session:

  1. At the point of SCA enrollment, during the first SCA session the user completes (provided SCA by proxy is activated for your platform)
  2. On the next SCA session they use following the activation of the proxy management system
  3. On the next SCA session they use following the modification of the proxy actions (that is, if your platform adds an action)
  4. Independently of enrollment or an SCA-triggering action, on the SCA session URL returned by the POST Manage proxy consent for a User endpoint

The action of giving consent or changing consent is authenticated by SCA, so once the user ticks the checkbox, they are required to authenticate using their chosen factors. At enrollment, they are asked to enroll their chosen factors.

The user must be able to revoke their consent via your platform at any time. You need to enable this by integrating the POST Manage proxy consent for a User endpoint.

The user also has the right to contact Mangopay to revoke their consent. In this case, Mangopay does not plan to proactively inform your platform. You will, however, be able to see a given user’s consent status in the Mangopay Dashboard (but not in the API).

The POST Manage proxy consent for a User endpoint allows your platform to:

  • Collect consent independently of an SCA-triggering action
  • Allow the user to revoke their consent, which you must enable at any time

The endpoint returns a PendingUserAction.RedirectUrl on which you need to redirect the user so they can give or revoke their consent.

Note – Encode and add your returnUrl before redirection

You must add your returnUrl before you redirect the user on the RedirectUrl value, otherwise the hosted web page cannot return them upon completion.

For more details, see How to redirect a user for SCA.

Add an SCA-triggering action to proxy

During integration and activation, your platform needs to inform Mangopay which of the 4 SCA-triggering actions for which Mangopay collects consent are included in your proxy.

It may happen that your platform needs to add a consent scope after activation, to obtain consent for an additional action.

To do so:

  • Contact Mangopay to change the proxy action with appropriate elements to justify why you need to extend the scope of actions to be performed under proxy (e.g. update terms and conditions and or update power of attorney).
  • Obtain consent for the new scope during the next SCA session for that user, which can be via POST Manage proxy consent for a User

Your platform may also wish to remove a proxy action scope. In this case, you need to contact Mangopay and request the change. The user does not need to be notified.

The new endpoint to manage consent returns only the SCA redirection link to the hosted experience (PendingUserAction.RedirectUrl).

Its purpose is to obtain or update user consent independently of SCA enrollment (or an SCA-triggering action).

It returns the same body as the existing enrollment endpoint but it serves a different use case:

  • POST Manage proxy consent for a User can only be called if the user is already enrolled in SCA (UserStatus is ACTIVE)
  • POST Enroll a User in SCA can only be called if the user is not yet enrolled in SCA (UserStatus is still ACTIVE), or is retrying a re-enrollment following a call to a PUT modification endpoint (in this case their UserStatus is PENDING_USER_ACTION)

Webhooks

Your platform can set up webhooks for the following event types to be notified if a User gave or revoked their consent to the platform taking actions on their behalf under proxy:

  • SCA_CONTACT_INFORMATION_UPDATE_CONSENT_GIVEN
  • SCA_CONTACT_INFORMATION_UPDATE_CONSENT_REVOKED
  • SCA_TRANSFER_CONSENT_GIVEN
  • SCA_TRANSFER_CONSENT_REVOKED
  • SCA_RECIPIENT_REGISTRATION_CONSENT_GIVEN
  • SCA_RECIPIENT_REGISTRATION_CONSENT_REVOKED
  • SCA_VIEW_ACCOUNT_INFORMATION_CONSENT_GIVEN
  • SCA_VIEW_ACCOUNT_INFORMATION_CONSENT_REVOKED

These webhooks are triggered by the User changing their consent and completing the SCA session to authenticate the change.

SCA status endpoint

The GET View a User SCA status endpoint returns information about:

  • The user’s SCA enrollment
  • Their consent to the proxy action scopes that your platform has activated (in the ConsentScope response object)

You can use this endpoint to check the consent given by a user in advance of attempting to take action under proxy.

SCA context

To orchestrate the logic of whether an SCA-triggering action is performed by the platform or the user, Mangopay is relying on the ScaContext API parameter.

Definition of ScaContext

With the release of user consent, the values have the following meanings in all cases:

  • USER_PRESENT – The user is taking the SCA-triggering action. The platform must redirect the user using the PendingUserAction.RedirectUrl returned so that the user can complete the SCA session (unless Mangopay applied an exemption, so no redirection link was returned).
  • USER_NOT_PRESENT – The platform is taking the action under proxy from the user and the user has given consent to Mangopay to allow the action.

The sections below describe how this new behavior is being enforced on cases where it is already present, and the cases where it is being newly added.

Caution – SCA must be performed or consent must be given

SCA must be performed on all SCA-triggering actions taken by the end user. For all SCA-triggering actions taken by the platform under proxy, Mangopay must have the user’s consent.

Your platform must send the correct ScaContext value in all cases.

Transfers and wallet access

The ScaContext parameter (defined above) is already present on the endpoints for the following action scopes:

ActionRelevant endpoint(s)

Retrieve account balances and transactions

Initiate payment transactions

However, the proxy management system makes it possible to enforce SCA fully in these scenarios. Therefore, the default value will be changed to enforce SCA:

Previous default valueUSER_NOT_PRESENTBefore proxy and user consent management, not sending ScaContext or sending USER_NOT_PRESENT was a temporary measure used to allow platforms to adopt SCA.
New default valueUSER_PRESENTWith proxy and consent management, the platform can collect the user’s consent and send USER_NOT_PRESENT to indicate that the platform taking the SCA-triggering action. Otherwise, the user must perform SCA.

User and recipient endpoints

The ScaContext parameter (defined above) is being added to the endpoints for the following action scopes.

The default value on users and recipients is USER_PRESENT.

ActionRelevant endpoint(s)Conditions

Change SCA contact information (Email or PhoneNumber)

If the request modifies:

  • For a Natural User, the Email, PhoneNumber, or PhoneNumberCountry parameters
  • For a Legal User, the Email, PhoneNumber, or PhoneNumberCountry sub-parameters of the LegalRepresentative object parameter

Register or change external accounts

If RecipientScope is PAYOUT

User account creation

Account creation is not an action that triggers SCA, but SCA enrollment must ordinarily be completed at the moment of account creation.

However, upon request in certain cases, Mangopay may allow account creation without simultaneous SCA enrollment. This possibility is considered on a case-by-case basis following a risk analysis. In such cases, it is essential that your platform ensures that users complete their SCA enrollment using the dedicated POST Enroll a User endpoint as soon as possible after account creation, and that you platform implements best practices to ensure that they do (such as periodic reminders).

Therefore, to serve these use cases, ScaContext is also added to the creation and categorization endpoints:

SCA context decision logic

Mangopay’s SCA solution relies on the ScaContext value to determine whether SCA should be performed by the user or if the action can be allowed under proxy with the user’s consent.

The logic of the overall flow is shown below:

Note – SCA exemptions on specific action

It may happen that Mangopay can apply an SCA exemption on a specific instance of an SCA-triggering transfer or wallet access request. If this happens, then the PendingUserAction.RedirectUrl is not returned even if the USER_PRESENT value was sent for ScaContext.

This is not reflected in the diagram above.

Therefore, for an action to be allowed with ScaContext set to USER_NOT_PRESENT, the following must be true:

  • Your platform has a proxy in place to act on the user’s behalf (in your legal documentation)
  • The proxy management system is activated for the action
  • The user has given their consent to Mangopay for the action

If the user’s consent is missing, either because it hasn’t been given yet or it has been revoked, then sending USER_NOT_PRESENT returns a 403 error:

403/401 - Consent not given for USER_NOT_PRESENT
1{
2    "Message": "You are not authorized to perform this action. The user has not provided consent to the requested proxy",
3    "Type": "sca_proxy_missing",
4    "Id": "bbf56cc0-079d-44fd-9e23-53bdb3e283e5#1762177336",
5    "Date": 1762177337,
6    "errors": null
7}

In this situation, your platform has two options:

  1. Obtain consent from the user by calling POST Manage proxy consent for a User and redirecting the user to the hosted SCA session, asking them to check the relevant checkbox. Then retry the initial action with USER_NOT_PRESENT.
  2. Retry the action with the user on session to authenticate by setting ScaContext to USER_PRESENT and redirecting the user on the PendingUserAction.RedirectUrl returned. Note that this SCA session also presents the user with the consent screen on which they can check the checkbox to give consent for future actions.