Create a Transfer

Note – SCA may be triggered by this endpoint

When a user with UserCategory OWNER initiates a transfer to another OWNER, they are required to complete SCA unless Mangopay can apply an exemption (read more about SCA on transfers).

To let the user complete the SCA session on the Mangopay-hosted webpage, your platform needs to retrieve the returned PendingUserAction.RedirectUrl, add an encoded returnUrl query parameter, and redirect the user. Read more about how to redirect them in the SCA session guide.

Body parameters

ScaContext · string

Possible values: USER_PRESENT, USER_NOT_PRESENT

Default value: null

The SCA context of the request, which is required if the AuthorId references a user whose UserCategory is OWNER:

• USER_PRESENT – The user is initiating the transfer and is actively present. The platform must redirect the user for SCA using the PendingUserAction.RedirectUrl returned, unless an exemption can be applied by Mangopay such as on low-amount and low-risk transfers. Platforms are not able to request specific exemptions (read more).
• USER_NOT_PRESENT – No user is present: the transfer is automated by the platform as part of their declared and authorized workflow. On these transfers, SCA redirection is not initially required, but in future Mangopay may be required to override the request.

The API returns what was sent. Both values may technically result in the need for SCA redirection, because an exemption may be applied by Mangopay or (in future) Mangopay may be required to override a given request.

Note: ScaContext is a temporary mechanism to introduce SCA on existing endpoints and workflows. Platforms integrating for the first time should consider the parameter required and send USER_PRESENT by default. Read more about SCA on transfers →

AuthorId · string · required

The unique identifier of the user at the source of the transaction.

DebitedFunds · object · required

Information about the debited funds.

Show properties

Currency · string · required

Allowed values: The three-letter ISO 4217 code (EUR, GBP, etc.) of a supported currency (depends on feature, contract, and activation settings).

The currency of the debited funds.

Amount · integer · required

An amount of money in the smallest sub-division of the currency (e.g., EUR 12.60 would be represented as 1260 whereas JPY 12 would be represented as just 12).

Fees · object · required

Information about the fees taken by the platform for this transaction (and hence transferred to the Fees Wallet).

Show properties

Currency · string · required

Allowed values: The three-letter ISO 4217 code (EUR, GBP, etc.) of a supported currency (depends on feature, contract, and activation settings).

The currency of the fees.

Amount · integer · required

An amount of money in the smallest sub-division of the currency (e.g., EUR 12.60 would be represented as 1260 whereas JPY 12 would be represented as just 12).

CreditedWalletId · string · required

The unique identifier of the credited wallet.

DebitedWalletId · string · required

The unique identifier of the debited wallet.

Tag · string

Max. length: 255 characters

Custom data that you can add to this object.

Responses

200

ScaContext · string

Possible values: USER_PRESENT, USER_NOT_PRESENT

Default value: null

The SCA context of the request, which is required if the AuthorId references a user whose UserCategory is OWNER:

• USER_PRESENT – The user is initiating the transfer and is actively present. The platform must redirect the user for SCA using the PendingUserAction.RedirectUrl returned, unless an exemption can be applied by Mangopay such as on low-amount and low-risk transfers. Platforms are not able to request specific exemptions (read more).
• USER_NOT_PRESENT – No user is present: the transfer is automated by the platform as part of their declared and authorized workflow. On these transfers, SCA redirection is not initially required, but in future Mangopay may be required to override the request.

The API returns what was sent. Both values may technically result in the need for SCA redirection, because an exemption may be applied by Mangopay or (in future) Mangopay may be required to override a given request.

Note: ScaContext is a temporary mechanism to introduce SCA on existing endpoints and workflows. Platforms integrating for the first time should consider the parameter required and send USER_PRESENT by default. Read more about SCA on transfers →

Id · string

Max length: 128 characters (see data formats for details)

The unique identifier of the object.

Tag · string

Max. length: 255 characters

Custom data that you can add to this object.

DebitedFunds · object

Information about the debited funds.

Show properties

Currency · string

