> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mangopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Info>
  **Prerequisites**

  * A `ClientId` and an API key – if you don't have these, <a href="https://mangopay.com/contact" target="_blank">contact Sales</a> to get access to the <a href="https://hub.mangopay.com/" target="_blank">Mangopay Dashboard</a>
  * A pay-in to refund (and its corresponding transaction `Id`)
  * The corresponding transfer to refund (and its corresponding transaction `Id`)
</Info>

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](/guides/refunds) **→**

<Note>
  **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.
</Note>

### 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>
  **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)
</Note>

## 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](/api-reference/refunds/create-refund-transfer)

<CodeGroup>
  ```json REST theme={null}
  {
      "Tag":"Created using Mangopay API Postman Collection",
      "AuthorId":"user_m_01HQK25M6KVHKDV0S36JY9NRKR"
  }
  ```

  ```php PHP  theme={null}
  <?php 

  require_once 'vendor/autoload.php';

  use MangoPay\MangoPayApi;
  use MangoPay\Libraries\ResponseException as MGPResponseException;
  use MangoPay\Libraries\Exception as MGPException;

  $api = new MangoPayApi();

  $api->Config->ClientId = 'your-client-id';
  $api->Config->ClientPassword = 'your-api-key';
  $api->Config->TemporaryFolder = 'tmp/';

  try {
      $transferId = 'xfer_m_01HTF5T24CXR0MFHCPV0239S9S';

      $refund = new \MangoPay\Refund();
      $refund->AuthorId = 'user_m_01HQK25M6KVHKDV0S36JY9NRKR';
      $refund->DebitedFunds = new \MangoPay\Money();
      $refund->DebitedFunds->Amount = 500;
      $refund->DebitedFunds->Currency = 'EUR';
      $refund->Fees = new \MangoPay\Money();
      $refund->Fees->Amount = 0;
      $refund->Fees->Currency = 'EUR';
      $refund->Tag = 'Created using Mangopay PHP SDK';
      
      $response = $api->Transfers->CreateRefund($transferId, $refund);

      print_r($response);
  } catch(MGPResponseException $e) {
      print_r($e);
  } catch(MGPException $e) {
      print_r($e);
  }  
  ```

  ```javascript NodeJS  theme={null}
  const mangopayInstance = require('mangopay4-nodejs-sdk')
  const mangopay = new mangopayInstance({
    clientId: 'your-client-id',
    clientApiKey: 'your-api-key',
  })

  let myTransfer = {
    Id: 'xfer_m_01HTF5T24CXR0MFHCPV0239S9S',
  }

  let myRefund = {
    AuthorId: 'user_m_01HQK25M6KVHKDV0S36JY9NRKR',
    Tag: 'Created using Mangopay Node.js SDK',
  }

  const createRefund = async (transferId, refund) => {
    return await mangopay.Transfers.createRefund(transferId, refund)
      .then((response) => {
        console.info(response)
        return response
      })
      .catch((err) => {
        console.log(err)
        return false
      })
  }

  createRefund(myTransfer.Id, myRefund)
  ```

  ```ruby Ruby theme={null}
  require 'mangopay'

  MangoPay.configure do |client|
      client.preproduction = true
      client.client_id = 'your-client-id'
      client.client_apiKey = 'your-api-key'
      client.log_file = File.join(Dir.pwd, 'mangopay.log')
  end

  def createTransferRefund(transferId, refundObject)
      begin
          response = MangoPay::Transfer.refund(transferId, refundObject)
          puts response
          return response
      rescue MangoPay::ResponseError => error
          puts "Failed to create Refund: #{error.message}"
          puts "Error details: #{error.details}"
          return false
      end
  end

  myTransfer = {
      Id: 'xfer_m_01HTF5T24CXR0MFHCPV0239S9S'
    }

  myRefund = {
      AuthorId: 'user_m_01HQK25M6KVHKDV0S36JY9NRKR',
      Tag: 'Created with Mangopay Ruby SDK'
    }
  ```

  ```python Python  theme={null}
  from pprint import pprint
  import mangopay

  mangopay.client_id='your-client-id'
  mangopay.apikey='your-api-key'

  from mangopay.api import APIRequest
  handler = APIRequest(sandbox=True)

  from mangopay.resources import NaturalUser, TransferRefund, Transfer

  natural_user = NaturalUser.get('user_m_01HQK25M6KVHKDV0S36JY9NRKR')

  user_transfer = Transfer.get('xfer_m_01HTF5T24CXR0MFHCPV0239S9S')

  transfer_refund = TransferRefund(
      author = natural_user,
      transfer = user_transfer
  )

  create_transfer_refund = transfer_refund.save()

  pprint(create_transfer_refund)  
  ```
</CodeGroup>

### 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](/api-reference/refunds/create-refund-transfer)

