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
- A
PayIn
is completed successfully - The end user contacts his/her bank to request a chargeback
- The bank contacts us and withdraws the funds automatically
- 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 - 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).
- 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.
- 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.
- 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.
- 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.
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:
Maximum length is 255 characters
The initial transaction ID
InitialTransactionType
TransactionType:
PAYIN, TRANSFER, PAYOUT
The initial transaction type
ResultCode
string:
Maximum length is 255 characters
The result code
ResultMessage
string:
Maximum length is 255 characters
A verbal explanation of the ResultCode
DisputeReason
DisputeReason:
View Sub-parameters
Info about the reason for the dispute
DisputeReason.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:
Maximum length is 255 characters
More information about the reason for the dispute
Status
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:
Maximum length is 255 characters
Used to communicate information about the dispute status to you
DisputedFunds
Money:
View Sub-parameters
The amount of funds that were disputed
DisputedFunds.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
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:
View Sub-parameters
The amount you wish to contest
ContestedFunds.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
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:
CONTESTABLE, NOT_CONTESTABLE, RETRIEVAL
The type of Dispute
The type of dispute
ContestDeadlineDate
timestamp
The deadline by which you must contest the dispute (if you wish to contest it)
ClosedDate
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:
Maximum length is 255 characters
The ID of the associated repudiation transaction