--- title: "Create an Intent Dispute" method: POST path: "/v3.0/{ClientId}/payins/intents/{IntentId}/capture/{CaptureId}/disputes" tags: ["Intents"] --- # Create an Intent Dispute `POST /v3.0/{ClientId}/payins/intents/{IntentId}/capture/{CaptureId}/disputes` ## Request - Base URL: `https://api.sandbox.mangopay.com` - URL: `https://api.sandbox.mangopay.com/v3.0/{ClientId}/payins/intents/{IntentId}/capture/{CaptureId}/disputes` - Auth: HTTP bearer Declare the full or partial dispute of a payment processed by a third-party PSP, represented by an Intent Dispute. ## Path parameters - `ClientId` string, required - `IntentId` string, required - `CaptureId` string, required ## Request body - CreateAnIntentDisputeRequest - `ExternalData` ExternalProcessingDateExternalProviderReferenceExternalMerchantReference2, required: 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. - `ExternalMerchantReference` string: The unique identifier of the transaction at the merchant 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. - `ExternalProviderPaymentMethod` string: One of the [supported payment methods](/api-reference/echo/supported-payment-methods) used to process the transaction. - `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. - `Currency` string: The currency of the intent. - `PlatformFeesAmount` 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 `PlatformFeesAmount` value must the sum of all line item `Seller.FeesAmount` values. - `LineItems` CreateAnIntentDisputeRequestLineItemsItems[], required: Information about the amount disputed for each line item, required for a partial dispute. - `Id` string, required: The unique identifier of the line item in Mangopay ecosystem. - `Tag` string: 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 - IntentDisputeResponse - `Id` string: The unique identifier of the intent. - `Amount` integer: The full amount authorized in the Intent, which must equal the sum of the total amounts of all `LineItems`. - `AvailableAmountToSplit` integer: The remaining amount of the Intent that can be split and transferred to the sellers' wallets. - `UnfundedAmount` integer: The amount needing to be settled to the Platform's technical wallet before the Intent Splits can be executed. - `Currency` string: The currency of the intent. - `PlatformFeesAmount` 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 `PlatformFeesAmount` value must the sum of all line item `Seller.FeesAmount` values. - `Status` 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. - `NextActions` string: The possible next actions on the intent. - `ExternalData` ExternalProcessingDateExternalProviderReferenceExternalMerchantReference: Information about the transaction authorization processed by the third-party PSP. - `ExternalProcessingDate` integer: The date at which the transaction authorization was created. - `ExternalProviderReference` string: The unique identifier of the transaction at the provider level. - `ExternalMerchantReference` string: The unique identifier of the transaction at the merchant level. - `ExternalProviderName` 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. - `ExternalProviderPaymentMethod` string: One of the [supported payment methods](/api-reference/echo/supported-payment-methods) used to process the transaction. - `Buyer` BuyerId: Information about the buyer. - `Id` 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`. - `LineItems` IdTotalLineItemAmountCapturedAmount[]: Information about the line items included in the intent action. - `Id` string: The unique identifier of the line item in Mangopay's ecosystem. - `TotalLineItemAmount` integer: The total amount of the line item calculated as ((`UnitAmount` x `Quantity`) - `DiscountAmount`). - `CapturedAmount` integer: The item total `CAPTURED` amount - `RefundedAmount` integer: The item total `REFUNDED` amount - `DisputedAmount` integer: The item total `DISPUTED` amount. - `SplitAmount` integer: The item total `COMPLETED` amount. - `UnfundedSellerAmount` integer: The amount needing to be settled to the Platform's technical wallet before the Intent Splits can be executed for this seller. - `CreationDate` integer: Unix timestamp (UTC) of the date and time the object was created. - `ExecutionDate` integer: Unix timestamp (UTC) of the date and time the Intent moved to `AUTHORIZED`. - `Dispute` IdIntentDispute: Information about the Dispute. - `Id` string: The unique identifier of the Dispute. ## Changes - **2026-09-17** `f44a59c76515`: 1 warning, 1 info - deleted the `header` request parameter `Authorization` - the endpoint scheme security `oauth2` was added to the API - **2026-09-12** `8e731ec4a85b`: 1 info - api operation id `create_intent_dispute` removed and replaced with `intents_create_intent_dispute` - **2026-07-26** `795281070285`: 1 info - added the new optional request property `Tag` [Operation history](https://skmtc.dev/mangopay/apis/api-reference/changes/v3.0/:ClientId/payins/intents/:IntentId/capture/:CaptureId/disputes/post.md) --- [API](https://skmtc.dev/mangopay/apis/api-reference.md) - [All operations](https://skmtc.dev/mangopay/apis/api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/mangopay/apis/api-reference/revisions/d288c2f6fa97?raw)