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

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

This endpoint allows you to declare that the Capture of an Intent was subject to a dispute, in full or in part.

### Path parameters

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

<ParamField path="CaptureId" type="string" required>
  The unique identifier of the Capture being disputed.
</ParamField>

### Body parameters

<Tabs>
  <Tab title="Full dispute">
    If you specify only the `ExternalData`, then the full amount of **all** `CapturedAmount` values for all `LineItems` are considered disputed. The `Status` of the Intent becomes `DISPUTED`.

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

      <Expandable>
        <ParamField body="ExternalProcessingDate" type="Unix timestamp" required>
          The date at which the dispute 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 dispute 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 dispute.
        </ParamField>
      </Expandable>
    </ParamField>
  </Tab>

  <Tab title="Partial dispute">
    If you specify one or more `LineItems` objects, then only the specified `Amount` value of the `LineItem.Id` you send is considered disputed. The `Status` of the Intent remains as `CAPTURED`.

    <ParamField body="Amount" type="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.
    </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 dispute processed by the third-party PSP.

      <Expandable>
        <ParamField body="ExternalProcessingDate" type="Unix timestamp" required>
          The date at which the dispute 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 dispute 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 dispute.
        </ParamField>
      </Expandable>
    </ParamField>

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

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

        <Amount_LineItems_Dispute_Request />
      </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 dispute processed by the third-party PSP.

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

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

        <ResponseField name="ExternalMerchantReference" type="string">
          The unique identifier of the dispute 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 dispute.
        </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="Dispute" type="object">
      Information about the Dispute.

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

<ResponseExample>
  ```json Full dispute theme={null}
  {
      "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,
              "CancelledAmount": 0,
              "UnfundedSellerAmount": 0
          },
          {
              "Id": "int_li_019c0e2f-1bab-7443-901b-80d1baf20e47",
              "TotalLineItemAmount": 10000,
              "CapturedAmount": 10000,
              "RefundedAmount": 0,
              "DisputedAmount": 10000,
              "SplitAmount": 0,
              "CancelledAmount": 0,
              "UnfundedSellerAmount": 0
          }
      ],
      "CreationDate": 1769764494,
      "ExecutionDate": 1769764498,
      "Dispute": {
          "Id": "int_dispute_019c0e2f-2c25-753e-8301-3ff93d541358"
      }
  }
  ```

  ```json Partial dispute theme={null}
  {
      "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,
              "CancelledAmount": 0,
              "UnfundedSellerAmount": 0
          },
          {
              "Id": "int_li_019c0e2f-8129-7016-b498-1a9fd0fb1622",
              "TotalLineItemAmount": 10000,
              "CapturedAmount": 10000,
              "RefundedAmount": 0,
              "DisputedAmount": 0,
              "SplitAmount": 0,
              "CancelledAmount": 0,
              "UnfundedSellerAmount": 0
          }
      ],
      "CreationDate": 1769764520,
      "ExecutionDate": 1769764526,
      "Dispute": {
          "Id": "int_dispute_019c0e2f-980c-76ed-9bd5-c6c00617180c"
      }
  }
  ```
</ResponseExample>

<RequestExample>
  ```json Full refund theme={null}
  {   
      "ExternalData": {
          "ExternalProcessingDate": 1769431976,
          "ExternalProviderReference": "dispute-stripe-1d55ff5f-87d0-4825-a766-52177bbc0a73",
          "ExternalMerchantReference": "dispute-order-4d351ba0-3987-408c-b12b-8af412432144",
          "ExternalProviderName": "Stripe",
          "ExternalProviderPaymentMethod": "MASTERCARD"
      }
  }
  ```

  ```json Partial refund theme={null}
  {
      "Amount": 10000,
      "Currency": "EUR",
      "PlatformFeesAmount": 0,
      "ExternalData": {
          "ExternalProcessingDate": 1769764526,
          "ExternalProviderReference": "dispute-stripe-b9e93ae2-36bb-42b6-ad1d-9d34ac14defc",
          "ExternalMerchantReference": "dispute-order-a20938bc-2d5a-4eda-98b2-ff2c04a96f64",      "ExternalProviderName": "Stripe",
          "ExternalProviderPaymentMethod": "MASTERCARD"
      },
      "LineItems": [
          {
              "Id": "int_li_019c0e2f-8129-7016-b498-1a9fd0fb1621",
              "Amount": 10000
          }
      ]
  }
  ```

  ```java Java theme={null}
  // idempotencyKey is null in this example
  PayInIntent disputeResult = api.getPayInApi().createPayInIntentDispute(intent.getId(), intent.getCapture().getId(), disputeToBeCreated, null);
  ```

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

  await Api.PayIns.CreatePartialPayInIntentDisputeAsync(dto, intent.Id, intent.Capture.Id);
  ```

  ```javascript NodeJS theme={null}
  api.PayIns.createPayInIntentDispute(intent.Id, intent.Capture.Id, disputeDto)
  ```

  ```php PHP theme={null}
  _api->PayIns->CreatePayInIntentDispute($intent->Id, $intent->Capture->Id, $disputeDto);
  ```

  ```py Python theme={null}
  PayInIntent.create_dispute(intent.id, intent.capture.id, **dto)
  ```
</RequestExample>