> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mangopay.com/guides/refunds/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mangopay.com/_mcp/server.

# Refunds

## Docs

- [How to process a refund](https://docs.mangopay.com/guides/refunds/how-to.md): Step-by-step guide to processing full or partial refunds, including transfer and pay-in refunds to return funds to the user.


> **Note:** This page contains both a page directory (above) and the landing page content (below). The page directory is generated for agent use and does not appear on the landing page.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mangopay.com/guides/refunds/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mangopay.com/_mcp/server.

# 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

transaction

, which means there three types of [Refund](/api-reference/refunds/refund-object) object:

<table class="header-column">
  <tbody>
    <tr>
      <th class="header">
        Pay‑in refund
      </th>

      <td class="table-content">
        Request to reimburse a

        pay-in

        , which is supported for most payment methods.
      </td>
    </tr>

    <tr>
      <th class="header">
        Transfer refund
      </th>

      <td class="table-content">
        Request to reimburse a

        transfer

        (i.e., a transaction from a wallet to another).
      </td>
    </tr>

    <tr>
      <th class="header">
        Payout refund
      </th>

      <td class="table-content">
        Reimbursement of a

        payout

        , 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](/guides/payouts/rejects-returns) section.
      </td>
    </tr>
  </tbody>
</table>

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](/guides/refunds/how-to)

See how to process pay-in and transfer refunds

## Pay-in refunds

### Prerequisites

The following conditions must be met to perform a pay-in refund:

* The amount value is `1` or above, regardless of the currency.
* The initial pay-in status is `SUCCEEDED`.
* The initial pay-in hasn't been disputed.
* The initial pay-in was made within the time window specified for the [payment method](/guides/payment-methods).
* The payment method is not:
  * [Bank wire pay-in](/api-reference/bank-wire-payins/create-bank-wire-payin)
  * [Pay-in to virtual IBAN](/api-reference/virtual-accounts/view-payin-external-instruction)
  * [Pay by Bank](/api-reference/pay-by-bank/create-pay-by-bank-payin)
  For these payment methods, the Refund endpoint can't be used and you need to use a [Payout](/api-reference/payouts/create-payout) provide the ID of the initial transaction in the `PaymentRef` (see [refunds using payouts](/guides/payouts/integration#refunds-using-payouts) for details).

### 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 `DebitedFunds.Amount` value lower than the initial transaction amount. The `Fees.Amount` must also be lower than the `DebitedFunds.Amount`, meaning you can't do a refund that consists only of `Fees`.

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.

## Transfer refunds

### Prerequisites

The following conditions must be met to perform a transfer refund:

* The amount value is `1` or above, regardless of the currency.
* The initial transfer status is `SUCCEEDED`.
* The initial transfer was made within the last 13 months.

### 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](/guides/payouts/rejects-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 `Fees` parameter 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.

## Related resources

#### [Endpoint](/api-reference/refunds/refund-object)

The Refund object

#### [Guide](/guides/refunds)

Learn how to process a refund