Payout failures

Once initiated successfully, the Payout object has the Status 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 (with Status 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
For the vast majority of payout return objects, the 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, the RefusedReasonType 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 RefundReasonTypeDescription
AC06_BLOCKED_BANKACCOUNTAccount blocked. Ask the user to register a different bank account.
AG01_FORBIDDEN_TRANSACTIONPayout not possible to this account (e.g. because it’s a savings account). Ask the user to register a different account.
AG02_INVALID_BANK_OPERATIONBank operation code not valid.
BANKACCOUNT_HAS_BEEN_CLOSEDAccount closed. Ask the user to register a new (open) account.
BANKACCOUNT_INCORRECTIncorrect identifier (IBAN or account number). Verify the account details with the user.
BE04_BENEFICIARY_ADDRESS_MISSINGAddress missing. See RR03_BENEFICIARY_NAME_OR_ADDRESS_MISSING.
FOCR_RECALLEDPayout recalled by Mangopay following a cancellation request.
INITIALIZED_BY_MANGOPAYRefund initiated by Mangopay.
MD07_BENEFICIARY_IS_DECEASEDBeneficiary indicated as deceased.
MS02_BENEFICIARY_ORDERRejected by order of the beneficiary. Contact the user for details.
MS03_NOT_SPECIFIEDNot specified. Check the RefusedReasonMessage for more details.
OTHEROther. Check the RefusedReasonMessage for more details.
OWNER_DOT_NOT_MATCH_BANKACCOUNTBeneficiary name mismatch. Ensure the registered Recipient (or bank account) owner name matches the beneficiary. See RR03_BENEFICIARY_NAME_OR_ADDRESS_MISSING.
RC01_INVALIDE_BICInvalid BIC. Ensure the BIC is valid. If possible, use the 11-character BIC instead of the 8-character one.
RR01_REGULATORY_REASONMissing debtor account or identification.
RR02_REGULATORY_REASONMissing debtor’s name or address.
RR03_BENEFICIARY_NAME_OR_ADDRESS_MISSINGMissing creditor’s name or address. Ensure the name and address of the Recipient match the beneficiary name and address.

When creating the Recipient:
  • The registered name is specified in the FirstName and LastName of the IndividualRecipient, or the BusinessName of the BusinessRecipient.
  • The registered address is specified in the Address of the IndividualRecipient or BusinessRecipient.
RR04_REGULATORY_REASONA regulatory reason not covered by RR01, RR02 or RR03.