​
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 ClientId and an API key – if you don’t have these, contact Sales to get access to the Mangopay Dashboard
  • 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. Learn more about Refunds →
Best practice - Partial transfer refund followed by partial pay-in refundTo 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 feesWhen 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.
POST /v2.01/{ClientId}/transfers/{TransferId}/refunds 
{
    "Tag":"Created using Mangopay API Postman Collection",
    "AuthorId":"user_m_01HQK25M6KVHKDV0S36JY9NRKR"
}

​
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.
POST /v2.01/{ClientId}/transfers/{TransferId}/refunds 
{
    "Tag":"Created using Mangopay API Postman Collection",
    "AuthorId":"user_m_01HQK25M6KVHKDV0S36JY9NRKR",
    "DebitedFunds":{
        "Currency":"EUR",
        "Amount":100
    },
    "Fees":{
        "Currency":"EUR",
        "Amount":-14
    }
}

​
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 RefundThe 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.
POST /v2.01/{ClientId}/payins/{PayInId}/refunds 
{
    "Tag":"Created using Mangopay API Postman Collection",
    "AuthorId":"user_m_01HQK25M6KVHKDV0S36JY9NRKR"
}

​
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.
POST /v2.01/{ClientId}/payins/{PayInId}/refunds 
{
    "Tag":"Created using Mangopay API Postman Collection",
    "AuthorId":"user_m_01HQK25M6KVHKDV0S36JY9NRKR", 
    "DebitedFunds": {
        "Currency":"EUR",
        "Amount":1400
    },
    "Fees":{
        "Currency":"EUR",
        "Amount":-14
    }
}
Note - Repeat partial pay-in refunds of same amountA 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.

Guide

Learn more about refunds

Endpoint

The Refund object