> ## 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 an Intent Refund

> Declare the full or partial refund of a payment processed by a third-party PSP

This endpoint allows you to declare that a captured Intent was subject to a refund, in full or in part.

### Path parameters

<ParamField path="IntentId" type="string" required>
  The unique identifier of the Intent.
</ParamField>

### Body parameters

<Tabs>
  <Tab title="Full refund">
    The full `Amount` of the intent is refunded (all line items) but the `ExternalData` of the third-party refund must be provided.

    <ParamField body="ExternalData" type="object" required>
      Information about the refund processed by the third-party PSP.

      <Expandable>
        <ParamField body="ExternalProcessingDate" type="Unix timestamp" required>
          The date at which the capture was created.
        </ParamField>

        <ParamField body="ExternalProviderReference" type="string" required>
          The unique identifier of the capture at the provider level.
        </ParamField>

        <ParamField body="ExternalMerchantReference" type="string">
          The unique identifier of the capture at the merchant level.
        </ParamField>

        <ParamField body="ExternalProviderName" type="string" required>
          The [supported third-party PSP](/api-reference/echo/supported-providers) processing the transaction.

          **Note:** The uppercase value is expected. The API returns the sentence-case value.
        </ParamField>

        <ParamField body="ExternalProviderPaymentMethod" type="string">
          One of the [supported payment methods](/api-reference/echo/supported-payment-methods) used to process the capture.
        </ParamField>
      </Expandable>
    </ParamField>
  </Tab>

  <Tab title="Partial refund">
    Part of the original Intent `Amount` is refunded from one or more line items in a third-party refund (corresponding to the `ExternalData`). Any amount can be refunded from any line item(s). In this call, the Refund `Amount` must equal the sum of the `LineItems.Amount` values sent.

    <ParamField body="Amount" type="integer" required>
      The amount of the Refund, required for a partial refund. The Refund `Amount` must equal the sum of the `Amount` values refunded for all line items.
    </ParamField>

    <ParamField body="Currency" type="integer">
      The currency of the intent.
    </ParamField>

    <ParamField body="PlatformFees" type="integer">
      The amount of fees to be diverted to the platform's Fees Wallet when the Intent is split. This value can be overridden when the Split is created.

      The `PlatformFees` value must the sum of all line item `Seller.FeesAmount` values.
    </ParamField>

    <ParamField body="ExternalData" type="object" required>
      Information about the refund processed by the third-party PSP.

      <Expandable>
        <ParamField body="ExternalProcessingDate" type="Unix timestamp" required>
          The date at which the capture was created.
        </ParamField>

        <ParamField body="ExternalProviderReference" type="string" required>
          The unique identifier of the capture at the provider level.
        </ParamField>

        <ParamField body="ExternalMerchantReference" type="string">
          The unique identifier of the capture at the merchant level.
        </ParamField>

        <ParamField body="ExternalProviderName" type="string" required>
          The [supported third-party PSP](/api-reference/echo/supported-providers) processing the transaction.

          **Note:** The uppercase value is expected. The API returns the sentence-case value.
        </ParamField>

        <ParamField body="ExternalProviderPaymentMethod" type="string">
          One of the [supported payment methods](/api-reference/echo/supported-payment-methods) used to process the capture.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="LineItems" type="array (object)" required>
      Information about the amount refunded for each line item, required for a partial refund.

      <Expandable defaultOpen>
        <ParamField body="Id" type="string" required>
          The unique identifier of the line item in Mangopay ecosystem.
        </ParamField>

        <ParamField body="Amount" type="integer" required>
          The amount of the refund. The sum of the Refund's `LineItems.Amount` values must equal the `Amount` of the Refund.
        </ParamField>
      </Expandable>
    </ParamField>
  </Tab>
</Tabs>

### Responses

