The Dispute object

The Dispute Object is used when a User requests a chargeback of transaction to their bank – in turn, their bank withdraws the funds from us and we will then repudiate the required funds from your client credit wallet.

Dispute process overview

  1. A PayIn is completed successfully
  2. The end user contacts his/her bank to request a chargeback
  3. The bank contacts us and withdraws the funds automatically
  4. We create a Dispute object in the API – you will receive an email by default, and can also set up the usual Hooks if you like
  5. Along with the Dispute, we will also repudiate the funds from your credit wallet (the amount in the original wallet will therefore remain unchanged which is different to the previous process).
  6. If the Dispute is contestable, you are able to contest this Dispute and submit evidence to try to reverse the repudiation and reclaim the funds (note that you do not have to contest the full amount) – evidence might include a delivery note, a refund you’ve already done for instance, but will depend on the type of Dispute. The evidence is submitted as documents, similarly to the current KYC process.
  7. Once we’ve verified the Dispute documents, we will pass them on to the relevant bank, and they will either:
    • Accept the contest and refund the funds you had contested (we will then refund this amount to your credit wallet)
    • Reject the contest – in which case the Dispute will be closed as you have lost
    • Ask for further documents – in this case, we will reopen the Dispute and ask you to submit further evidence – check the StatusMessage field for more information.
  8. In the event you have credit following a Dispute (because you lost, or didn’t contest the full amount), you can do a settlement transfer to transfer funds from the original wallet to the credit wallet if you wish – this is entirely optional and will depend on your workflow whether you want to impact the original wallet or not.
  9. If your credit wallet balance is negative, it means that you have a debt to settle with MANGOPAY. In that case, you’re required to make a settlement transfer to rectify the situation.

alt

Important notes

  • You are strongly advised to use the available hooks to be notified (and therefore act on the changes from your side) of Dispute status changes (for example, in the case of a Dispute being reopened because more documents are required, you will not be notified by email – only via the hooks)
  • All contestable disputes have a date by which they can be contested – after this time, no further action is permitted from your side
  • Banks can sometimes issue a warning of a chargeback that may happen – in this case, we will still create a Dispute (with the DisputeType of “RETRIEVAL”) and require you to send various documents, however there will be no funds repudiated from your credit wallet in this case
  • Some Disputes are not contestable (they’ll have the DisputeType of “NOT_CONTESTABLE” as opposed to “CONTESTABLE”) – this means they’ll be closed just after being created and no further action is possible from your side

Parameters

InitialTransactionId
string

string:

Maximum length is 255 characters

The initial transaction ID

InitialTransactionType
TransactionType

TransactionType:

PAYIN, TRANSFER, PAYOUT

The initial transaction type

ResultCode
string

string:

Maximum length is 255 characters

The result code

ResultMessage
string

string:

Maximum length is 255 characters

A verbal explanation of the ResultCode

DisputeReason
DisputeReason

DisputeReason:

View Sub-parameters

Info about the reason for the dispute

DisputeReason.DisputeReasonType
DisputeReasonType

DisputeReasonType:

DUPLICATE, FRAUD, PRODUCT_UNACCEPTABLE, UNKNOWN, OTHER, REFUND_CONVERSION_RATE, LATE_FAILURE_INSUFFICIENT_FUNDS, LATE_FAILURE_CONTACT_USER, LATE_FAILURE_BANKACCOUNT_CLOSED, LATE_FAILURE_BANKACCOUNT_INCOMPATIBLE, LATE_FAILURE_BANKACCOUNT_INCORRECT, AUTHORISATION_DISPUTED, TRANSACTION_NOT_RECOGNIZED, PRODUCT_NOT_PROVIDED, CANCELED_REOCCURING_TRANSACTION, REFUND_NOT_PROCESSED

The reason type for the dispute

The type of reason for the dispute

DisputeReason.DisputeReasonMessage
string

string:

Maximum length is 255 characters

More information about the reason for the dispute

Status
DisputeStatus

DisputeStatus:

CREATED, PENDING_CLIENT_ACTION, SUBMITTED, PENDING_BANK_ACTION, REOPENED_PENDING_CLIENT_ACTION, CLOSED

The status of the Dispute

The status of the dispute

StatusMessage
string

string:

Maximum length is 255 characters

