Read about how SCA impacts wallet access endpoints
OWNER
) requests to access their Mangopay Account, they must authenticate using SCA.
OWNER
users. SCA is required on first-time access and if more than 180 days have passed since the last SCA authentication for account access.
SCA applies even if a wallet is empty and its balance is zero (and even if there have never been funds in it). SCA also applies to a request to list transactions even if no transactions have ever taken place (the list is empty) or all the transaction requests were not successful.
OWNER
user are considered to be part of their Mangopay Account. This means that SCA only has to be done once to access any of the user’s wallets.USER_NOT_PRESENT
described below can be used to declare an automated account access request which won’t trigger SCA redirection. In future, and based on its analysis of adoption, Mangopay may be required to take action to ensure SCA adoption, such as overriding these requests.ScaContext
, which your platform needs to send on all requests initiated by users whose UserCategory
is OWNER
.
The ScaContext
parameter has the values:
USER_PRESENT
– The user is initiating the access and is actively present. SCA is required unless successful SCA for wallet access took place in the last 180 days.USER_NOT_PRESENT
– No user is present: the access is automated by the platform as part of their declared and authorized workflow. SCA is not required (unless the request is overridden by Mangopay).USER_NOT_PRESENT
. This approach allows existing platforms to introduce SCA on their existing integration without undue consequences or breaking changes. 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.
For new platforms, the parameter should be considered required and USER_PRESENT
should be considered the default value.
You do not need to send this parameter if the UserCategory
is PAYER
.
ScaContext
is a query parameter.
So, for example, a request to the GET List Wallets for a User would be made on the following URL (in Sandbox):
https://api.sandbox.mangopay.com/v2.01/ClientId /users/UserId /wallets?ScaContext=USER_PRESENT |
ScaContext
may technically result in the need for SCA redirection: you can include USER_PRESENT
and be exempted by Mangopay, or include USER_NOT_PRESENT
and, in future, have SCA imposed by Mangopay.
When Mangopay determines that SCA is required, a call to any of the 4 endpoints above will return a 401 - Unauthorized.
The RedirectUrl
value needed for the user to be able authenticate is returned in the WWW-Authenticate
response header, in the following format:
RedirectUrl
in the same way.WWW-Authenticate
response header.RedirectUrl
value to redirect the user.
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.returnUrl
, regardless of the outcome.
Once SCA is successful, subsequent calls to any of the above endpoints return the wallet or transaction data for the next 180 days, because SCA can be exempted, and then SCA redirection will be required again.
controlStatus
query parameter appended to your returnUrl
by Mangopay after the SCA session.
You can retry the wallet access by calling the relevant GET endpoint again.
UserCategory
value OWNER
ScaContext
is USER_PRESENT
UserCategory
value PAYER
LegalPersonType
is BUSINESS
, PARTNERSHIP
, or ORGANIZATION
ScaContext
is USER_NOT_PRESENT
or not sent (in which case it is null
)ScaContext
query parameter with the value USER_PRESENT
on wallet access endpoints, and a script for extracting the RedirectUrl
from the 401 response.
See the Postman guide for details on how to fork the collection and set up your environment with your ClientId
and API key.