<AccordionGroup>
  <Accordion title="200 - Response parameters">
    <ResponseField name="Id" type="string">
      The unique identifier of the intent.
    </ResponseField>

    <ResponseField name="Amount" type="integer">
      The full amount authorized in the Intent, which must equal the sum of the total amounts of all `LineItems`.
    </ResponseField>

    <ResponseField name="AvailableAmountToSplit" type="integer">
      The remaining amount of the Intent that can be split and transferred to the sellers' wallets.
    </ResponseField>

    <ResponseField name="UnfundedAmount" type="integer">
      The amount needing to be settled to the Platform's escrow wallet before the Intent Splits can be executed.
    </ResponseField>

    <ResponseField name="Currency" type="integer">
      The currency of the intent.
    </ResponseField>

    <ResponseField name="PlatformFees" type="integer">
      The amount of fees to be diverted to the platform's Fees Wallet when the Intent is split. This value can be overridden when the Split is created.

      The `PlatformFees` value must the sum of all line item `Seller.FeesAmount` values.
    </ResponseField>

    <ResponseField name="Status" type="string">
      The status of the Intent, as declared by the platform through Intent Captures, Refunds (and reversals), or Disputes (and decisions). Where partial actions occur, the top-level Intent `Status` may differ from the `Status` of Intent `LineItems`.

      Intent `Status` values:

      * `AUTHORIZED` – The Intent `Amount` was authorized for acquisition by the PSP and can be captured or canceled.
      * `PARTIALLY_CAPTURED` – Part of the Intent `Amount` from one or more `LineItems` was captured. The other parts are either still available for capture or cancel.
      * `CAPTURED` – All of the Intent `Amount` was captured. Part of it may have been subsequently refunded or disputed.
      * `CANCELLED` – All of the Intent `Amount` was canceled.
      * `REFUNDED` – All of the `CapturedAmount` of all `LineItems` was refunded.
      * `REFUND_REVERSED` – The refund could not be completed and the funds were returned to the platform.
      * `DISPUTED` – All of the `CapturedAmount` of all `LineItems` was disputed.
      * `DEFENDED` – The dispute is being defended by the platform.
      * `DISPUTED_WON` – The dispute was resolved in favor of the platform.
      * `DISPUTED_LOST` – The dispute was resolved against the platform.
    </ResponseField>

    <ResponseField name="NextActions" type="string">
      The possible next actions on the intent.
    </ResponseField>

    <ResponseField name="ExternalData" type="object">
      Information about the refund processed by the third-party PSP.

      <Expandable>
        <ResponseField name="ExternalProcessingDate" type="Unix timestamp">
          The date at which the refund was created.
        </ResponseField>

        <ResponseField name="ExternalProviderReference" type="string">
          The unique identifier of the refund at the provider level.
        </ResponseField>

        <ResponseField name="ExternalMerchantReference" type="string">
          The unique identifier of the refund at the merchant level.
        </ResponseField>

        <ResponseField name="ExternalProviderName" type="string">
          The [supported third-party PSP](/api-reference/echo/supported-providers) processing the transaction.

          **Note:** The uppercase value is expected. The API returns the sentence-case value.
        </ResponseField>

        <ResponseField name="ExternalProviderPaymentMethod" type="string">
          One of the [supported payment methods](/api-reference/echo/supported-payment-methods) used to process the refund.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="Buyer" type="object">
      Information about the buyer.

      <Expandable>
        <ResponseField name="Id" type="string">
          If it exists, the unique identifier of the Mangopay user making the payment via the third-party PSP. Must be a valid Mangopay `UserId`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="LineItems" type="array (object)">
      Information about the line items included in the intent action.

      <Expandable>
        <ResponseField name="Id" type="string">
          The unique identifier of the line item in Mangopay's ecosystem.
        </ResponseField>

        <ResponseField name="TotalLineItemAmount" type="integer">
          The total amount of the line item calculated as ((`UnitAmount` x `Quantity`) - `DiscountAmount`).
        </ResponseField>

        <ResponseField name="CapturedAmount" type="integer">
          The item total `CAPTURED` amount
        </ResponseField>

        <ResponseField name="RefundedAmount" type="integer">
          The item total `REFUNDED` amount
        </ResponseField>

        <ResponseField name="DisputedAmount" type="integer">
          The item total `DISPUTED` amount.
        </ResponseField>

        <ResponseField name="SplitAmount" type="integer">
          The item total `COMPLETED` amount.
        </ResponseField>

        <ResponseField name="UnfundedSellerAmount" type="integer">
          The amount needing to be settled to the Platform's escrow wallet before the Intent Splits can be executed for this seller.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="CreationDate" type="string">
      The date and time at which the Intent was created.
    </ResponseField>

    <ResponseField name="ExecutionDate" type="Unix timestamp">
      The date and time at which the Intent moved to `AUTHORIZED`.
    </ResponseField>

    <ResponseField name="Refund" type="object">
      Information about the Refund.

      <Expandable>
        <ResponseField name="Id" type="string">
          The unique identifier of the Refund.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Accordion>
</AccordionGroup>

