Learn how to redirect a user for their hosted SCA session
RedirectUrl
response parameter on relevant actions across its API. The RedirectUrl
is returned as part of the PendingUserAction
response object.
This guide describes how to redirect users for the SCA session. For more details about the factors, how they work, and the experience for users, see the factors guide.
LegalPersonType
is BUSINESS
, PARTNERSHIP
, or ORGANIZATION
, but the endpoints can still be integrated for them. For more details, see the section about legal user integration.Action | Endpoints | Criteria |
---|---|---|
Register a Owner user for the first time | POST Create a Natural User (SCA) or POST Create a Legal User (SCA) | If UserCategory is OWNER |
Transition an existing Payer to Owner | PUT Categorize a Natural User or PUT Categorize a Legal User | None (always returned) |
Enroll an existing Owner | POST Enroll a User in SCA | None (always returned) |
Re-enroll a User | PUT Update a Natural User (SCA) or PUT Update a Legal User (SCA) | If UserCategory is OWNER and any of these are changed:
|
https://sca.mangopay.com?token=0193d02f30df7a188c51cf890a191d21 |
returnUrl
to which the user will be returned after they authenticate on the Mangopay-hosted page, regardless of the outcome.
Append your URL to the RedirectUrl
response value as the returnUrl
query parameter, being sure to percent-encode any non-ASCII characters.
Continuing the previous example, if your returnUrl
is https://example.com, the full URL you will need to redirect the user on is:
https://sca.mangopay.com?token=0193d02f30df7a188c51cf890a191d21&returnUrl=https%3A%2F%2Fexample.com |
returnUrl
before you redirect the user on the RedirectUrl
value. If you don’t, the hosted web page displays an error because it cannot return the user upon completion.The returnUrl
parameter name is case-sensitive.RedirectUrl
and your encoded returnUrl
must be less than 2,000 characters, which is the limit of most web browsers.
RedirectUrl
response value (including the unique token) and your added returnUrl
.
RedirectUrl
is valid for 10 minutes. If the user does not complete the necessary steps during this time, the session can no longer be used and they are returned on your return URL.If this happens, you need to retry the SCA session using the relevant endpoint (see Step 7 below) to obtain a new RedirectUrl
.PhoneNumber
+33611111111
(or 0611111111
and FR
) and the passcode 702100 to simulate a successful flow. You can also use a real phone number to receive the SMS OTP.
returnUrl
to continue their experience on your platform.
On redirection, Mangopay adds an indicative query parameter to your returnUrl
: controlStatus
.
For example:
https://example.com/?controlStatus=VALIDATED |
controlStatus
parameter indicates the outcome of the SCA session itself:
VALIDATED
- The SCA session was successful.FAILED
- The SCA session was unsuccessful and cannot be reused.controlStatus
query parameter is only indicative of the SCA session, not the enrollment or authentication attempt.actionStatus
, that was added to the returnUrl
on redirection. This was subsequently removed for consistency across all SCA redirection scenarios, and to encourage reliance on webhooks.
returnUrl
are indicative.
You should listen for the webhooks events listed below, and confirm the outcome of the action that triggered the SCA session by calling the relevant endpoint of the Mangopay API.
Status change | Webhook event | |
---|---|---|
Success | UserStatus changed from PENDING_USER_ACTION to ACTIVE | USER_ACCOUNT_ACTIVATED , SCA_ENROLLMENT_SUCCEEDED |
Failure | None, UserStatus stayed as PENDING_USER_ACTION | None for user account status; SCA_ENROLLMENT_FAILED or SCA_ENROLLMENT_EXPIRED for SCA enrollment |
Confirm | GET View a User (SCA) |
---|---|
Retry | POST Enroll a User |