> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mangopay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Proxy management
> Managing user consent to the proxy allowing you to take action on their behalf
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](/guides/sca#actions-requiring-sca) 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](/guides/sca/platform) **→**
## 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).
2. **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
| Request activation of the proxy management system |
Now |
Dec 15, 2025 |
| Integrate consent management endpoint to collect consent and enable users to revoke it |
Now |
Dec 15, 2025 |
| Start collecting user consent for proxy (via dedicated endpoint and other SCA sessions) |
Once proxy activated in production |
Dec 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:
|
Change SCA contact information (`Email` or `PhoneNumber`)
|
* [PUT Update a Natural User (SCA)](/api-reference/users/update-natural-user-sca)
* [PUT Update a Legal User (SCA)](/api-reference/users/update-legal-user-sca)
|
|
Retrieve account balances and transactions
|
* [GET View a Wallet](/api-reference/wallets/view-wallet)
* [GET List Wallets for a User](/api-reference/wallets/list-wallets-user)
* [GET List Transactions for a User](/api-reference/transactions/list-transactions-user)
* [GET List Transactions for a Wallet](/api-reference/transactions/list-transactions-wallet)
|
|
Register or change external accounts
|
* [POST Create a Recipient](/api-reference/recipients/create-recipient)
|
|
Initiate payment transactions
|
* [POST Create a Transfer](/api-reference/transfers/create-transfer)
|
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).
## User consent
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](#sca-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](/api-reference/users/manage-proxy-consent) 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.
### User’s control over their consent
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](/api-reference/users/manage-proxy-consent) 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).
## Integrate the consent endpoint
The [POST Manage proxy consent for a User](/api-reference/users/manage-proxy-consent) 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**](https://docs.mangopay.com/guides/sca/session#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](/api-reference/users/manage-proxy-consent)
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.
### Difference between enrollment and consent endpoints
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](/api-reference/users/manage-proxy-consent) can only be called if the **user is** **already enrolled in SCA** (`UserStatus` is `ACTIVE`)
* [POST Enroll a User in SCA](/api-reference/users/enroll-user) 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](/webhooks) for the following [event types](/webhooks/event-types##proxy-consent-status-for-sca-triggering-action-scopes) 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](/api-reference/users/view-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](/guides/sca/session) 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](#sca-context)) is already present on the endpoints for the following action scopes:
|
Retrieve account balances and transactions
|
* [GET View a Wallet](/api-reference/wallets/view-wallet)
* [GET List Wallets for a User](/api-reference/wallets/list-wallets-user)
* [GET List Transactions for a User](/api-reference/transactions/list-transactions-user)
* [GET List Transactions for a Wallet](/api-reference/transactions/list-transactions-wallet)
|
|
Initiate payment transactions
|
* [POST Create a Transfer](/api-reference/transfers/create-transfer)
|
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:
| `USER_NOT_PRESENT` |
Before proxy and user consent management, not sending `ScaContext` or sending `USER_NOT_PRESENT` was a temporary measure used to allow platforms to adopt SCA. |
| `USER_PRESENT` |
With 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](#sca-context)) is being added to the endpoints for the following action scopes.
The default value on users and recipients is `USER_PRESENT`.
|
Change SCA contact information (`Email` or `PhoneNumber`)
|
* [PUT Update a Natural User (SCA)](/api-reference/users/update-natural-user-sca) (available)
* [PUT Update a Legal User (SCA)](/api-reference/users/update-legal-user-sca) (available)
|
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
|
* [POST Create a Recipient](/api-reference/recipients/create-recipient) (release planned early November 2025)
|
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](/api-reference/users/enroll-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:
* [POST Create a Natural User (SCA)](/api-reference/users/create-natural-user-sca)
* [POST Create a Legal User (SCA)](/api-reference/users/create-legal-user-sca)
* [PUT Categorize a Natural User](/api-reference/users/categorize-natural-user)
* [PUT Categorize a Legal User](/api-reference/users/categorize-legal-user)
## 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:
```mermaid theme={null}
%%{
init: {
'theme': 'base',
'themeVariables': {
'primaryColor': '#FFFFFF',
'primaryTextColor': '#2D0F37',
'primaryBorderColor': '#2D0F37',
'lineColor': '#2D0F37',
'secondaryColor': '#F5F3F5',
'tertiaryColor': '#FFFFFF',
'fontSize': '32px',
'fontFamily': 'Inter'
}
}
}%%
flowchart TD
A([Action requested])
B[Is SCA required?]
C[Is proxy management activated for the action?]
D[ScaContext value]
E[Consent given by user for action?]
F[SCA performed by the user]
G([Action refused])
I([Action allowed])
A ==> B
B == Yes ==> C
B == No ==> I
C == Yes ==> D
C == No ==> F
D == USER_NOT_PRESENT ==> E
D == USER_PRESENT ==> F
F == SCA session
succeeded ==> I
F == SCA session
failed ==> G
E == Yes ==> I
E == No ==> G
style A stroke-width:3.5px
style B stroke-width:3.5px
style C stroke-width:3.5px
style D stroke-width:3.5px
style E stroke-width:3.5px
style F stroke-width:3.5px
style G stroke-width:3.5px
style I stroke-width:3.5px
```
```mermaid theme={null}
%%{
init: {
'theme': 'base',
'themeVariables': {
'primaryColor': "#090D0D",
'primaryTextColor': "#FFFFFF",
'primaryBorderColor': "#FFFFFF",
'lineColor': "#FFFFFF",
'secondaryColor': "#222525",
'tertiaryColor': "#090D0D",
'fontSize': '32px',
'fontFamily': 'Inter'
}
}
}%%
flowchart TD
A([Action requested])
B[Is SCA required?]
C[Is proxy management activated for the action?]
D[ScaContext value]
E[Consent given by user for action?]
F[SCA performed by the user]
G([Action refused])
I([Action allowed])
A ==> B
B == Yes ==> C
B == No ==> I
C == Yes ==> D
C == No ==> F
D == USER_NOT_PRESENT ==> E
D == USER_PRESENT ==> F
F == SCA session
succeeded ==> I
F == SCA session
failed ==> G
E == Yes ==> I
E == No ==> G
style A stroke-width:3.5px
style B stroke-width:3.5px
style C stroke-width:3.5px
style D stroke-width:3.5px
style E stroke-width:3.5px
style F stroke-width:3.5px
style G stroke-width:3.5px
style I stroke-width:3.5px
```
**Note – SCA exemptions on specific action**
It may happen that Mangopay can apply an [SCA exemption](/guides/sca#exemptions-available-to-mangopay) 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:
```json 403/401 - Consent not given for USER_NOT_PRESENT theme={null}
{
"Message": "You are not authorized to perform this action. The user has not provided consent to the requested proxy",
"Type": "sca_proxy_missing",
"Id": "bbf56cc0-079d-44fd-9e23-53bdb3e283e5#1762177336",
"Date": 1762177337,
"errors": null
}
```
In this situation, your platform has two options:
1. Obtain consent from the user by calling [POST Manage proxy consent for a User](/api-reference/users/manage-proxy-consent) 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.