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

# Create a Refund for a PayIn

The pay-in refund is a request to reimburse a pay-in and is supported for most payment methods. You can make partial refunds by providing a debited funds `Amount` value lower than the initial transaction amount.

<Note>
  **Note – Conditions for 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](/guides/payment-methods).
</Note>

[Read more about pay-in refunds](/guides/refunds#pay-in-refunds) **→**

### Path parameters

<ParamField path="PayInId" type="string" required>
  The unique identifier of the pay-in.
</ParamField>

### Body parameters

<ParamField body="Tag" type="string">
  Max. length: 255 characters

  Custom data that you can add to this object.\
  For transactions (pay-in, transfer, payout), you can use this parameter to identify corresponding information regarding the user, transaction, or payment methods on your platform.
</ParamField>

<ParamField body="AuthorId" type="string" required>
  The unique identifier of the user at the source of the initial transaction.
</ParamField>

<ParamField body="DebitedFunds" type="object">
  **Default value:** The amount and currency values of the debited funds of the initial transaction.

  Required if the `Fees` parameter is included in the call.

  Information about the debited funds. Debited funds:

  * Takes by default the amount and currency values of the initial transaction when left empty.
  * Must be entered manually to perform a partial refund.
  * Cannot exceed the initial transaction `CreditedFunds` value when entered manually. This also applies to the sum of debited funds when making multiple partial refunds.

  <Expandable title="properties">
    <ParamField body="Amount" type="integer" required>
      An amount of money in the smallest sub-division of the currency (e.g., EUR 12.60 would be represented as `1260` whereas JPY 12 would be represented as just `12`).
    </ParamField>

    <ParamField body="Currency" type="string" required>
      **Allowed values:** The three-letter <a href="/api-reference/overview/data-formats" target="_blank">ISO 4217 code</a> (EUR, GBP, etc.) of a <a href="/guides/currencies" target="_blank">supported currency</a> (depends on feature, contract, and activation settings).

      The currency of the debited funds.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="Fees" type="object">
  **Default value:** The amount and currency values of the fees of the initial transaction.

  Required if the `DebitedFunds` parameter is included in the call.

  Information about the fees. This value:

  * Should be preceded by a minus sign (-) to refund the fees, otherwise more fees will be taken.
  * Takes by default the amount and currency values of the fees of the initial transaction when left empty (preceded by a -).
  * Cannot exceed the initial transaction fees amount when entered manually. This also applies to the sum of the amount of the fees when making multiple partial refunds.

  <Expandable title="properties">
    <ParamField body="Amount" type="integer" required>
      An amount of money in the smallest sub-division of the currency (e.g., EUR 12.60 would be represented as `1260` whereas JPY 12 would be represented as just `12`).
    </ParamField>

    <ParamField body="Currency" type="string" required>
      **Allowed values:** The three-letter <a href="/api-reference/overview/data-formats" target="_blank">ISO 4217 code</a> (EUR, GBP, etc.) of a <a href="/guides/currencies" target="_blank">supported currency</a> (depends on feature, contract, and activation settings).

      The currency of the debited funds.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="StatementDescriptor" type="string">
  Max. length: 10 characters; only alphanumeric and spaces

  Custom description to appear on the user’s bank statement along with the platform name. Different banks may show more or less information. See the <a href="/bank-statements">Customizing bank statement references</a> article for details.

  **Note:** On refunds, the `StatementDescriptor` is only available for SEPA and BACS <a href="/api-reference/direct-debit-payins/create-direct-debit-payin">direct debit pay-ins</a> (no other payment methods nor transfers).
</ParamField>

### Responses

<AccordionGroup>
  <Accordion title="200">
    <ResponseField name="Id" type="string">
      Max length: 128 characters (see [data formats](/api-reference/overview/data-formats) for details)

      The unique identifier of the object.
    </ResponseField>

    <ResponseField name="Tag" type="string">
      Max. length: 255 characters

      Custom data that you can add to this object.\
      For transactions (pay-in, transfer, payout), you can use this parameter to identify corresponding information regarding the user, transaction, or payment methods on your platform.
    </ResponseField>

    <ResponseField name="CreationDate" type="Unix timestamp">
      The date and time at which the object was created.
    </ResponseField>

    <ResponseField name="AuthorId" type="string">
      The unique identifier of the user at the source of the initial transaction.
    </ResponseField>

    <ResponseField name="CreditedUserId" type="string">
      **Default value:** The unique identifier of the owner of the credited wallet.

      The unique identifier of the user whose wallet is credited.
    </ResponseField>

    <ResponseField name="DebitedFunds" type="object">
      **Default value:** The amount and currency values of the debited funds of the initial transaction.

      Information about the debited funds. Debited funds:

      * Takes by default the amount and currency values of the initial transaction when left empty.
      * Must be entered manually to perform a partial refund.
      * Cannot exceed the initial transaction `CreditedFunds` value when entered manually. This also applies to the sum of debited funds when making multiple partial refunds.

      <Expandable title="properties">
        <ResponseField name="Amount" type="integer">
          An amount of money in the smallest sub-division of the currency (e.g., EUR 12.60 would be represented as `1260` whereas JPY 12 would be represented as just `12`).
        </ResponseField>

        <ResponseField name="Currency" type="string">
          **Returned values:** The three-letter <a href="/api-reference/overview/data-formats" target="_blank">ISO 4217 code</a> (EUR, GBP, etc.) of a <a href="/guides/currencies" target="_blank">supported currency</a> (depends on feature, contract, and activation settings).

          The currency of the debited funds.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="CreditedFunds" type="object">
      Information about the funds being credited to the target of the transaction (`CreditedFunds` = `DebitedFunds` - `Fees`).

      <Expandable title="properties">
        <ResponseField name="Currency" type="string">
          **Returned values:** The three-letter <a href="/api-reference/overview/data-formats" target="_blank">ISO 4217 code</a> (EUR, GBP, etc.) of a <a href="/guides/currencies" target="_blank">supported currency</a> (depends on feature, contract, and activation settings).

          The currency of the debited funds.
        </ResponseField>

        <ResponseField name="Amount" type="integer">
          An amount of money in the smallest sub-division of the currency (e.g., EUR 12.60 would be represented as `1260` whereas JPY 12 would be represented as just `12`).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="Fees" type="object">
      **Default value:** The amount and currency values of the fees of the initial transaction.

      Information about the fees. This value:

      * Should be preceded by a minus sign (-) to refund the fees, otherwise more fees will be taken.
      * Takes by default the amount and currency values of the fees of the initial transaction when left empty (preceded by a -).
      * Cannot exceed the initial transaction fees amount when entered manually. This also applies to the sum of the amount of the fees when making multiple partial refunds.

      <Expandable title="properties">
        <ResponseField name="Amount" type="integer">
          An amount of money in the smallest sub-division of the currency (e.g., EUR 12.60 would be represented as `1260` whereas JPY 12 would be represented as just `12`).
        </ResponseField>

        <ResponseField name="Currency" type="string">
          **Returned values:** The three-letter <a href="/api-reference/overview/data-formats" target="_blank">ISO 4217 code</a> (EUR, GBP, etc.) of a <a href="/guides/currencies" target="_blank">supported currency</a> (depends on feature, contract, and activation settings).

          The currency of the debited funds.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="Status" type="string">
      **Returned values:** `CREATED`, `SUCCEEDED`, `FAILED`

      The status of the transaction.
    </ResponseField>

    <ResponseField name="ResultCode" type="string">
      The code indicating the result of the operation. This information is mostly used to <a href="/errors/codes">handle errors</a> or for filtering purposes.
    </ResponseField>

    <ResponseField name="ResultMessage" type="string">
      The explanation of the result code.
    </ResponseField>

    <ResponseField name="ExecutionDate" type="Unix timestamp">
      The date and time at which the status changed to `SUCCEEDED`, indicating that the transaction occurred. The statuses `CREATED` and `FAILED` return an `ExecutionDate` of `null`.
    </ResponseField>

    <ResponseField name="Type" type="string">
      **Returned values:** `PAYIN`, `TRANSFER`, `CONVERSION`, `PAYOUT`

      The type of the transaction.
    </ResponseField>

    <ResponseField name="Nature" type="string">
      **Returned values:** `REGULAR`, `REPUDIATION`, `REFUND`, `SETTLEMENT`

      The nature of the transaction, providing more information about the context in which the transaction occurred:

      * `REGULAR` – Relative to most of the transactions (pay-ins, payouts, and transfers) in a usual workflow.
      * `REPUDIATION` – Automatic withdrawal of funds from the platform’s repudiation wallet as part of the dispute process (when the user has requested a chargeback).
      * `REFUND` – Reimbursement of a transaction to the user (pay-in refund), to a wallet (transfer refund), or of a payout (payout refund, only initiated by Mangopay).
      * `SETTLEMENT` – Transfer made to the repudiation wallet by the platform to settle a lost dispute.
    </ResponseField>

    <ResponseField name="InitialTransactionId" type="string">
      The unique identifier of the initial transaction being refunded.
    </ResponseField>

    <ResponseField name="InitialTransactionType" type="string">
      **Returned values:** `PAYIN`, `TRANSFER`, `PAYOUT`

      The type of the initial transaction being refunded.
    </ResponseField>

    <ResponseField name="InitialTransactionNature" type="string">
      **Returned values:** `REGULAR`, `REPUDIATION`, `REFUND`, `SETTLEMENT`

      The nature of the initial transaction being refunded, providing more information about the context in which the transaction occurred:

      * REGULAR – Relative to most of the transactions (pay-ins, payouts, and transfers) in a usual workflow.
      * REPUDIATION – Automatic withdrawal of funds from the platform’s repudiation wallet as part of the dispute process (when the user requested a chargeback).
      * REFUND – Reimbursement of a transaction to the user (pay-in refund), to a wallet (transfer refund), or of a payout (payout refund, only initiated by Mangopay).
      * SETTLEMENT – Transfer made to the repudiation wallet by the platform to settle the credit from a repudiation following a lost dispute.
    </ResponseField>

    <ResponseField name="DebitedWalletId" type="string">
      The unique identifier of the debited wallet.
    </ResponseField>

    <ResponseField name="CreditedWalletId" type="string">
      The unique identifier of the credited wallet.
    </ResponseField>

    <ResponseField name="RefundReason" type="object">
      Information about the reasons for the refund.

      <Expandable title="properties">
        <ResponseField name="RefundReasonMessage" type="string">
          Max. length: 255 characters

          Message explaining the reason for the refusal.
        </ResponseField>

        <ResponseField name="RefundReasonType" type="string">
          **Returned values:** `INITIALIZED_BY_CLIENT`, `BANKACCOUNT_INCORRECT`, `OWNER_DO_NOT_MATCH_BANKACCOUNT`, `BANKACCOUNT_HAS_BEEN_CLOSED`, `WITHDRAWAL_IMPOSSIBLE_ON_SAVINGS_ACCOUNTS`, `OTHER`

          The type of reason for the refund.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="StatementDescriptor" type="string">
      Max. length: 10 characters; only alphanumeric and spaces

      Custom description to appear on the user’s bank statement along with the platform name. Different banks may show more or less information. See the <a href="/bank-statements">Customizing bank statement references</a> article for details.

      **Note:** On refunds, the `StatementDescriptor` is only available for SEPA and BACS <a href="/api-reference/direct-debit-payins/create-direct-debit-payin">direct debit pay-ins</a> (no other payment methods nor transfers).
    </ResponseField>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="400 - Fees parameter must be defined">
    ```json theme={null}
    {
        "Message":"One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
        "Type":"param_error",
        "Id":"9712a945-c96a-4e70-b3de-06529534a9de#1667200884",
        "Date":1667200885.0,
        "errors":{
            "Fees":"if DebitedFunds are defined, Fees must be defined"
        }
    }  
    ```
  </Accordion>

  <Accordion title="400 - Incorrect AuthorId">
    ```json theme={null}
    {
        "Message":"One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
        "Type":"param_error",
        "Id":"a2af2b8b-506c-4b5b-b607-7441a58c0a66#1667201846",
        "Date":1667201847.0,
        "errors":{
            "AuthorId":"Author of the refund is not the author of the initial payin"
        }
    }  
    ```
  </Accordion>

  <Accordion title="400 - DebitedFunds exceed initial CreditedFunds">
    ```json theme={null}
    {
        "Message":"One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
        "Type":"param_error",
        "Id":"5eebf638-efd9-4a02-9854-f476c16c0262#1667809509",
        "Date":1667809510.0,
        "errors":{
            "DebitedFunds":"DebitedFunds cannot be superior the CreditedFunds of the initial PayIn"
        }
    }  
    ```
  </Accordion>

  <Accordion title="400 - Initial transaction must be SUCCEEDED">
    ```json theme={null}
    {
        "Message": "The original transaction must have a SUCCEEDED Status to be refunded",
        "Id": "cd53bb5b-21f6-499e-bcc5-d3520c0d1eb7",
        "Date": 1759504170,
        "Type": "original_transaction_must_be_succeeded",
        "Errors": {}
    }
    ```
  </Accordion>

  <Accordion title="400 - The transaction is already disputed">
    ```json theme={null}
    {
        "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
        "Type": "param_error",
        "Id": "34989f04-25db-4246-a926-6fadbf1d53e1#1673521386",
        "Date": 1673521387.0,
        "errors": {
            "DebitedFunds": "Due to repudiations against this transaction, you can not refund this amount"
        }
    }  
    ```
  </Accordion>

  <Accordion title="404 - PayInId not found, including if archived after 13 months">
    A 404 is returned if the initial transaction has been archived after 13 months and no longer available via the API (see [data availability](/api-reference/overview/data-availability-periods) for details). Note that for many payment methods, the period during which a refund is allowed is shorter than 13 months.

    ```json theme={null}
    {
        "Message": "The ressource does not exist",
        "Type": "ressource_not_found",
        "Id": "4ce07ad6-8d30-4dc1-82c1-fe4596ae67d4#1747900976",
        "Date": 1747900977,
        "errors": {
            "ResourceNotFound": "Cannot found the resource PayIn with the id=payin_m_01HPF0PN7SCWZ6TFPRHPBMXSAG "
        }
    }
    ```
  </Accordion>
</AccordionGroup>

<ResponseExample>
  ```json 200 - Direct debit pay-in refund with StatementDescriptor theme={null}
  {
      "Id": "refund_m_01HW8A130S4SBVDZ70V809SS2X",
      "Tag": "Created using Mangopay API Postman Collection",
      "CreationDate": 1713970908,
      "AuthorId": "204071581",
      "CreditedUserId": null,
      "DebitedFunds": {
          "Currency": "EUR",
          "Amount": 2500
      },
      "CreditedFunds": {
          "Currency": "EUR",
          "Amount": 2750
      },
      "Fees": {
          "Currency": "EUR",
          "Amount": -250
      },
      "Status": "SUCCEEDED",
      "ResultCode": "000000",
      "ResultMessage": "Success",
      "ExecutionDate": 1713970908,
      "Type": "PAYOUT",
      "Nature": "REFUND",
      "InitialTransactionId": "204844475",
      "InitialTransactionType": "PAYIN",
      "InitialTransactionNature": "REGULAR",
      "DebitedWalletId": "204844308",
      "CreditedWalletId": null,
      "RefundReason": {
          "RefundReasonMessage": null,
          "RefundReasonType": "INITIALIZED_BY_CLIENT"
      },
      "StatementDescriptor": "Example123"
  }
  ```
</ResponseExample>

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

  ```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 {
      $payinId = '199478487';

      $refund = new \MangoPay\Refund();
      $refund->AuthorId = '146476890';
      $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 Mangopay PHP SDK';
      
      $response = $api->PayIns->CreateRefund($payinId, $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 myPayIn = {
    Id: '192870720',
  }

  let myRefund = {
    AuthorId: '192822811',
    Tag: 'Created with Mangopay Nodejs SDK',
    DebitedFunds: {
      Currency: 'EUR',
      Amount: 250,
    },
    Fees: {
      Currency: 'EUR',
      Amount: 0,
    },
  }

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

  createPayInRefund(myPayIn.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 createPayInRefund(payInId, refundObject)
      begin
          response = MangoPay::PayIn.refund(payInId, 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

  myPayIn = {
      Id: '193930143'
  }

  myRefund = {
      AuthorId: '193930097',
      Tag: 'Created with Mangopay Ruby SDK',
      DebitedFunds: {
        Currency: 'EUR',
        Amount: 1188
      },
      Fees: {
        Currency: 'EUR',
        Amount: -12
      }
    }

  createPayInRefund(myPayIn[:Id], myRefund)  
  ```

  ```java Java theme={null}
  import com.google.gson.Gson;
  import com.google.gson.GsonBuilder;
  import com.mangopay.MangoPayApi;
  import com.mangopay.core.Money;
  import com.mangopay.core.enumerations.CurrencyIso;
  import com.mangopay.entities.Refund;

  public class CreatePayinRefund {
      public static void main(String[] args) throws Exception {
          MangoPayApi mangopay = new MangoPayApi();
          mangopay.getConfig().setClientId("your-client-id");
          mangopay.getConfig().setClientPassword("your-api-key");

          var authorId = "user_m_01HT2NFK7Z2BRQNGNHMY30VVTT";
          var payInId = "payin_m_01J28XNRJXNQKEQ3GK3WBVQK8B";

          Refund refund = new Refund();
          refund.setAuthorId(authorId);
          refund.setDebitedFunds(new Money(CurrencyIso.EUR, 200));
          refund.setFees(new Money(CurrencyIso.EUR, 0));
          refund.setTag("Created using the Mangopay Java SDK");

          Refund createPayinRefund = mangopay.getPayInApi().createRefund(payInId, refund);

          Gson prettyPrint = new GsonBuilder().setPrettyPrinting().create();
          String prettyJson = prettyPrint.toJson(createPayinRefund);

          System.out.println(prettyJson);
      }
  }
  ```

  ```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, PayInRefund, DirectDebitDirectPayIn
  from mangopay.utils import Money

  natural_user = NaturalUser.get('213753890')

  natural_user_wallet_id = '213754077'

  user_payin = DirectDebitDirectPayIn.get('214568733')

  payin_refund = PayInRefund(
      author = natural_user,
      payin = user_payin
  )

  create_payin_refund = payin_refund.save()

  pprint(create_payin_refund)  
  ```

  ```csharp .NET  theme={null}
  using MangoPay.SDK;
  using MangoPay.SDK.Core.Enumerations;
  using MangoPay.SDK.Entities;
  using MangoPay.SDK.Entities.POST;
  using Newtonsoft.Json;

  class Program
  {
      static async Task Main(string[] args)
      {
          MangoPayApi api = new MangoPayApi();

          api.Config.ClientId = "your-client-id";
          api.Config.ClientPassword = "your-api-key";

          var userId = "user_m_01J2TZ261WZNDM0ZDRWGDYA4GN";
          var payInId = "payin_m_01J3ZJ2SC199VC64SFTTZ71VPC";

          var refund = new RefundPayInPostDTO(userId, 
              new Money { Amount=0, Currency = CurrencyIso.EUR}, 
              new Money { Amount=1000, Currency = CurrencyIso.EUR} 
          );

          var createRefund = await api.PayIns.CreateRefundAsync(payInId, refund);

          string prettyPrint = JsonConvert.SerializeObject(createRefund, Formatting.Indented);
          Console.WriteLine(prettyPrint);
      }
  }
  ```
</RequestExample>