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_CREATEDPAYOUT_REFUND_SUCCEEDEDPAYOUT_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. |