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.
In the Mangopay API, a refund is a reversal of a , which means there three types of Refund object:
| 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 | Reimbursement of a , known as a payout return. Payout returns are only generated by Mangopay, for example when funds are rejected by the user’s bank. For more details, see the payout returns section. |
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
See how to process pay-in and transfer refunds
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 status is
SUCCEEDED. - The initial transaction hasn’t been disputed.
- The initial transaction was made within the time window specified for the payment method.
Note - Refunds on bank wire pay-ins
You cannot create a Refund object to reimburse a bank wire pay-in or a pay-in to virtual IBAN. Instead, you must use a Payout object and provide the ID of the initial transaction in the PaymentRef.
For more details, see the refunds using payouts section.
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
A payout refund is only generated by Mangopay when the user’s bank rejects a payout and returns the funds.
For more details about this scenario, see the payout returns section.
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.