Returned values: The three-letter ISO 4217 code (EUR, GBP, etc.) of a supported currency (depends on feature, contract, and activation settings).

The currency of the debited funds.

Amount · integer

An amount of money in the smallest sub-division of the currency (e.g., EUR 12.60 would be represented as 1260 whereas JPY 12 would be represented as just 12).

CreditedFunds · object

Information about the credited funds (CreditedFunds = DebitedFunds - Fees).

Show properties

Currency · string

Returned values: The three-letter ISO 4217 code (EUR, GBP, etc.) of a supported currency (depends on feature, contract, and activation settings).

The currency of the credited funds.

Amount · integer

An amount of money in the smallest sub-division of the currency (e.g., EUR 12.60 would be represented as 1260 whereas JPY 12 would be represented as just 12).

Fees · object

Information about the fees taken by the platform for this transaction (and hence transferred to the Fees Wallet).

Show properties

Currency · string

Returned values: The three-letter ISO 4217 code (EUR, GBP, etc.) of a supported currency (depends on feature, contract, and activation settings).

The currency of the fees.

Amount · integer

An amount of money in the smallest sub-division of the currency (e.g., EUR 12.60 would be represented as 1260 whereas JPY 12 would be represented as just 12).

Status · string

Returned values: CREATED, SUCCEEDED, FAILED

The status of the transaction.

ResultCode · string

The code indicating the result of the operation. This information is mostly used to handle errors or for filtering purposes.

ResultMessage · string

The explanation of the result code.

ExecutionDate · Unix timestamp

The date and time at which the status changed to SUCCEEDED, indicating that the transaction occurred. The statuses CREATED and FAILED return an ExecutionDate of null.

Type · string

Returned values: PAYIN, TRANSFER, CONVERSION, PAYOUT

The type of the transaction.

Nature · string

Returned values: REGULAR, REPUDIATION, REFUND, SETTLEMENT

The nature of the transaction, providing more information about the context in which the transaction occurred:

• REGULAR – Relative to most of the transactions (pay-ins, payouts, and transfers) in a usual workflow.
• REPUDIATION – Automatic withdrawal of funds from the platform’s repudiation wallet as part of the dispute process (when the user has requested a chargeback).
• REFUND – Reimbursement of a transaction to the user (pay-in refund), to a wallet (transfer refund), or of a payout (payout refund, only initiated by Mangopay).
• SETTLEMENT – Transfer made to the repudiation wallet by the platform to settle a lost dispute.

DebitedWalletId · string

The unique identifier of the debited wallet.

CreditedWalletId · string

The unique identifier of the credited wallet.

PendingUserAction · object

Object containing the link needed for SCA redirection if triggered by the API call (otherwise returned null).

Show properties

RedirectUrl · string

The URL to which to redirect the user to perform strong customer authentication (SCA) via a Mangopay-hosted webpage. This value is a variable and should not be hardcoded.

The SCA session link expires 10 minutes after it’s generated.

Caution: Before redirecting the user on this URL, you must add the query parameter ReturnUrl with the percent-encoded URL to which you want the SCA session to return the user after authentication (whether successful or not).

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

400 - Currency incompatibility

{
    "Message": "Error: multi-currency usage is not authorized",
    "Type": "currency_incompatibility",
    "Id": "0c23333c-a0ef-468a-8d33-7bd7ced6e7d4#1661495038",
    "Date": 1661495039.0,
    "errors": {
        "currency": "The Debited Wallet's currency EUR and the Credited Wallet's currency GBP must be the same"
    }
}  

400 - Author must be debited wallet owner

{
    "Message": "Author should be the Debited wallet owner",
    "Type": "param_error",
    "Id": "3cc18d56-5aab-4271-87aa-7baee84a78a0",
    "Date": 1756456857.0,
    "errors": null
}

200 - SCA required

{
    "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": 3001
    },
    "CreditedFunds": {
        "Currency": "EUR",
        "Amount": 3001
    },
    "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"
    }
}

REST

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