> 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-dispute/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 Dispute

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

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

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

## 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.
- `CaptureId` (string, required) — The unique identifier of the Capture being disputed.

### Body (application/json)

This endpoint expects a CreateAnIntentDisputeRequest.

- `ExternalData` (ExternalProcessingDateExternalProviderReferenceExternalMerchantReference2, required) — Information about the transaction authorization processed by the third-party PSP.
- `Amount` (integer, required) — The amount of the Dispute, required for a partial dispute. The Dispute `Amount` must equal the sum of the `Amount` values disputed for all line items.
- `LineItems` (list of CreateAnIntentDisputeRequestLineItemsItems, required) — Information about the amount disputed for each line item, required for a partial dispute.
- `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.
- `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`.
- `Dispute` (Id_IntentDispute, optional) — Information about the Dispute.

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

### CreateAnIntentDisputeRequestLineItemsItems

- `Id` (string, required) — The unique identifier of the line item in Mangopay ecosystem.

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

Information about the Dispute.

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

## Examples

### Full dispute

**Response**

```json
{
  "Id": "int_019c0e2f-8128-709d-8efc-dc930576997e",
  "Amount": 20000,
  "AvailableAmountToSplit": 10000,
  "UnfundedAmount": 0,
  "Currency": "EUR",
  "PlatformFeesAmount": 0,
  "Status": "CAPTURED",
  "NextActions": "REFUND, DISPUTE, DEFEND, WIN_DISPUTE, LOSE_DISPUTE",
  "ExternalData": {
    "ExternalProcessingDate": 1769764526,
    "ExternalProviderReference": "dispute-stripe-b9e93ae2-36bb-42b6-ad1d-9d34ac14defc",
    "ExternalMerchantReference": "dispute-order-a20938bc-2d5a-4eda-98b2-ff2c04a96f64",
    "ExternalProviderName": "Stripe",
    "ExternalProviderPaymentMethod": "MASTERCARD"
  },
  "Buyer": {
    "Id": "user_m_01KF3087EDXEAK8VPD9DTMZW8N"
  },
  "LineItems": [
    {
      "Id": "int_li_019c0e2f-8129-7016-b498-1a9fd0fb1621",
      "TotalLineItemAmount": 10000,
      "CapturedAmount": 10000,
      "RefundedAmount": 0,
      "DisputedAmount": 10000,
      "SplitAmount": 0,
      "UnfundedSellerAmount": 0,
      "CancelledAmount": 0
    },
    {
      "Id": "int_li_019c0e2f-8129-7016-b498-1a9fd0fb1622",
      "TotalLineItemAmount": 10000,
      "CapturedAmount": 10000,
      "RefundedAmount": 0,
      "DisputedAmount": 0,
      "SplitAmount": 0,
      "UnfundedSellerAmount": 0,
      "CancelledAmount": 0
    },
    {
      "Id": "int_li_019c0e2f-8129-7016-b498-1a9fd0fb1621",
      "TotalLineItemAmount": 10000,
      "CapturedAmount": 10000,
      "RefundedAmount": 0,
      "DisputedAmount": 10000,
      "SplitAmount": 0,
      "UnfundedSellerAmount": 0,
      "CancelledAmount": 0
    },
    {
      "Id": "int_li_019c0e2f-8129-7016-b498-1a9fd0fb1622",
      "TotalLineItemAmount": 10000,
      "CapturedAmount": 10000,
      "RefundedAmount": 0,
      "DisputedAmount": 0,
      "SplitAmount": 0,
      "UnfundedSellerAmount": 0,
      "CancelledAmount": 0
    }
  ],
  "CreationDate": 1769764520,
  "ExecutionDate": 1769764526,
  "Dispute": {
    "Id": "int_dispute_019c0e2f-980c-76ed-9bd5-c6c00617180c"
  }
}
```

### Partial dispute

**Request**

```json
{
  "body": {
    "Amount": 20000,
    "Currency": "EUR",
    "ExternalData": {
      "ExternalMerchantReference": "dispute-order-4d351ba0-3987-408c-b12b-8af412432144",
      "ExternalProcessingDate": 1769764498,
      "ExternalProviderName": "Stripe",
      "ExternalProviderPaymentMethod": "MASTERCARD",
      "ExternalProviderReference": "dispute-stripe-1d55ff5f-87d0-4825-a766-52177bbc0a73"
    },
    "LineItems": [
      {
        "Id": "int_li_019c0e2f-1bab-7443-901b-80d1baf20e46"
      },
      {
        "Id": "int_li_019c0e2f-1bab-7443-901b-80d1baf20e47"
      }
    ],
    "Tag": "Dispute tag"
  }
}
```

**Response**

```json
{
  "Id": "int_019c0e2f-1baa-73d9-9053-074ad2a50e79",
  "Amount": 20000,
  "AvailableAmountToSplit": 0,
  "UnfundedAmount": 0,
  "Currency": "EUR",
  "PlatformFeesAmount": 0,
  "Status": "DISPUTED",
  "NextActions": "DEFEND, WIN_DISPUTE, LOSE_DISPUTE",
  "ExternalData": {
    "ExternalProcessingDate": 1769764498,
    "ExternalProviderReference": "dispute-stripe-1d55ff5f-87d0-4825-a766-52177bbc0a73",
    "ExternalMerchantReference": "dispute-order-4d351ba0-3987-408c-b12b-8af412432144",
    "ExternalProviderName": "Stripe",
    "ExternalProviderPaymentMethod": "MASTERCARD"
  },
  "Buyer": {
    "Id": "user_m_01KF3087EDXEAK8VPD9DTMZW8N"
  },
  "LineItems": [
    {
      "Id": "int_li_019c0e2f-1bab-7443-901b-80d1baf20e46",
      "TotalLineItemAmount": 10000,
      "CapturedAmount": 10000,
      "RefundedAmount": 0,
      "DisputedAmount": 10000,
      "SplitAmount": 0,
      "UnfundedSellerAmount": 0,
      "CancelledAmount": 0
    },
    {
      "Id": "int_li_019c0e2f-1bab-7443-901b-80d1baf20e47",
      "TotalLineItemAmount": 10000,
      "CapturedAmount": 10000,
      "RefundedAmount": 0,
      "DisputedAmount": 10000,
      "SplitAmount": 0,
      "UnfundedSellerAmount": 0,
      "CancelledAmount": 0
    },
    {
      "Id": "int_li_019c0e2f-1bab-7443-901b-80d1baf20e46",
      "TotalLineItemAmount": 10000,
      "CapturedAmount": 10000,
      "RefundedAmount": 0,
      "DisputedAmount": 10000,
      "SplitAmount": 0,
      "UnfundedSellerAmount": 0,
      "CancelledAmount": 0
    },
    {
      "Id": "int_li_019c0e2f-1bab-7443-901b-80d1baf20e47",
      "TotalLineItemAmount": 10000,
      "CapturedAmount": 10000,
      "RefundedAmount": 0,
      "DisputedAmount": 10000,
      "SplitAmount": 0,
      "UnfundedSellerAmount": 0,
      "CancelledAmount": 0
    }
  ],
  "CreationDate": 1769764494,
  "ExecutionDate": 1769764498,
  "Dispute": {
    "Id": "int_dispute_019c0e2f-2c25-753e-8301-3ff93d541358"
  }
}
```