<ResponseExample>
  ```json Full refund theme={null}
  {
      "Id": "int_019bfa5d-33a7-7cd5-9178-627425ff32ee",
      "Amount": 20000,
      "AvailableAmountToSplit": 0,
      "UnfundedAmount": 0,
      "Currency": "EUR",
      "PlatformFeesAmount": 0,
      "Status": "REFUNDED",
      "NextActions": "REVERSE_REFUND",
      "ExternalData": {
          "ExternalProcessingDate": 1769431976,
          "ExternalProviderReference": "refund-stripe-23bdabed-7ba8-488e-822a-ba7d8c8da0d1",
          "ExternalMerchantReference": "order-33419af2-e770-43b8-82ac-512963313811",
          "ExternalProviderName": "Stripe",
          "ExternalProviderPaymentMethod": "MASTERCARD"
      },
      "Buyer": {
          "Id": "user_m_01KF3087EDXEAK8VPD9DTMZW8N"
      },
      "LineItems": [
          {
              "Id": "int_li_019bfa5d-33ae-723e-b257-ce01863b3ce0",
              "TotalLineItemAmount": 10000,
              "CapturedAmount": 10000,
              "RefundedAmount": 10000,
              "DisputedAmount": 0,
              "SplitAmount": 0,
              "CancelledAmount": 0,
              "UnfundedSellerAmount": 0
          },
          {
              "Id": "int_li_019bfa5d-33ae-723e-b257-ce01863b3ce1",
              "TotalLineItemAmount": 10000,
              "CapturedAmount": 10000,
              "RefundedAmount": 10000,
              "DisputedAmount": 0,
              "SplitAmount": 0,
              "CancelledAmount": 0,
              "UnfundedSellerAmount": 0
          }
      ],
      "CreationDate": 1769431970,
      "ExecutionDate": 1769431976,
      "Refund": {
          "Id": "int_refund_019bfa5d-4ad4-79b2-8dcf-5738147affeb"
      }
  }
  ```

  ```json Partial refund theme={null}
  {
      "Id": "int_019bfa63-90ad-743b-b478-c0f950f6efb3",
      "Amount": 10000,
      "AvailableAmountToSplit": 10000,
      "UnfundedAmount": 0,
      "Currency": "EUR",
      "PlatformFeesAmount": 0,
      "Status": "CAPTURED",
      "NextActions": "REFUND, DISPUTE, REVERSE_REFUND",
      "ExternalData": {
          "ExternalProcessingDate": 1769432391,
          "ExternalProviderReference": "refund-stripe-3ce4ca75-4ce0-4a6c-8681-6ce02f056367",
          "ExternalMerchantReference": "refund-order-9724a65a-9d98-4ac3-8c8b-639e0c9ad21f",
          "ExternalProviderName": "Stripe",
          "ExternalProviderPaymentMethod": "MASTERCARD"
      },
      "Buyer": {
          "Id": "user_m_01KF3087EDXEAK8VPD9DTMZW8N"
      },
      "LineItems": [
          {
              "Id": "int_li_019bfa63-90ae-762a-ad52-7f6284ceb9bc",
              "TotalLineItemAmount": 10000,
              "CapturedAmount": 10000,
              "RefundedAmount": 5000,
              "DisputedAmount": 0,
              "SplitAmount": 0,
              "CancelledAmount": 0,
              "UnfundedSellerAmount": 0
          },
          {
              "Id": "int_li_019bfa63-90ae-762a-ad52-7f6284ceb9bd",
              "TotalLineItemAmount": 10000,
              "CapturedAmount": 10000,
              "RefundedAmount": 5000,
              "DisputedAmount": 0,
              "SplitAmount": 0,
              "CancelledAmount": 0,
              "UnfundedSellerAmount": 0
          }
      ],
      "CreationDate": 1769432387,
      "ExecutionDate": 1769432390,
      "Refund": {
          "Id": "int_refund_019bfa63-9d22-76fe-afb1-c561008f4e93"
      }
  }
  ```
</ResponseExample>

<RequestExample>
  ```json Full refund theme={null}
  {   
      "ExternalData": {
          "ExternalProcessingDate": 1769431976,
          "ExternalProviderReference": "refund-stripe-23bdabed-7ba8-488e-822a-ba7d8c8da0d1",
          "ExternalMerchantReference": "order-33419af2-e770-43b8-82ac-512963313811",
          "ExternalProviderName": "Stripe",
          "ExternalProviderPaymentMethod": "MASTERCARD"
      }
  }
  ```

  ```json Partial refund theme={null}
  {
      "Amount": 10000,
      "Currency": "EUR",
      "PlatformFeesAmount": 0,
      "ExternalData": {
          "ExternalProcessingDate": 1769432391,
          "ExternalProviderReference": "refund-stripe-3ce4ca75-4ce0-4a6c-8681-6ce02f056367",
          "ExternalMerchantReference": "refund-order-9724a65a-9d98-4ac3-8c8b-639e0c9ad21f",
          "ExternalProviderName": "Stripe",
          "ExternalProviderPaymentMethod": "MASTERCARD"
      },
      "LineItems": [
          {
              "Id": "int_li_019bfa63-90ae-762a-ad52-7f6284ceb9bc",
              "Amount": 5000
          },
          {
              "Id": "int_li_019bfa63-90ae-762a-ad52-7f6284ceb9bd",
              "Amount": 5000
          }
      ]
  }
  ```

  ```java Java theme={null}
  // idempotencyKey is null in this example
  api.getPayInApi().createPayInIntentRefund(intentId, refundToBeCreated, null);
  ```

  ```c# .NET theme={null}
   await Api.PayIns.CreatePayInIntentPartialRefundAsync(dto, intent.Id);
   await Api.PayIns.CreatePayInIntentFullRefundAsync(dto, intent.Id);
  ```

  ```javascript NodeJS theme={null}
   api.PayIns.createPayInIntentRefund(intent.Id, refundDto)
  ```

  ```php PHP theme={null}
  _api->PayIns->CreatePayInIntentRefund($intent->Id, $refundDto);
  ```

  ```py Python theme={null}
  PayInIntent.create_refund(intent.id, **dto)
  ```

  ```ruby Ruby theme={null}
  MangoPay::PayIn::PayInIntent::Refund.create(intent['Id'], dto)
  ```
</RequestExample>