Overview
A payout is the process of withdrawing funds from the Mangopay environment to an external bank account opened in the name of the Mangopay account holder.
As detailed in the prerequisites below, the user must be verified (their KYCLevel
must be REGULAR
) and the bank account must be valid and in their name.
How Mangopay sends funds
How Mangopay sends a payout is determined by:
1. The user’s bank account and its type
Bank accounts in the API have a different Type
depending on the country of registration of the account, and different information is required for each to reflect local formats (see prerequisites below).
The country of registration of a bank account is not linked to its currency. For example, a EUR payout to an account registered in the US requires a US-type account. A CAD payout to an account registered in Italy requires an IBAN-type account.
2. The currency of the payout
Mangopay can send payouts in a wide range of currencies – see the currencies page for details.
Receiving banks can be anywhere in the world. The currency of the payout combines with the account type to determine whether the bank wire is sent locally or internationally, which impacts processing times and costs.
For more information, see the bank wire glossary definition and pricing page.
3. The mode requested by the platform (if EUR in SEPA)
If the payout is in EUR in the SEPA zone, platforms can choose to request an Instant Payout or not. There are two modes of payout:
- Standard - For all currencies and all bank account types, a request to send funds by the quickest route available (see processing times below).
- Instant payment - For EUR in SEPA (only), a request to send funds as an SEPA Instant Credit Transfer (in about 25 seconds, see instant payout below).
Basic flow
Mangopay’s e-wallet system allows users of the Owner category to hold funds in their wallets. The user must be verified to withdraw funds to their bank account as a payout.
The flow is as follows:
- Ensure the Owner user is verified (
KYCLevel
isREGULAR
) - Create a Bank Account to register their bank account
- Create a Payout to request that Mangopay wire the funds
Once the payout is successfully requested, its status becomes CREATED
.
You should set up hook notifications for the following event types to be notified of its progress:
- PAYOUT_NORMAL_SUCCEEDED
- PAYOUT_NORMAL_FAILED
The SUCCEEDED
status indicates that Mangopay successfully processed the payout and sent the funds. There are some cases where the funds are returned by the receiving bank and Mangopay creates a payout refund (see below).
In case of a FAILED
status, you can use the GET View a Payout endpoint to see more information, particularly the ResultCode
and ResultMessage
. For more information on specific errors, see Error codes.
Note - Testing payouts
You can find all you need to test payouts in Sandbox in the Testing payouts article.
Prerequisites
User verification
Mangopay has legal obligations to verify the identity of users who wish to make payouts. Therefore, payouts can only be performed to bank accounts whose owner (as defined by the Bank Account object’s User) is verified.
If the user is not verified, the payout Status
will automatically be set to FAILED
after being processed by Mangopay. This processing usually takes a few seconds, but can be longer due to the amount or supplementary fraud checks.
Note - Payout Status
may remain CREATED
In the production environment, a payout can remain with the CREATED
status for longer than expected. This may be due to an uploaded KYC document still pending processing for the corresponding user.
In addition, you should pay special attention to the identities of the payout author and bank account owner. Indeed, when the payout author is different from the bank account owner, the Payout AuthorId
value must be different from the Bank Account UserId
value as well. Otherwise, Mangopay’s Compliance team will reject the payout.
Bank accounts
Different information is required for bank accounts in different countries. This is managed by the Bank Account Type
parameter, which determines the information that needs to be provided via the dedicated endpoint. The values are:
IBAN
– For accounts registered in countries that use IBAN (including the UK when the payout currency is not GBP)US
– For accounts registered in the United StatesCA
– For accounts registered in CanadaGB
– For accounts registered in the United Kingdom only when the payout currency is GBP (for other payout currencies, use theIBAN
type)OTHER
– For accounts registered in countries that do not use IBAN (and are not the US, Canada, or the UK)
The country of registration of a bank account is not linked to its currency.
Caution - Creating the wrong type can lead to processing delays
Failure to use the correct type can lead to processing delays. Use the dedicated types for US, CA, and GB. Only use OTHER if the country isn’t one of these and doesn’t use IBAN.
For USD and CAD payouts made by a natural user, the Address of the author must be provided.
For payments to GB accounts, the OwnerName
must match either the FirstName
and LastName
of the corresponding natural user, or the Name
of the corresponding legal user.
Country restrictions
Due to policy, we don’t accept the creation of bank accounts and payouts to some countries. Please refer to the Country restrictions article for more information.
Minimum amount
The payout minimum amount is €0.10 (or equivalent in other currencies). This is the default amount in Sandbox.
It is not possible to make a payout inferior to €0.10, unless it is a payout made to empty a wallet. In other words, you can only make a €0.05 payout if the wallet balance is also €0.05.
Note that the minimum amount might differ depending on the platform’s contract with Mangopay.
Standard payout processing
Cutoffs and processing times
Standard payouts are processed by Mangopay as quickly as possible. Some payouts are subject to manual review by Mangopay’s teams for reasons of risk management or AML/CFT - these may take longer.
Payouts created before the cutoff times outlined below are transferred to the user’s bank account within the corresponding processing times. Payouts created after the cutoff are processed next .
Cutoffs and processing times vary between currencies and target bank account types:
Currency | Bank account type | Cutoff | Processing time |
---|---|---|---|
EUR | All types | 15:30 CET | 2 working days |
GBP | GB | N/A | ~10 seconds up to 2 hours |
GBP | IBAN | 15:30 CET | 2 – 5 working days |
USD | US | 15:30 CET | 1 working day |
USD | OTHER | 15:30 CET | 2 – 5 working days |
CAD | CA | 15:30 CET | 1 – 2 working days |
DKK | IBAN | 15:30 CET | 2 working days |
Other | All types | 15:30 CET | 2 – 5 working days |
Faster Payments in the UK
For GBP payouts to GB bank accounts, Mangopay sends them automatically via the Faster Payments System (FPS).
The payout is usually processed in a matter of seconds (the Status
changes from CREATED
to SUCCEEDED
) but there can be a delay of up to two hours. The service is available 24/7, 365 days of the year, so there is no cutoff for processing.
Cost-bearing for international USD payouts
For USD payouts sent internationally (that is, not to US-type bank accounts), Mangopay can enable platforms to shoulder the full cost of any processing fees that may arise from correspondent banks. This allows the beneficiary to receive the full amount of USD international payouts.
When activated, cost-bearing uses the OUR configuration of SWIFT international bank wires instead of the SHA option used as standard for international payouts. The fees borne by the platform are recuperated by Mangopay during the usual billing cycle.
Please note that this setting can only be applied to all international USD payouts and is not available on a payout-by-payout basis. A contractual amendment is also required. To activate this option for your platform, contact our teams via the Dashboard.
Payout refunds
Successful payouts can be rejected by the acquiring bank (if the bank account is closed, or if it’s a savings account for instance), and this even if the payout Status
is SUCCEEDED
. In this case, Mangopay generates a Payout Refund request so that the funds can be returned to the wallet.
We recommend you keep track of these refunds by setting up hook notifications for the following event types:
- PAYOUT_REFUND_CREATED
- PAYOUT_REFUND_SUCCEEDED
- PAYOUT_REFUND_FAILED
Additional information regarding the Payout Refund can be found in the RefundReason
object returned by the API.
Possible RefundReasonType
are:
- BANKACCOUNT_INCORRECT
- BANKACCOUNT_HAS_BEEN_CLOSED
- OWNER_DOT_NOT_MATCH_BANKACCOUNT
- WITHDRAWAL_IMPOSSIBLE_ON_SAVINGS_ACCOUNTS
The refund reason type may be accompanied by a custom message in the RefundReasonMessage
parameter.
Related resources
Was this page helpful?