How to process a refund
Introduction
This how-to guide will show you how to successfully process a refund when, following the pay-in to the Payer’s wallet, a transfer has already been made to the Owner’s wallet.
Prerequisites
- A
ClientIdand an API key – if you don’t have these, contact Sales to get access to the Mangopay Hub - A pay-in to refund (and its corresponding transaction
Id) - The corresponding transfer to refund (and its corresponding transaction
Id)
In a typical integration, the pay-in to the Payer’s wallet triggers a transfer to the Owner’s wallet. To process the refund, you need to refund the transfer first to make sure there are sufficient funds in the Payer’s wallet to refund the pay-in.
By default, Mangopay’s Refund object reimburses the full amount of the initial transaction’s DebitedFunds and any Fees taken. To do a partial refund, you need to specify these amounts.
Best practice - Partial transfer refund followed by partial pay-in refund
To ensure that there are sufficient funds in the relevant wallets, you should always precede a partial refund of a pay-in with partial refund of a transfer. Mixing full and partial refunds in your workflow may result in cash flow issues and discrepancies in reconciliation.
Notes on partial refunds
When doing multiple partial refunds, please note that:
- The refunded funds cannot exceed the initial transaction’s credited funds (and the same rule applies for the fees).
- The debited funds Amount must be at 1 or more; it can’t be zero.
Note - Handling fees
When creating partial refunds, you can either:
- Refund the fees by setting a negative value (i.e., the initial value preceded by a -), or
- Charge additional fees by setting a positive value (thus adding a cost for the refund)
1. Refund the transfer
A. Full refund
Create a Refund for a Transfer by using the initial transaction’s Id as a path parameter, and by indicating the initial transaction’s AuthorId.
B. Partial refund
Create a Refund for a Transfer by using the initial transaction’s Id as a path parameter, and by indicating the initial transaction’s AuthorId.
To do a partial refund, specify the DebitedFunds and Fees parameters manually. If either of these parameters is present, the other one must also be.
2. Refund the pay-in
Proceed with the pay-in refund once the transfer refund status is SUCCEEDED. You can be notified of a successful transfer refund by setting up the following event type for webhook notifications:
- TRANSFER_REFUND_SUCCEEDED
Note - Conditions for 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.
A. Full refund
Create a Refund for a PayIn by using the initial transaction’s Id as a path parameter, and by indicating the initial transaction’s AuthorId.
B. Partial refund
Create a Refund for a PayIn by using the initial transaction’s Id as a path parameter, and by indicating the initial transaction’s AuthorId.
To do a partial refund, specify the DebitedFunds and Fees parameters manually. If either of these parameters is present, the other one must also be.
Note - Repeat partial pay-in refunds of same amount
A waiting time of 24 hours is necessary when refunding the same amount of a single pay-in several times in a row. This is a safety mechanism to avoid unintended duplicate refunds.