Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Reference Disputes API
version: 1.0.0
servers:
- url: https://api.sandbox.mangopay.com
description: Sandbox
- url: https://api.mangopay.com
description: Production
- url: https://api-mtls.sandbox.mangopay.com
description: mTLS Sandbox
- url: https://api-mtls.mangopay.com
description: mTLS Production
- url: '%7BCardRegistrationUrl%7D'
description: "The full dynamic URL returned by the Create a Card Registration call, including host, path, and query parameters. \n"
- url: '%7BSettlementFileUploadUrl%7D'
description: 'The unique URL returned by the [POST Create a Settlement and secure URL](/api-reference/settlements/create-settlement) endpoint.
**Note:** Use the full dynamic URL including the host, path, and all query parameters. The URL is already authenticated, so this call does not require an Authorization header.
'
tags:
- name: Disputes
paths:
/v2.01/{ClientId}/disputes/{DisputeId}:
get:
operationId: disputes_view_dispute
summary: View a Dispute
tags:
- Disputes
parameters:
- name: ClientId
in: path
description: Platform's API account identifier, associated with the API key.
required: true
schema:
type: string
- name: DisputeId
in: path
description: The unique identifier of the dispute.
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/DisputeResponse'
security:
- oauth2: []
put:
operationId: disputes_update_dispute
summary: Update a Dispute
tags:
- Disputes
parameters:
- name: ClientId
in: path
description: Platform's API account identifier, associated with the API key.
required: true
schema:
type: string
- name: DisputeId
in: path
description: The unique identifier of the dispute.
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/DisputeResponse'
security:
- oauth2: []
/v2.01/{ClientId}/disputes/{DisputeId}/submit:
put:
operationId: disputes_submit_dispute
summary: Submit a Dispute
description: 'Submit a Dispute
This call is used both for the initial submission of the dispute and any resubmission made afterwards (in case more documents are required for instance).'
tags:
- Disputes
parameters:
- name: ClientId
in: path
description: Platform's API account identifier, associated with the API key.
required: true
schema:
type: string
- name: DisputeId
in: path
description: The unique identifier of the dispute.
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/DisputeResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitADisputeRequest'
security:
- oauth2: []
/v2.01/{ClientId}/disputes/{DisputeId}/close:
put:
operationId: disputes_close_dispute
summary: Close a Dispute
description: '**Note – Empty body required**
For the call to be successful, you need to pass an empty body.
Close a Dispute'
tags:
- Disputes
parameters:
- name: ClientId
in: path
description: Platform's API account identifier, associated with the API key.
required: true
schema:
type: string
- name: DisputeId
in: path
description: The unique identifier of the dispute.
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/DisputeResponse'
security:
- oauth2: []
/v2.01/{ClientId}/disputes:
get:
operationId: disputes_list_disputes
summary: List all Disputes
tags:
- Disputes
parameters:
- name: ClientId
in: path
description: Platform's API account identifier, associated with the API key.
required: true
schema:
type: string
- name: BeforeDate
in: query
description: The date before which the object was created (based on the object's `CreationDate` parameter). You can filter on a specific time range by using both the `AfterDate` and `BeforeDate` query parameters.
required: false
schema:
type: integer
- name: AfterDate
in: query
description: The date after which the object was created (based on the object's `CreationDate` parameter). You can filter on a specific time range by using both the `AfterDate` and `BeforeDate` query parameters.
required: false
schema:
type: integer
- name: Status
in: query
description: '**Allowed values:** `CREATED`, `PENDING_CLIENT_ACTION`, `SUBMITTED`, `PENDING_BANK_ACTION`, `CLOSED`, `REOPENED_PENDING_CLIENT_ACTION`
The status of the Dispute. You can filter on multiple values by separating them with a comma.'
required: false
schema:
type: string
- name: DisputeType
in: query
description: '**Allowed values:** `CONTESTABLE`, `NOT_CONTESTABLE`, `RETRIEVAL`
The type of the Dispute. You can filter on multiple values by separating them with a comma.'
required: false
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ListAllDisputesResponse'
security:
- oauth2: []
/v2.01/{ClientId}/disputes/pendingsettlement:
get:
operationId: disputes_list_disputes_settlement
summary: List Disputes pending settlement
description: 'List Disputes pending settlement
This call lists all the disputes for which you need to make a settlement transfer.'
tags:
- Disputes
parameters:
- name: ClientId
in: path
description: Platform's API account identifier, associated with the API key.
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ListAllDisputesResponse'
security:
- oauth2: []
/v2.01/{ClientId}/payins/{PayInId}/disputes:
get:
operationId: disputes_list_disputes_payin
summary: List Disputes for a PayIn
tags:
- Disputes
parameters:
- name: ClientId
in: path
description: Platform's API account identifier, associated with the API key.
required: true
schema:
type: string
- name: PayInId
in: path
description: The unique identifier of the pay-in.
required: true
schema:
type: string
- name: BeforeDate
in: query
description: The date before which the object was created (based on the object's `CreationDate` parameter). You can filter on a specific time range by using both the `AfterDate` and `BeforeDate` query parameters.
required: false
schema:
type: integer
- name: AfterDate
in: query
description: The date after which the object was created (based on the object's `CreationDate` parameter). You can filter on a specific time range by using both the `AfterDate` and `BeforeDate` query parameters.
required: false
schema:
type: integer
- name: Status
in: query
description: '**Allowed values:** `CREATED`, `PENDING_CLIENT_ACTION`, `SUBMITTED`, `PENDING_BANK_ACTION`, `CLOSED`, `REOPENED_PENDING_CLIENT_ACTION`
The status of the Dispute. You can filter on multiple values by separating them with a comma.'
required: false
schema:
type: string
- name: DisputeType
in: query
description: '**Allowed values:** `CONTESTABLE`, `NOT_CONTESTABLE`, `RETRIEVAL`
The type of the Dispute. You can filter on multiple values by separating them with a comma.'
required: false
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ListAllDisputesResponse'
security:
- oauth2: []
/v2.01/{ClientId}/users/{UserId}/disputes:
get:
operationId: disputes_list_disputes_user
summary: List Disputes for a User
tags:
- Disputes
parameters:
- name: ClientId
in: path
description: Platform's API account identifier, associated with the API key.
required: true
schema:
type: string
- name: UserId
in: path
description: The unique identifier of the user.
required: true
schema:
type: string
- name: BeforeDate
in: query
description: The date before which the object was created (based on the object's `CreationDate` parameter). You can filter on a specific time range by using both the `AfterDate` and `BeforeDate` query parameters.
required: false
schema:
type: integer
- name: AfterDate
in: query
description: The date after which the object was created (based on the object's `CreationDate` parameter). You can filter on a specific time range by using both the `AfterDate` and `BeforeDate` query parameters.
required: false
schema:
type: integer
- name: Status
in: query
description: '**Allowed values:** `CREATED`, `PENDING_CLIENT_ACTION`, `SUBMITTED`, `PENDING_BANK_ACTION`, `CLOSED`, `REOPENED_PENDING_CLIENT_ACTION`
The status of the Dispute. You can filter on multiple values by separating them with a comma.'
required: false
schema:
type: string
- name: DisputeType
in: query
description: '**Allowed values:** `CONTESTABLE`, `NOT_CONTESTABLE`, `RETRIEVAL`
The type of the Dispute. You can filter on multiple values by separating them with a comma.'
required: false
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ListAllDisputesResponse'
security:
- oauth2: []
/v2.01/{ClientId}/wallets/{WalletId}/disputes:
get:
operationId: disputes_list_disputes_wallet
summary: List Disputes for a Wallet
tags:
- Disputes
parameters:
- name: ClientId
in: path
description: Platform's API account identifier, associated with the API key.
required: true
schema:
type: string
- name: WalletId
in: path
description: The unique identifier of the wallet.
required: true
schema:
type: string
- name: BeforeDate
in: query
description: The date before which the object was created (based on the object's `CreationDate` parameter). You can filter on a specific time range by using both the `AfterDate` and `BeforeDate` query parameters.
required: false
schema:
type: integer
- name: AfterDate
in: query
description: The date after which the object was created (based on the object's `CreationDate` parameter). You can filter on a specific time range by using both the `AfterDate` and `BeforeDate` query parameters.
required: false
schema:
type: integer
- name: Status
in: query
description: '**Allowed values:** `CREATED`, `PENDING_CLIENT_ACTION`, `SUBMITTED`, `PENDING_BANK_ACTION`, `CLOSED`, `REOPENED_PENDING_CLIENT_ACTION`
The status of the Dispute. You can filter on multiple values by separating them with a comma.'
required: false
schema:
type: string
- name: DisputeType
in: query
description: '**Allowed values:** `CONTESTABLE`, `NOT_CONTESTABLE`, `RETRIEVAL`
The type of the Dispute. You can filter on multiple values by separating them with a comma.'
required: false
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ListAllDisputesResponse'
security:
- oauth2: []
components:
schemas:
Amount:
type: integer
description: The amount of the currency in its minor unit. For example, EUR 12.60 would be represented as `1260` whereas JPY 12 would be represented as just `12`.
title: Amount
SubmitADisputeRequest:
type: object
properties:
ContestedFunds:
$ref: '#/components/schemas/SubmitADisputeRequestContestedFunds'
description: Information about the debited funds.
required:
- ContestedFunds
title: SubmitADisputeRequest
ResultMessage:
type: string
description: The explanation of the result code.
title: ResultMessage
ListAllDisputesResponseArrayDisputesItemsObjectDisputeDisputeReason:
type: object
properties:
DisputeReasonType:
type: string
description: The reason for the dispute.
DisputeReasonMessage:
type: string
description: Additional information about the reason for the dispute sent by Mangopay teams.
description: Information about the reasons for the dispute.
title: ListAllDisputesResponseArrayDisputesItemsObjectDisputeDisputeReason
Currency:
type: string
description: '**Allowed values:** The three-letter <a href="/api-reference/overview/data-formats" target="_blank">ISO 4217 code</a> (EUR, GBP, etc.) of a <a href="/guides/currencies" target="_blank">supported currency</a> (depends on feature, contract, and activation settings).
The currency of the amount.'
title: Currency
DisputeResponseDisputeReason:
type: object
properties:
DisputeReasonType:
type: string
description: The reason for the dispute.
DisputeReasonMessage:
type: string
description: Additional information about the reason for the dispute sent by Mangopay teams.
description: Information about the reasons for the dispute.
title: DisputeResponseDisputeReason
DisputeResponseContestedFunds:
type: object
properties:
Currency:
$ref: '#/components/schemas/Currency'
Amount:
$ref: '#/components/schemas/Amount'
description: 'Information about the contested funds, in other words, the amount that you wish to contest.
This amount can be lower than the disputed funds amount.'
title: DisputeResponseContestedFunds
Tag:
type: string
description: '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}"`.'
title: Tag
CreationDate:
type: integer
description: Unix timestamp (UTC) of the date and time the object was created.
title: CreationDate
ListAllDisputesResponse:
type: object
properties:
Array (Disputes):
type: array
items:
$ref: '#/components/schemas/ListAllDisputesResponseArrayDisputesItems'
description: The list of disputes automatically created by Mangopay.
title: ListAllDisputesResponse
ListAllDisputesResponseArrayDisputesItemsObjectDisputeDisputedFunds:
type: object
properties:
Currency:
$ref: '#/components/schemas/Currency'
Amount:
$ref: '#/components/schemas/Amount'
description: 'Information about the amount the disputed funds.
This amount can be lower than the initial transaction amount.'
title: ListAllDisputesResponseArrayDisputesItemsObjectDisputeDisputedFunds
Error:
type: object
properties:
Message:
type: string
description: Description of the error.
Type:
type: string
description: 'The category of the error.
'
Id:
type: string
description: Unique identifier of the error instance, useful when contacting Mangopay for support.
Date:
type: number
format: double
description: Unix timestamp (UTC) of the date and time the error was triggered.
errors:
type:
- object
- 'null'
additionalProperties:
type: string
description: 'Object containing one or more field-level errors.
'
description: 'The error body typically returned by the Mangopay API for any non-2xx HTTP status code.
'
title: Error
ListAllDisputesResponseArrayDisputesItemsObjectDisputeContestedFunds:
type: object
properties:
Currency:
$ref: '#/components/schemas/Currency'
Amount:
$ref: '#/components/schemas/Amount'
description: 'Information about the contested funds, in other words, the amount that you wish to contest.
This amount can be lower than the disputed funds amount.'
title: ListAllDisputesResponseArrayDisputesItemsObjectDisputeContestedFunds
Id:
type: string
description: 'Max length: 128 characters (see [data formats](/api-reference/overview/data-formats) for details)
The unique identifier of the object.'
title: Id
SubmitADisputeRequestContestedFunds:
type: object
properties:
Currency:
$ref: '#/components/schemas/Currency'
Amount:
$ref: '#/components/schemas/Amount'
required:
- Currency
- Amount
description: Information about the debited funds.
title: SubmitADisputeRequestContestedFunds
ListAllDisputesResponseArrayDisputesItemsObjectDispute:
type: object
properties:
InitialTransactionId:
type: string
description: The unique identifier of the initial pay-in being disputed.
InitialTransactionType:
type: string
description: '**Returned values:** `PAYIN`
The type of the initial transaction being disputed.'
InitialTransactionNature:
type: string
description: '**Returned values:** `REGULAR`, `REPUDIATION`, `REFUND`, `SETTLEMENT`
The nature of the initial transaction being refunded, providing more information about the context in which the transaction occurred:
- REGULAR – Relative to most of the transactions (pay-ins, payouts, and transfers) in a usual workflow.
- REPUDIATION – Automatic withdrawal of funds from the platform''s repudiation wallet as part of the dispute process (when the user requested a chargeback).
- REFUND – Reimbursement of a transaction to the user (pay-in refund), to a wallet (transfer refund), or of a payout (payout refund, only initiated by Mangopay).
- SETTLEMENT – Transfer made to the repudiation wallet by the platform to settle the credit from a repudiation following a lost dispute.'
DisputeType:
type: string
description: '**Returned values:** `CONTESTABLE`, `NOT_CONTESTABLE`, `RETRIEVAL`
The type of dispute:
- `CONTESTABLE` – Dispute for which the chargeback can be contested by providing proof (i.e., Dispute Documents) justifying the original transaction.
- `NOT_CONTESTABLE` – Dispute that is automatically closed after its creation, without any action possible for the platform.
- `RETRIEVAL` – Dispute that is actually a chargeback warning issued by the bank. The platform is required to provide documents, but no funds will be taken from the Repudiation Wallet.'
ContestDeadlineDate:
type: integer
description: The date and time until which the platform can contest the dispute (i.e., the `Status` is set to `SUBMITTED`). This date is defined by the issuing bank of the initial transaction and may usually vary between 7 to 18 days. Once the deadline passes, the dispute `Status` is automatically set to `CLOSED`.
DisputedFunds:
$ref: '#/components/schemas/ListAllDisputesResponseArrayDisputesItemsObjectDisputeDisputedFunds'
description: 'Information about the amount the disputed funds.
This amount can be lower than the initial transaction amount.'
ContestedFunds:
$ref: '#/components/schemas/ListAllDisputesResponseArrayDisputesItemsObjectDisputeContestedFunds'
description: 'Information about the contested funds, in other words, the amount that you wish to contest.
This amount can be lower than the disputed funds amount.'
Status:
type: string
description: '**Returned values:** `CREATED`, `PENDING_CLIENT_ACTION`, `SUBMITTED`, `PENDING_BANK_ACTION`, `REOPENED_PENDING_CLIENT_ACTION`, `CLOSED`
The status of the dispute:
- `CREATED` – The dispute is created.
- `PENDING_CLIENT_ACTION` – The dispute was not closed automatically upon its creation, it now requires some actions from the platform (either submission after providing the relevant proofs or closing).
- `SUBMITTED` – The dispute is submitted by the platform for the Mangopay team to review the documents.
- `PENDING_BANK_ACTION` – Mangopay accepted the documents and passed them on to the bank for them to review the dispute contestation. They will either reject or accept the contestation, or require further documents.
- `REOPENED_PENDING_CLIENT_ACTION` – Mangopay didn''t accept the documents and requires more information or documents before sending the documents to the bank.
- `CLOSED` – The dispute is closed.'
StatusMessage:
type: string
description: Additional information about the dispute `Status` communicated by Mangopay teams.
DisputeReason:
$ref: '#/components/schemas/ListAllDisputesResponseArrayDisputesItemsObjectDisputeDisputeReason'
description: Information about the reasons for the dispute.
ResultCode:
type: string
description: '**Returned values:** `LOST`, `WON`, `VOID`
The result of the dispute for the platform, which can be:
- `LOST` – The platform lost the dispute and must settle its debt to Mangopay with a Settlement Transfer.
- `WON` – The platform won the dispute, the disputed funds will be credited back to the Repudiation Wallet.
- `VOID` – The dispute has been canceled.'
ResultMessage:
$ref: '#/components/schemas/ResultMessage'
Id:
$ref: '#/components/schemas/Id'
Tag:
$ref: '#/components/schemas/Tag'
CreationDate:
$ref: '#/components/schemas/CreationDate'
ClosedDate:
type: integer
description: 'The date and time the dispute was closed (i.e., its `Status` is set to `CLOSED`).
**Note:** This value will be `null` for any Dispute closed before February 16th, 2023.'
RepudiationId:
type: string
description: The unique identifier of the repudiation.
description: The dispute automatically created by Mangopay.
title: ListAllDisputesResponseArrayDisputesItemsObjectDispute
DisputeResponse:
type: object
properties:
InitialTransactionId:
type: string
description: The unique identifier of the initial pay-in being disputed.
InitialTransactionType:
type: string
description: '**Returned values:** `PAYIN`
The type of the initial transaction being disputed.'
InitialTransactionNature:
type: string
description: '**Returned values:** `REGULAR`
The nature of the initial transaction being disputed.'
DisputeType:
type: string
description: '**Returned values:** `CONTESTABLE`, `NOT_CONTESTABLE`, `RETRIEVAL`
The type of dispute:
- `CONTESTABLE` – Dispute for which the chargeback can be contested by providing proof (i.e., Dispute Documents) justifying the original transaction.
- `NOT_CONTESTABLE` – Dispute that is automatically closed after its creation, without any action possible for the platform.
- `RETRIEVAL` – Dispute that is actually a chargeback warning issued by the bank. The platform is required to provide documents, but no funds will be taken from the Repudiation Wallet.'
ContestDeadlineDate:
type: integer
description: The date and time until which the platform can contest the dispute (i.e., the `Status` is set to `SUBMITTED`). This date is defined by the issuing bank of the initial transaction and may usually vary between 7 to 18 days. Once the deadline passes, the dispute `Status` is automatically set to `CLOSED`.
DisputedFunds:
$ref: '#/components/schemas/DisputeResponseDisputedFunds'
description: 'Information about the amount the disputed funds.
This amount can be lower than the initial transaction amount.'
ContestedFunds:
$ref: '#/components/schemas/DisputeResponseContestedFunds'
description: 'Information about the contested funds, in other words, the amount that you wish to contest.
This amount can be lower than the disputed funds amount.'
Status:
type: string
description: '**Returned values:** `CREATED`, `PENDING_CLIENT_ACTION`, `SUBMITTED`, `PENDING_BANK_ACTION`, `REOPENED_PENDING_CLIENT_ACTION`, `CLOSED`
The status of the dispute:
- `CREATED` – The dispute is created.
- `PENDING_CLIENT_ACTION` – The dispute was not closed automatically upon its creation, it now requires some actions from the platform (either submission after providing the relevant proofs or closing).
- `SUBMITTED` – The dispute is submitted by the platform for the Mangopay team to review the documents.
- `PENDING_BANK_ACTION` – Mangopay accepted the documents and passed them on to the bank for them to review the dispute contestation. They will either reject or accept the contestation, or require further documents.
- `REOPENED_PENDING_CLIENT_ACTION` – Mangopay didn''t accept the documents and requires more information or documents before sending the documents to the bank.
- `CLOSED` – The dispute is closed.'
StatusMessage:
type: string
description: Additional information about the dispute `Status` communicated by Mangopay teams.
DisputeReason:
$ref: '#/components/schemas/DisputeResponseDisputeReason'
description: Information about the reasons for the dispute.
ResultCode:
type: string
description: '**Returned values:** `LOST`, `WON`, `VOID`
The result of the dispute for the platform, which can be:
- `LOST` – The platform lost the dispute and must settle its debt to Mangopay with a Settlement Transfer.
- `WON` – The platform won the dispute, the disputed funds will be credited back to the Repudiation Wallet.
- `VOID` – The dispute has been canceled.'
ResultMessage:
$ref: '#/components/schemas/ResultMessage'
Id:
$ref: '#/components/schemas/Id'
Tag:
$ref: '#/components/schemas/Tag'
CreationDate:
$ref: '#/components/schemas/CreationDate'
ClosedDate:
type: integer
description: 'The date and time the dispute was closed (i.e., its `Status` is set to `CLOSED`).
**Note:** This value will be `null` for any Dispute closed before February 16th, 2023.'
RepudiationId:
type: string
description: The unique identifier of the repudiation.
title: DisputeResponse
ListAllDisputesResponseArrayDisputesItems:
type: object
properties:
Object (Dispute):
$ref: '#/components/schemas/ListAllDisputesResponseArrayDisputesItemsObjectDispute'
description: The dispute automatically created by Mangopay.
title: ListAllDisputesResponseArrayDisputesItems
DisputeResponseDisputedFunds:
type: object
properties:
Currency:
$ref: '#/components/schemas/Currency'
Amount:
$ref: '#/components/schemas/Amount'
description: 'Information about the amount the disputed funds.
This amount can be lower than the initial transaction amount.'
title: DisputeResponseDisputedFunds
securitySchemes:
oauth2:
type: http
scheme: bearer
description: "Bearer authentication of the form `Bearer <token>`, where token is your auth token. \n\nIf 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."
x-provenance:
method: harvested
publisher: Mangopay
source: https://docs.mangopay.com/openapi.json
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)