Instant payouts
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). Please contact support@mangopay.com to activate instant payouts. See below for activation approaches.
Introduction
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 bank wires.
Scope
This functionality is available on the PayOuts object. Instant payment is only possible for payout bank wires in euros to a receiving bank in the SEPA zone.
Prerequisites
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 an instant payout. 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.
Instant payments are not possible to bank accounts created using v1 of the API.
To determine whether a bank account was created using v1 or v2, please compare with the following examples:
BankAccount
example created using API v1
{
"OwnerName": "Name Surname",
"OwnerAddress": "6 rue Ordeneria, batiment A, 75018 Paris FR",
"IBAN": "FR7610107041011234567890129",
"BIC": "BREDFRPPXXX",
"Tag": "Postman create a bank account"
}
BankAccount
example created using API v2
{
"OwnerName": "Name Surname",
"OwnerAddress": {
"AddressLine1":"6 rue Ordeneria",
"AddressLine2": "batiment A",
"City": "Paris",
"PostalCode":"75018",
"Country":"FR"
},
"IBAN": "FR7610107041011234567890129",
"BIC": "BREDFRPPXXX",
"Tag": "Postman create a bank account"
}
Activation
Please contact support@mangopay.com to activate instant payouts. There are two ways you can integrate this feature:
1. On demand
On calls to the Create a PayOut endpoint, the parameter PayoutModeRequested enables you to request the instant payment mode on each payout using the value INSTANT_PAYMENT (or INSTANT_PAYMENT_ONLY, see below). If this parameter is not sent, the payout will be processed as STANDARD (within 48 hours).
2. Threshold
Alternatively, MANGOPAY can set a threshold under which all payouts will be attempted as instant payments. In case of an unsuccessful instant payment attempt, there is a fallback so that the payout will be made automatically via standard bank wire. The threshold approach requires no integration on your side; the feature can be activated as soon as you request it. The on-demand functionality can still be used even if a threshold is in place. If you set a PayoutModeRequested value for a particular payout call, it will take precedence over the threshold rule in place.
Please contact support@mangopay.com to switch the activation mode.
Endpoints
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.
POST /payouts/bankwire
Field name | Format | Required | Description |
---|---|---|---|
PayoutModeRequested | string | OPTIONAL | Payout mode requested. May take one of the following values: STANDARD (value by default if no parameter is sent): a standard bank wire is requested and the processing time of the funds is about 48 hours; INSTANT_PAYMENT: an instant payment bank wire is requested and the processing time is within 25 seconds (subject to prerequisites); INSTANT_PAYMENT_ONLY: an instant payment bank wire is requested and the processing time is within 25 seconds, but, if any prerequisite is not met or another problem occurs, there is no fallback: the wallet is automatically refunded and the payout is not completed. |
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 new endpoint gives the same information as the existing one with additional information regarding the instant payment.
GET /payouts/bankwire/{id}
Field name | Format | Description |
---|---|---|
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 | object | Details regarding the reason for refusal of an Instant Payout request.{"Code": "001999", "Message": "Generic Operation error"} If no fallback occurred, null is returned |
Verify the eligibility of an instant payout request
Before making a payout request, you can verify that all your settings are correct and that the destination bank is reachable with a POST call to the following endpoint.
This call has the same parameters as the payout request but is to a different endpoint.
Note, however, that you need to set the PayoutModeRequested
parameter to “INSTANT_PAYMENT” for this call to work properly.
POST /{ClientID}/payouts/reachability/
Field name | Sub-field name | Format | Description |
---|---|---|---|
InstantPayout | IsReachable | Boolean | Indicates whether the instant payout request is eligible. |
UnreachableReason | Object | Details regarding the reason(s) for non-eligibility of an instant payout. {"Code": "130009", "Message": "The destination IBAN is not valid"} |
For more details on the result codes, please see Errors.
Testing
To simulate a banking error blocking an instant payment, you can use the following bank account:
"IBAN": "FR541558929750ZZZZZZAC01915",
"BIC": "CMBRFR2BXXX",
To simulate a non-reachable bank account, you can enter the following bankwire reference in the call body:
"BankWireRef": "IP1070",