Instant payment (payout)
Please note: instant payment for payout is in the beta phase. Use of this feature must be authorised and activated by MANGOPAY. Attempts to use the parameters described below without this authorisation will result in the payout being treated as standard (processed in 48 hours). If you are interested in joining the beta, please contact email@example.com.
The instant payment mode allows payouts to be processed within 25 seconds, rather than the 48 hours required for the batch processing of standard payout bankwires.
This functionality is available on the payout endpoint. Instant payment is only possible for payout bankwires in euros to a receiving bank in the SEPA zone.
The following criteria are checked by MANGOPAY before we send a request for instant payment:
You are authorised to execute instant payments
You use the version 2.01 of the MANGOPAY API
The user holding the bank account is KYC verified (KYCLevel=REGULAR)
The user is not blocked by MANGOPAY
The payout is in euros and the receiving bank is in the SEPA zone
The amount of the payout is lower than the threshold above which MANGOPAY carries out a manual verification to guarantee the security of your funds (this threshold depends on your activity and workflow, but it is about €2,500 on average)
Once these verifications are complete, we proceed with the request for instant payment. Several other criteria must be respected for the operation to be instantaneous:
- The receiving bank must be reachable. This means that it participates in the SEPA Instant Credit Transfer scheme of the European Payments Council (EPC). A non-exhaustive list of reachable banks can be found on the EPC website.
- No opposition is linked to the banking situations of the creditor or debtor. These oppositions can be functional (e.g. deceased account holder) or technical (e.g. the receiving bank does not respond).
- No instant payment has been made to the same bank account for the same amount in the preceding 24 hours.
If any one of the criteria above is not satisfied, we process the instant payment request as a standard payout.
Request an instant payment
On calls to the payout endpoint, the parameter PayoutModeRequested enables you to request an instant payout by using the value INSTANT_PAYMENT. Otherwise, you can use the value STANDARD to request a normal payout (processed in under 48 hours).
If no parameter is sent, the payout will be processed as STANDARD.
|AuthorId||string||REQUIRED||A user's ID|
|DebitedFunds||Money||REQUIRED||Information about the funds that are being debited (amount and currency)|
|DebitedFunds.Currency||CurrencyIso||REQUIRED||The currency - should be ISO_4217 format|
|DebitedFunds.Amount||Int||REQUIRED||An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)|
|Fees||Money||REQUIRED||Information about the fees that were taken by the client for this transaction (and were hence transferred to the Client's platform wallet)|
|Fees.Currency||CurrencyIso||REQUIRED||The currency - should be ISO_4217 format|
|Fees.Amount||Int||REQUIRED||An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)|
|BankAccountId||string||REQUIRED||ID of the receiving bank account|
|DebitedWalletId||string||REQUIRED||ID of the wallet that was debited|
|BankWireRef||string||OPTIONAL||A custom reference you wish to appear on the user’s bank statement (your Client Name is already shown). We advise you not to add more than 12 characters.|
|PayoutModeRequested||string||OPTIONAL||Payout mode requested. May take one of the following values: STANDARD (value by default if no parameter is sent): equivalent to the existing behaviour, the processing time of the funds is about 48 hours - INSTANT_PAYMENT: the payout is requested as a instant payment|
In the response to the API call, the parameter Status will have the value CREATED to indicate that the request has been taken into account.
Verify the payout mode used
Once the payout request has been made, you can verify the mode applied via a GET call to the following endpoint. This endpoint gives the same information as the existing one with additional information regarding instant payment.
|Status||string||The status of the payout, whichever mode was requested or applied.|
|ModeRequested||string||The payout mode that you initially requested.|
|ModeApplied||string||The payout mode applied in executing the payout request.|
|FallbackReason||string||Details regarding a possible reason for refusal of an instant payment request. The definitions employed in this object are being defined.|