<CodeGroup>
  ```json REST theme={null}
  {
      "Tag":"Created using Mangopay API Postman Collection",
      "AuthorId":"user_m_01HQK25M6KVHKDV0S36JY9NRKR",
      "DebitedFunds":{
          "Currency":"EUR",
          "Amount":100
      },
      "Fees":{
          "Currency":"EUR",
          "Amount":-14
      }
  }
  ```

  ```php PHP  theme={null}
  <?php

  require_once 'vendor/autoload.php';

  use MangoPay\MangoPayApi;
  use MangoPay\Libraries\ResponseException as MGPResponseException;
  use MangoPay\Libraries\Exception as MGPException;
  use MangoPay\Money;

  $api = new MangoPayApi();

  $api->Config->ClientId = 'your-client-id';
  $api->Config->ClientPassword = 'your-api-key';
  $api->Config->TemporaryFolder = 'tmp/';


  try {
      $transferId = 'xfer_m_01HT2NH7EAT7VVAWCZ7K8ET790';

      $refund = new \MangoPay\Refund();
      $refund->AuthorId = 'user_m_01HQK25M6KVHKDV0S36JY9NRKR';

      $refund->DebitedFunds = new Money();
      $refund->DebitedFunds->Amount = 100;
      $refund->DebitedFunds->Currency = 'EUR';

      $refund->Fees = new Money();
      $refund->Fees->Amount = -14;
      $refund->Fees->Currency = 'EUR';

      $refund->Tag = 'Created using the Mangopay PHP SDK';
      
      $response = $api->PayIns->CreateRefund($transferId, $refund);

      print_r($response);
  } catch(MGPResponseException $e) {
      print_r($e);
  } catch(MGPException $e) {
      print_r($e);
  }
  ```
</CodeGroup>

## 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 <a href="/webhooks">event type</a> for webhook notifications:

* TRANSFER\_REFUND\_SUCCEEDED

<Note>
  **Note - Prerequisites for pay-in refund**

  Refunding a pay-in is only possible if the initial transaction is in `SUCCEEDED` status, has not been disputed, and you're attempting the refund within the time window allowed, which differs depending on the payment method. Read more about [pay-in refund prerequisites](/guides/refunds#prerequisites) →
</Note>

### 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](/api-reference/refunds/create-refund-payin)

<CodeGroup>
  ```json REST theme={null}
  {
      "Tag":"Created using Mangopay API Postman Collection",
      "AuthorId":"user_m_01HQK25M6KVHKDV0S36JY9NRKR"
  }
  ```

  ```php PHP theme={null}
  <?php

  require_once 'vendor/autoload.php';

  use MangoPay\MangoPayApi;
  use MangoPay\Libraries\ResponseException as MGPResponseException;
  use MangoPay\Libraries\Exception as MGPException;
  use MangoPay\Money;

  $api = new MangoPayApi();

  $api->Config->ClientId = 'your-client-id';
  $api->Config->ClientPassword = 'your-api-key';
  $api->Config->TemporaryFolder = 'tmp/';

  try {
      $payInId = 'payin_m_01HT2DBS02XJBNQER4TG12EG76';

      $refund = new \MangoPay\Refund();
      $refund->AuthorId = 'user_m_01HQK25M6KVHKDV0S36JY9NRKR';

      $refund->DebitedFunds = new \MangoPay\Money();
      $refund->DebitedFunds->Amount = 1000;
      $refund->DebitedFunds->Currency = 'EUR';

      $refund->Fees = new \MangoPay\Money();
      $refund->Fees->Amount = 0;
      $refund->Fees->Currency = 'EUR';

      $refund->Tag = 'Created using the Mangopay PHP SDK';
      
      $response = $api->PayIns->CreateRefund($payInId, $refund);

      print_r($response);
  } catch(MGPResponseException $e) {
      print_r($e);
  } catch(MGPException $e) {
      print_r($e);
  }
  ```
</CodeGroup>

### 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](/api-reference/refunds/create-refund-payin)

<CodeGroup>
  ```json REST theme={null}
  {
      "Tag":"Created using Mangopay API Postman Collection",
      "AuthorId":"user_m_01HQK25M6KVHKDV0S36JY9NRKR", 
      "DebitedFunds": {
          "Currency":"EUR",
          "Amount":1400
      },
      "Fees":{
          "Currency":"EUR",
          "Amount":-14
      }
  }
  ```

  ```php PHP  theme={null}
  <?php

  require_once 'vendor/autoload.php';

  use MangoPay\MangoPayApi;
  use MangoPay\Libraries\ResponseException as MGPResponseException;
  use MangoPay\Libraries\Exception as MGPException;
  use MangoPay\Money;

  $api = new MangoPayApi();

  $api->Config->ClientId = 'your-client-id';
  $api->Config->ClientPassword = 'your-api-key';
  $api->Config->TemporaryFolder = 'tmp/';

  try {
      $payInId = 'payin_m_01HT2NAH2PF1G00WE5C5CYGS0C';

      $refund = new \MangoPay\Refund();
      $refund->AuthorId = 'user_m_01HQK25M6KVHKDV0S36JY9NRKR';

      $refund->DebitedFunds = new Money();
      $refund->DebitedFunds->Amount = 100;
      $refund->DebitedFunds->Currency = 'EUR';

      $refund->Fees = new Money();
      $refund->Fees->Amount = -14;
      $refund->Fees->Currency = 'EUR';

      $refund->Tag = 'Created using the Mangopay PHP SDK';
      
      $response = $api->PayIns->CreateRefund($payInId, $refund);

      print_r($response);
  } catch(MGPResponseException $e) {
      print_r($e);
  } catch(MGPException $e) {
      print_r($e);
  }
  ```
</CodeGroup>

<Note>
  **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.
</Note>

## Related resources

<CardGroup col={2}>
  <Card title="Guide" href="/guides/refunds">Learn more about refunds</Card>

  <Card title="Endpoint" href="/api-reference/refunds/refund-object">The Refund object</Card>
</CardGroup>