Used to communicate information about the dispute status to you

DisputedFunds
Money

Money:

View Sub-parameters

The amount of funds that were disputed

DisputedFunds.Currency
Currency

Currency:

AED, AUD, CAD, CHF, CZK, DKK, EUR, GBP, HKD, JPY, NOK, PLN, SEK, USD, ZAR

The currency - should be ISO_4217 format

DisputedFunds.Amount
int

int

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

ContestedFunds
Money

Money:

View Sub-parameters

The amount you wish to contest

ContestedFunds.Currency
Currency

Currency:

AED, AUD, CAD, CHF, CZK, DKK, EUR, GBP, HKD, JPY, NOK, PLN, SEK, USD, ZAR

The currency - should be ISO_4217 format

ContestedFunds.Amount
int

int

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

DisputeType
DisputeType

DisputeType:

CONTESTABLE, NOT_CONTESTABLE, RETRIEVAL

The type of Dispute

The type of dispute

ContestDeadlineDate
timestamp

timestamp

The deadline by which you must contest the dispute (if you wish to contest it)

ClosedDate
timestamp

timestamp

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
string

string:

Maximum length is 255 characters

The ID of the associated repudiation transaction

{
"InitialTransactionId": "1463496101",
"InitialTransactionType": "PAYIN",
"ResultCode": "000000",
"ResultMessage": "The transaction was successful",
"DisputeReason": {
"DisputeReasonType": "FRAUD",
"DisputeReasonMessage": "This was a fraudulent transaction"
},
"Status": "PENDING_CLIENT_ACTION",
"StatusMessage": "You must reupload your delivery proof",
"DisputedFunds": {
"Currency": "EUR",
"Amount": 12
},
"ContestedFunds": {
"Currency": "EUR",
"Amount": 12
},
"DisputeType": "CONTESTABLE",
"ContestDeadlineDate": 12327031,
"ClosedDate": 1494350900,
"RepudiationId": "12639879"
}

View a Dispute

GET .../v2.01/ClientId

The ID of your client account

/disputes/DisputeId

The Id of a Dispute

/
  • View
  • Code
  • Run
  • View
  • Code
  • Run
GET .../disputes/:DisputeId/ HTTP/1.1
GET .../disputes// HTTP/1.1

Update a Dispute

This method is used to update the "Tag" of a dispute

PUT .../v2.01/ClientId

The ID of your client account

/disputes/DisputeId

The Id of a Dispute

/
  • View
  • Code
  • Run
  • View
  • Code
  • Run
PUT .../disputes/:DisputeId/ HTTP/1.1
PUT .../disputes// HTTP/1.1

Close a Dispute

This method is used to close a "Dispute", effectively confirming that you do not wish to contest it. This action is optional, and once the "ContestDeadlineDate" passes, you will not be able to contest it anyway

PUT .../v2.01/ClientId

The ID of your client account

/disputes/DisputeId

The Id of a Dispute

/close/
  • View
  • Code
  • Run
  • View
  • Code
  • Run
PUT .../disputes/:DisputeId/close/ HTTP/1.1
PUT .../disputes//close/ HTTP/1.1

Submit a Dispute

This method is used to contest a Dispute.

The "ContestedFunds" must be the same "Currency" as the "DisputedFunds", and the amount can be up to and including the "DisputedFunds".

PUT .../v2.01/ClientId

The ID of your client account

/disputes/DisputeId

The Id of a Dispute

/submit/

Parameters

ContestedFunds
Money

Money:

View Sub-parameters

optional

The amount you wish to contest

ContestedFunds.Currency
Currency

Currency:

AED, AUD, CAD, CHF, CZK, DKK, EUR, GBP, HKD, JPY, NOK, PLN, SEK, USD, ZAR

required

The currency - should be ISO_4217 format

ContestedFunds.Amount
int

int

required

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

  • View
  • Code
  • Run
  • View
  • Code
  • Run
PUT .../disputes/:DisputeId/submit/ HTTP/1.1
Body Parameters :
{
"ContestedFunds": {
"Currency": "EUR",
"Amount": 12
}
}
PUT .../disputes//submit/ HTTP/1.1
Body Parameters :
{
"ContestedFunds": {
"Currency": "",
"Amount":
}
}

Re-submit a Dispute

