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

# Create an Intent Refund

POST https://api.sandbox.mangopay.com/v3.0/{ClientId}/payins/intents/{IntentId}/refunds
Content-Type: application/json

Declare the full or partial refund of a payment processed by a third-party PSP, represented by an Intent Refund. 

Reference: https://docs.mangopay.com/api-reference/intents/create-intent-refund

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token. If your platform is using a [proxy](/guides/sca/proxy-management) to take SCA-triggering action on behalf of users, you also need to integrate [mTLS authentication](/guides/sca/platform) and use the `api-mtls` base URL.

## Servers

- `https://api.sandbox.mangopay.com` (Sandbox, default)
- `https://api.mangopay.com` (Production)
- `https://api-mtls.sandbox.mangopay.com` (mTLS Sandbox)
- `https://api-mtls.mangopay.com` (mTLS Production)

## Request

### Path parameters

- `ClientId` (string, required) — Platform's API account identifier, associated with the API key.
- `IntentId` (string, required) — The unique identifier of the Intent.

### Body (application/json)

This endpoint expects a CreateAnIntentRefundRequest.

- `ExternalData` (ExternalProcessingDateExternalProviderReferenceExternalMerchantReference2, optional) — Information about the transaction authorization processed by the third-party PSP.
- `Amount` (integer, optional) — 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.
- `Currency` (string, optional) — The currency of the intent.
- `PlatformFeesAmount` (integer, optional) — 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 `PlatformFeesAmount` value must the sum of all line item `Seller.FeesAmount` values.
- `LineItems` (list of CreateAnIntentRefundRequestLineItemsItems, optional) — Information about the amount refunded for each line item, required for a partial refund.
- `Tag` (string, optional) — Max. length: 255 characters Custom data that you can add to this object, such as unique identifiers in your system. To store multiple values, you can serialize them into a single string, for example a JSON object: `"{\"id_1\":AB123,\"id_2\":DE456}"`.

## Response

### 200

Success

- `Id` (string, optional) — The unique identifier of the intent.
- `Amount` (integer, optional) — The full amount authorized in the Intent, which must equal the sum of the total amounts of all `LineItems`.
- `AvailableAmountToSplit` (integer, optional) — The remaining amount of the Intent that can be split and transferred to the sellers' wallets.
- `UnfundedAmount` (integer, optional) — The amount needing to be settled to the Platform's technical wallet before the Intent Splits can be executed.
- `Currency` (string, optional) — The currency of the intent.
- `PlatformFeesAmount` (integer, optional) — 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 `PlatformFeesAmount` value must the sum of all line item `Seller.FeesAmount` values.
- `Status` (string, optional) — 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.
- `NextActions` (string, optional) — The possible next actions on the intent.
- `ExternalData` (ExternalProcessingDateExternalProviderReferenceExternalMerchantReference, optional) — Information about the transaction authorization processed by the third-party PSP.
- `Buyer` (BuyerId, optional) — Information about the buyer.
- `LineItems` (list of IdTotalLineItemAmountCapturedAmount, optional) — Information about the line items included in the intent action.
- `CreationDate` (integer, optional) — Unix timestamp (UTC) of the date and time the object was created.
- `ExecutionDate` (integer, optional) — Unix timestamp (UTC) of the date and time the Intent moved to `AUTHORIZED`.
- `Refund` (Id_IntentRefund, optional) — Information about the Refund.

## Types

### ExternalProcessingDateExternalProviderReferenceExternalMerchantReference2

Information about the transaction authorization processed by the third-party PSP.

