Overview
Introduction
A refund occurs when money is paid back to a user, most often an unsatisfied customer who requests reimbursement for the goods or services purchased.
At Mangopay, a refund refers to a reversal of a , which means we have three types of refund:
| Pay‑in refund | Request to reimburse a , which is supported for most payment methods. |
|---|---|
| Transfer refund | Request to reimburse a (i.e., a transaction from a wallet to another). |
| Payout refund | Return of a , only generated by Mangopay. Payout returns may occur, for example, when the end user’s bank account is closed. |
From the end user’s perspective, therefore, being refunded for a payment on your platform may involve a transfer refund as well as a pay-in refund to complete their refund. This is the case if the initial pay-in automatically triggers a transfer to the recipient’s wallet.
For a step-by-step walkthrough of different cases, see:
How to
Pay-in refunds
Prerequisites
The following conditions must be met to make a pay-in refund:
- The amount value is 1 or above, regardless of the currency.
- The initial transaction was made less than 11 months ago.
- The initial transaction status is
SUCCEEDED. - The initial transaction hasn’t been disputed.
Note - Refunds on bank wire not supported
You cannot make a refund on a bank wire pay-in or a pay-in to virtual IBAN. The commonly used workaround for this is to create a payout.
Partial pay-in refunds
Sometimes, platforms will need to refund only part of the initial pay-in amount (for instance, the customer returns only one product from a larger order).
Mangopay allows for partial pay-in refunds. To partially refund a pay-in, you need to provide a debited funds Amount value lower than the initial transaction amount.
When making multiple partial pay-in refunds, please note that:
- The refunded funds cannot exceed the initial transaction credited funds (and the same rule applies for the fees).
- A waiting time of 24 hours is necessary when refunding the same amount several times in a row. This is a safety mechanism to avoid unintended duplicate refunds.
Note - Partial pay-in refunds limitation on direct debit
For SEPA and BACS direct debits, you’re limited to 5 refunds per pay-in.
Transfer refunds
Partial transfer refunds
Mangopay allows for partial transfer refunds. To partially refund a transfer, you need to provide a debited funds Amount value lower than the initial transaction amount. If you don’t supply the debited funds or the fees, then the full debited funds and fees are reimbursed. The debited funds amount must be at least 1, meaning you can’t refund only the fees.
Payout refunds
Payout refunds are only generated by Mangopay when the user’s bank rejects a payout. This can occur when the end user’s bank account is closed or if the acquiring bank refuses the funds for instance.
The refund object being created automatically, we advise you take advantage of the following event type to set up the corresponding hook notification:
- PAYOUT_REFUND_SUCCEDDED
In this way, you’ll know when the funds arrive back to the relevant wallet, and will be able to view the refund by obtaining its Id.
Handling fees
The Fees parameter on the refunds has a different behavior than for other transactions.
There are two approaches:
- Refunding fees - If the platform wants to refund the fees, a negative value must be passed (i.e., the initial value preceded by a -). This is the default behavior of Mangopay when the refund
Feesparameter is not specified. - Charging fees for the refund - If the platform wants to add a cost to the refund, fees must be set with a positive value. Note that in this case, you cannot reimburse the fees to the user, since the debited funds of the refund cannot exceed the initial transaction.
If not specified, the fees amount will automatically take the value of the initial transaction.