This method is used to resubmit a "Dispute" if it is reopened requiring more docs

PUT .../v2.01/ClientId

The ID of your client account

/disputes/DisputeId

The Id of a Dispute

/submit/
  • View
  • Code
  • Run
  • View
  • Code
  • Run
PUT .../disputes/:DisputeId/submit/ HTTP/1.1
PUT .../disputes//submit/ HTTP/1.1

List a User's Disputes

GET .../v2.01/ClientId

The ID of your client account

/users/UserId

A Mangopay user's ID

/disputes/

Get parameters

DisputeType
DisputeType

DisputeType:

CONTESTABLE, NOT_CONTESTABLE, RETRIEVAL

The type of Dispute

optional

The type of dispute

Status
DisputeStatus

DisputeStatus:

CREATED, PENDING_CLIENT_ACTION, SUBMITTED, PENDING_BANK_ACTION, REOPENED_PENDING_CLIENT_ACTION, CLOSED

The status of the Dispute

optional

The status of this KYC/Dispute document

  • View
  • Code
    A code sample is not available
  • Run
  • View
  • Code
    A code sample is not available
  • Run
GET .../users/:UserId/disputes/ HTTP/1.1
Get Parameters :
{
"DisputeType": "CONTESTABLE,RETRIEVAL",
"Status": "CREATED, SUCCEEDED"
}
GET .../users//disputes/ HTTP/1.1
Get Parameters :
{
"DisputeType": "",
"Status": ""
}

List a Wallet's Disputes

GET .../v2.01/ClientId

The ID of your client account

/wallets/WalletId

The ID of a wallet

/disputes/

Get parameters

DisputeType
DisputeType

DisputeType:

CONTESTABLE, NOT_CONTESTABLE, RETRIEVAL

The type of Dispute

optional

The type of dispute

Status
DisputeStatus

DisputeStatus:

CREATED, PENDING_CLIENT_ACTION, SUBMITTED, PENDING_BANK_ACTION, REOPENED_PENDING_CLIENT_ACTION, CLOSED

The status of the Dispute

optional

The status of this KYC/Dispute document

  • View
  • Code
    A code sample is not available
  • Run
  • View
  • Code
    A code sample is not available
  • Run
GET .../wallets/:WalletId/disputes/ HTTP/1.1
Get Parameters :
{
"DisputeType": "CONTESTABLE,RETRIEVAL",
"Status": "CREATED, SUCCEEDED"
}
GET .../wallets//disputes/ HTTP/1.1
Get Parameters :
{
"DisputeType": "",
"Status": ""
}

List all Disputes

GET .../v2.01/ClientId

The ID of your client account

/disputes/

Get parameters

DisputeType
DisputeType

DisputeType:

CONTESTABLE, NOT_CONTESTABLE, RETRIEVAL

The type of Dispute

optional

The type of dispute

Status
DisputeStatus

DisputeStatus:

CREATED, PENDING_CLIENT_ACTION, SUBMITTED, PENDING_BANK_ACTION, REOPENED_PENDING_CLIENT_ACTION, CLOSED

The status of the Dispute

optional

The status of this KYC/Dispute document

  • View
  • Code
    A code sample is not available
  • Run
  • View
  • Code
    A code sample is not available
  • Run
GET .../disputes/ HTTP/1.1
Get Parameters :
{
"DisputeType": "CONTESTABLE,RETRIEVAL",
"Status": "CREATED, SUCCEEDED"
}
GET .../disputes/ HTTP/1.1
Get Parameters :
{
"DisputeType": "",
"Status": ""
}

List Disputes that need settling

In the event you have credit following a Dispute (because you lost, or didn’t contest the full amount), you can do a settlement transfer to transfer funds from the original wallet to the credit wallet if you wish – this is entirely optional and will depend on your workflow whether you want to impact the original wallet or not. The endpoint below provides you with the list of disputes that allow a settlement transfer - meaning that you have credit for these disputes and that funds are still available in the original wallet.

GET .../v2.01/ClientId

The ID of your client account

/disputes/pendingsettlement
  • View
  • Code
    A code sample is not available
  • Run
  • View
  • Code
    A code sample is not available
  • Run
GET .../disputes/pendingsettlement HTTP/1.1
GET .../disputes/pendingsettlement HTTP/1.1
Share feedback