Payout failures
Once initiated successfully, the Payout object has theStatus
value CREATED
, which changes to SUCCEEDED
or FAILED
to indicate the outcome of the request. The delay between CREATED
and the final status depends on the payout route and the outcome.
If a payout request could not be created in Mangopay’s system or was created and then failed for other reasons, the Status
changes to FAILED
and a webhook is triggered for the event type PAYOUT_NORMAL_FAILED
.
A payout may be rejected for a number of reasons, such as invalid data, compliance or anti-fraud reasons, or by the clearing system or receiving bank.
To view further details about the request, call the GET View a Payout endpoint or, especially if using SCT Inst, the GET View a Payout and check mode applied endpoint.
Details about why the payout failed can be found in the ResultCode
and ResultMessage
, which are described in more detail in the error codes section (particularly payouts and risk management).
Payout returns
Successful payouts (withStatus
value SUCCEEDED
) can be rejected by the acquiring bank, for example if the bank account is closed or not compatible (e.g. if it’s a savings account). In some cases, Mangopay is able to request the recall on behalf of a platform or user.
In these scenarios, Mangopay creates a Refund object for the initial payout so that the funds can be returned to the wallet.
Set up hook notifications for the following event types to be notified of this:
PAYOUT_REFUND_CREATED
PAYOUT_REFUND_SUCCEEDED
PAYOUT_REFUND_FAILED
Status
value passes from CREATED
to SUCCEEDED
within a matter of seconds. On extremely rare occasions, a payout return can fail (FAILED
), in which case details are given in the fields below.
To view the details of a payout return (once SUCCEEDED
), call the GET View a Refund endpoint to see details of the payout return.
In the response, the RefundReason
object parameter contains a RefundReasonType
and RefundReasonMessage
which give more information about why the transaction was returned.
Refusal reasons
When Mangopay creates a payout return, theRefusedReasonType
assigned gives more details about why the refund object was created.
Where possible, Mangopay assigns a code in line with the standards for SEPA Credit Transfer (SCT) reason codes for R-transactions (rejects, returns, recalls, and requests for recall), which are available on the EPC website.
The table below lists the RefusedReasonType
values along with a description and recommendation for how your platform can proceed (where relevant). The RefundReasonMessage
value may provide more information about the specific case.
Note – Types and messages may changeThe
RefundReasonType
and RefundReasonMessage
values may evolve over time as Mangopay improves payout deliverability.Refund RefundReasonType | Description |
---|---|
AC06_BLOCKED_BANKACCOUNT | Account blocked. Ask the user to register a different bank account. |
AG01_FORBIDDEN_TRANSACTION | Payout not possible to this account (e.g. because it’s a savings account). Ask the user to register a different account. |
AG02_INVALID_BANK_OPERATION | Bank operation code not valid. |
BANKACCOUNT_HAS_BEEN_CLOSED | Account closed. Ask the user to register a new (open) account. |
BANKACCOUNT_INCORRECT | Incorrect identifier (IBAN or account number). Verify the account details with the user. |
BE04_BENEFICIARY_ADDRESS_MISSING | Address missing. See RR03_BENEFICIARY_NAME_OR_ADDRESS_MISSING . |
FOCR_RECALLED | Payout recalled by Mangopay following a cancellation request. |
INITIALIZED_BY_MANGOPAY | Refund initiated by Mangopay. |
MD07_BENEFICIARY_IS_DECEASED | Beneficiary indicated as deceased. |
MS02_BENEFICIARY_ORDER | Rejected by order of the beneficiary. Contact the user for details. |
MS03_NOT_SPECIFIED | Not specified. Check the RefusedReasonMessage for more details. |
OTHER | Other. Check the RefusedReasonMessage for more details. |
OWNER_DOT_NOT_MATCH_BANKACCOUNT | Beneficiary name mismatch. Ensure the registered Recipient (or bank account) owner name matches the beneficiary. See RR03_BENEFICIARY_NAME_OR_ADDRESS_MISSING . |
RC01_INVALIDE_BIC | Invalid BIC. Ensure the BIC is valid. If possible, use the 11-character BIC instead of the 8-character one. |
RR01_REGULATORY_REASON | Missing debtor account or identification. |
RR02_REGULATORY_REASON | Missing debtor’s name or address. |
RR03_BENEFICIARY_NAME_OR_ADDRESS_MISSING | Missing creditor’s name or address. Ensure the name and address of the Recipient match the beneficiary name and address. When creating the Recipient:
|
RR04_REGULATORY_REASON | A regulatory reason not covered by RR01, RR02 or RR03. |