- `ExternalProcessingDate` (integer, required) — The date at which the transaction authorization was created.
- `ExternalProviderReference` (string, required) — The unique identifier of the transaction at the provider level.
- `ExternalProviderName` (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.
- `ExternalMerchantReference` (string, optional) — The unique identifier of the transaction at the merchant level.
- `ExternalProviderPaymentMethod` (string, optional) — One of the [supported payment methods](/api-reference/echo/supported-payment-methods) used to process the transaction.

### CreateAnIntentRefundRequestLineItemsItems

- `Id` (string, required) — The unique identifier of the line item in Mangopay ecosystem.
- `Amount` (integer, required) — The amount of the refund. The sum of the Refund's `LineItems.Amount` values must equal the `Amount` of the Refund.

### ExternalProcessingDateExternalProviderReferenceExternalMerchantReference

Information about the transaction authorization processed by the third-party PSP.

- `ExternalProcessingDate` (integer, optional) — The date at which the transaction authorization was created.
- `ExternalProviderReference` (string, optional) — The unique identifier of the transaction at the provider level.
- `ExternalMerchantReference` (string, optional) — The unique identifier of the transaction at the merchant level.
- `ExternalProviderName` (string, optional) — 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.
- `ExternalProviderPaymentMethod` (string, optional) — One of the [supported payment methods](/api-reference/echo/supported-payment-methods) used to process the transaction.

### BuyerId

Information about the buyer.

- `Id` (string, optional) — If it exists, the unique identifier of the Mangopay user making the payment via the third-party PSP. Must be a valid Mangopay `UserId`.

### IdTotalLineItemAmountCapturedAmount

- `Id` (string, optional) — The unique identifier of the line item in Mangopay's ecosystem.
- `TotalLineItemAmount` (integer, optional) — The total amount of the line item calculated as ((`UnitAmount` x `Quantity`) - `DiscountAmount`).
- `CapturedAmount` (integer, optional) — The item total `CAPTURED` amount
- `RefundedAmount` (integer, optional) — The item total `REFUNDED` amount
- `DisputedAmount` (integer, optional) — The item total `DISPUTED` amount.
- `SplitAmount` (integer, optional) — The item total `COMPLETED` amount.
- `UnfundedSellerAmount` (integer, optional) — The amount needing to be settled to the Platform's technical wallet before the Intent Splits can be executed for this seller.

### Id_IntentRefund

Information about the Refund.

- `Id` (string, optional) — The unique identifier of the Refund.

## Examples

### Full refund

**Request**

```json
{
  "body": {
    "ExternalData": {
      "ExternalMerchantReference": "order-33419af2-e770-43b8-82ac-512963313811",
      "ExternalProcessingDate": 1769431976,
      "ExternalProviderName": "Stripe",
      "ExternalProviderPaymentMethod": "MASTERCARD",
      "ExternalProviderReference": "refund-stripe-23bdabed-7ba8-488e-822a-ba7d8c8da0d1"
    },
    "Tag": "Refund tag"
  }
}
```

**Response**

```json
{
  "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,
      "UnfundedSellerAmount": 0,
      "CancelledAmount": 0
    },
    {
      "Id": "int_li_019bfa5d-33ae-723e-b257-ce01863b3ce1",
      "TotalLineItemAmount": 10000,
      "CapturedAmount": 10000,
      "RefundedAmount": 10000,
      "DisputedAmount": 0,
      "SplitAmount": 0,
      "UnfundedSellerAmount": 0,
      "CancelledAmount": 0
    },
    {
      "Id": "int_li_019bfa5d-33ae-723e-b257-ce01863b3ce0",
      "TotalLineItemAmount": 10000,
      "CapturedAmount": 10000,
      "RefundedAmount": 10000,
      "DisputedAmount": 0,
      "SplitAmount": 0,
      "UnfundedSellerAmount": 0,
      "CancelledAmount": 0
    },
    {
      "Id": "int_li_019bfa5d-33ae-723e-b257-ce01863b3ce1",
      "TotalLineItemAmount": 10000,
      "CapturedAmount": 10000,
      "RefundedAmount": 10000,
      "DisputedAmount": 0,
      "SplitAmount": 0,
      "UnfundedSellerAmount": 0,
      "CancelledAmount": 0
    }
  ],
  "CreationDate": 1769431970,
  "ExecutionDate": 1769431976,
  "Refund": {
    "Id": "int_refund_019bfa5d-4ad4-79b2-8dcf-5738147affeb"
  }
}
```

### Partial refund

**Request**

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

**Response**

```json
{
  "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,
      "UnfundedSellerAmount": 0,
      "CancelledAmount": 0
    },
    {
      "Id": "int_li_019bfa63-90ae-762a-ad52-7f6284ceb9bd",
      "TotalLineItemAmount": 10000,
      "CapturedAmount": 10000,
      "RefundedAmount": 5000,
      "DisputedAmount": 0,
      "SplitAmount": 0,
      "UnfundedSellerAmount": 0,
      "CancelledAmount": 0
    },
    {
      "Id": "int_li_019bfa63-90ae-762a-ad52-7f6284ceb9bc",
      "TotalLineItemAmount": 10000,
      "CapturedAmount": 10000,
      "RefundedAmount": 5000,
      "DisputedAmount": 0,
      "SplitAmount": 0,
      "UnfundedSellerAmount": 0,
      "CancelledAmount": 0
    },
    {
      "Id": "int_li_019bfa63-90ae-762a-ad52-7f6284ceb9bd",
      "TotalLineItemAmount": 10000,
      "CapturedAmount": 10000,
      "RefundedAmount": 5000,
      "DisputedAmount": 0,
      "SplitAmount": 0,
      "UnfundedSellerAmount": 0,
      "CancelledAmount": 0
    }
  ],
  "CreationDate": 1769432387,
  "ExecutionDate": 1769432390,
  "Refund": {
    "Id": "int_refund_019bfa63-9d22-76fe-afb1-c561008f4e93"
  }
}
```