Skip to main content

​
Scope

When a Mangopay Account holder (OWNER) transfers funds to another Mangopay Account holder, they must authenticate using SCA. This means that when an OWNER user initiates a transfer to a wallet held by another OWNER user, the first user must authenticate the request.

​
Action required

On transfers between one OWNER user and another, your platform needs to implement SCA redirection to Mangopay’s hosted webpage.

​
1. Send ScaContext on Owner-initiated transfers

On the POST Create a Transfer endpoint, Mangopay has introduced the body parameter ScaContext, which your platform needs to send on all transfers initiated by users whose UserCategory is OWNER. The ScaContext parameter has the values:
  • USER_PRESENT – The user is taking the SCA-triggering action of initiating a transfer. 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 for low-amount and low-risk transfers, so no redirection link was returned).
  • USER_NOT_PRESENT – The platform is taking the action under proxy from the user and the user has previously given consent to Mangopay (via the SCA hosted experience) to allow the action.
The ScaContext parameter should be considered mandatory and the relevant value must be sent on all transfers initiated by OWNER users. You do not need to send ScaContext if the UserCategory is PAYER.

​
USER_NOT_PRESENT requires proxy

To use the USER_NOT_PRESENT value, your platform must put in place a proxy in your legal documentation, and you must obtain the User’s consent. For more information, see the proxy management guide. The introduction of Mangopay’s proxy management system makes it possible to apply SCA correctly in all cases. If the proxy action is activated for your platform and you send USER_NOT_PRESENT, but the user hasn’t given consent via the hosted SCA experience, then the request will fail. In this case, your platform has two options:
  1. Obtain consent from the user by calling POST Manage proxy consent for a User, and then retry the transfer 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
The rest of this guide describes the USER_PRESENT case.

​
Example API request with user present

{
    "ScaContext": "USER_PRESENT", 
    "AuthorId": "user_m_01JRJM5RR5NYQDN0S6QWJJDRMR",
    "DebitedFunds": {
        "Currency": "EUR",
        "Amount": 50001 
    },
    "Fees": {
        "Currency": "EUR",
        "Amount": 0
    },   
    "DebitedWalletId": "wlt_m_01JRJM7ASZN7YP4MBDVBT0HZF1",
    "CreditedWalletId": "wlt_m_01JRHSTW2NP4MDB45WQMDNS23C",
    "Tag": "Created using Mangopay API Postman Collection"
}

​
2. Redirect the user for SCA if required

For requests made with ScaContext set to USER_PRESENT, the user is on session and can perform SCA. On a given transfer request, it is possible that Mangopay can apply an SCA exemption if the transaction is considered low risk or for a low amount. If SCA is required for the transfer request, the API response contains PendingUserAction.RedirectUrl, as shown in the example below. If an exemption was applied (for USER_PRESENT), then the RedirectUrl is not returned because no redirection is necessary.

​
Example API response

In Sandbox, the Transaction Risk Analysis (TRA) exemption is systematically applied for amounts of 500 EUR or less (or equivalent in other currencies). So in the examples below, setting DebitedFunds.Amount to more than 50000 triggers SCA (see SCA triggers in Sandbox below for details).
  • SCA redirection required
  • Exemption applied
{
    "ScaContext": "USER_PRESENT",
    "Id": "xfer_c_01JRSHQFG2337DBQ4NS8XPYCK7",
    "CreationDate": 1744614179,
    "DebitedWalletId": "wlt_m_01JRJM7ASZN7YP4MBDVBT0HZF1",
    "CreditedWalletId": "wlt_m_01JRHSTW2NP4MDB45WQMDNS23C",
    "AuthorId": "user_m_01JRJM5RR5NYQDN0S6QWJJDRMR",
    "CreditedUserId": "user_m_01JRHSS3B18H86QA0C467RVK07",
    "DebitedFunds": {
        "Currency": "EUR",
        "Amount": 50001
    },
    "CreditedFunds": {
        "Currency": "EUR",
        "Amount": 50001
    },
    "Fees": {
        "Currency": "EUR",
        "Amount": 0
    },
    "Type": "TRANSFER",
    "Nature": "REGULAR",
    "Status": "CREATED",
    "Tag": "Created using Mangopay API Postman Collection",
    "ResultCode": null,
    "ResultMessage": null,
    "ExecutionDate": null,
    "PendingUserAction": {
        "RedirectUrl": "https://sca.sandbox.mangopay.com/?token=sca_0196331bc1247e3fa33be6f9c797abd7"
    }
}
Caution – Encode and add your returnUrl before redirectionYou 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.
The individual must authenticate on the Mangopay-hosted webpage within 10 minutes of the API response. After the SCA session, the user is returned to your specified returnUrl, regardless of the outcome.

​
3. Ensure your integration relies on transfer status and webhooks

The introduction of SCA makes reliance on the Transfer’s Status essential. Whereas previously, a Transfer’s Status would typically pass to SUCCEEDED quickly, with SCA it will remain in CREATED until the user completes SCA. This means that your platform needs to rely on the existing webhook event types for the outcome of the transfer:
  • TRANSFER_NORMAL_SUCCEEDED
  • TRANSFER_NORMAL_FAILED
For more details about setting up webhooks, see the dedicated webhook guide. Once your system receives the webhook notification, call the GET View a Transfer endpoint to retrieve more information about the transfer. If SCA was not successful, the Status changes to FAILED and there are two new SCA-related functional errors that may be returned in ResultCode and ResultMessage:
ResultCodeResultMessageDescription
007101Transfer authentication failed. Please retry with a new request.The user reached the maximum number of retries for one of the authentication factors, so the SCA session failed.
007102Transfer authentication expired. Please initiate a new request.The user did not complete all steps required within 10 minutes, so the SCA session expired.
A transfer can also fail for other reasons that were already applicable before the introduction of SCA. To retry the transfer request, call the POST Create a Transfer endpoint again.

​
Testing

​
SCA triggers in Sandbox

While in Production, Mangopay will apply the exemptions for low-risk or low-amount transfers (read more), the behavior in Sandbox is described below for your integration and testing. In Sandbox, SCA is triggered on POST Create a Transfer when all of the following are true:
  • DebitedWalletId and CreditedWalletId belong to different OWNER users.
  • The type of users owning the wallets is Natural or Soletrader (in any combination for debited and credited user).
  • DebitedFunds.Amount is greater than 500 EUR or equivalent. So if Currency is EUR, this means Amount must be 50001 or more.
  • ScaContext is USER_PRESENT
The users involved in the transfer don’t have to be already enrolled in SCA. In Sandbox, SCA is not triggered if any of the following are true:
  • The legal user’s LegalPersonType is BUSINESS, PARTNERSHIP, or ORGANIZATION
  • The amount is less than 500 EUR or equivalent
  • ScaContext is USER_NOT_PRESENT or not sent (in which case it is null)

​
Postman

The Mangopay API Postman collection contains a dedicated folder for SCA on transfers and wallet access, has the calls needed to set up two Owner users, get funds into their wallets via a direct card pay-in, and then transfer between them using the ScaContext value USER_PRESENT. See the Postman guide for details on how to fork the collection and set up your environment with your ClientId and API key.

SCA session

Read more about redirecting users for an SCA session

Proxy management

Read more about proxy management for USER_NOT_PRESENT