Disputes
Introduction
Customers may question the validity of a transaction registered to their account and ask for a . The issuing bank then withdraws the corresponding funds from Mangopay.
The platform may have the opportunity to contest the chargeback by providing proof prior to being requested to settle their credit to Mangopay.
Mangopay automatically creates a Dispute object when a chargeback occurs to handle proof submissions and settlement.
Type of disputes
Mangopay offers three types of disputes depending on the kind of chargeback that occurred.
| 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. |
Note - Disputes and Refunds
Disputes cannot be created if a Refund already occurred on the transaction. In the same way, you cannot create a Refund for a transaction subject to a Dispute.
See the Refunds article to learn more.
Late failures
For transactions by direct debit, a dispute can be created due to a late failure. These disputes are non-contestable. See the direct debit article for more details:
Guide
Direct debit - Late failures and chargebacks
Dispute process
The dispute process varies depending on the type of dispute and the outcome (whether the platform wins or loses the dispute).
For contestable disputes, the process can be broken down into the following steps:
Chargeback
Repudiation
Platform's evidence
Issuer's response
Settlement
Best practice - Set up hooks for disputes
Due to the deadline to contest disputes, we strongly advise you to set up hooks to be notified as soon as a dispute is created. See the Dispute event types for the set of hooks allowing you to stay up to date throughout the process.
New dispute and repudiation
When a chargeback occurs, two objects are created on Mangopay’s side:
- Dispute - You can view the dispute by using the GET View a Dispute endpoint.
- Repudiation - Refers to the withdrawal of funds from the platform’s Repudiation Wallet, resulting in a negative balance. You can view the Repudiation by using the GET View a Repudiation endpoint.
If the dispute is contestable, the next step is creating the Dispute Documents and submitting them before the ContestDeadline by using the following endpoints:
- POST Create a Dispute Document and POST Create a Dispute Document Page
- PUT Submit a Dispute Document
- PUT Submit a Dispute
If the dispute is not contestable, the next step is to settle the dispute by using the following endpoint:
Note - Settling several disputes
You also have the opportunity to settle disputes via bank wire, using the POST Create a Direct Bank Wire PayIn to the Repudiation Wallet endpoint.
Contesting the dispute
When the dispute type is CONTESTABLE or RETRIEVAL, you can choose to either close it directly, or to contest it.
Note - Contesting partially the dispute
Mangopay allows you to handle cases where the platform would want to contest only part of the dispute (e.g., only one of several goods were damaged). You can do so by taking advantage of the ContestedFunds parameter.
In order to contest a dispute, you need to complete the following steps before the ContestDeadlineDate:
- Create the Dispute Documents to submit as evidence of the legitimacy of the transaction.
- Submit the dispute to Mangopay teams so that they can relay the proofs to the issuing bank.
Caution - Contesting multiple disputes for the same credit card
If the platform has multiple disputes for the same card, the platform needs to send proofs to justify the legitimacy of all the disputed transactions.
If only some of the transactions are contested, then banks will reject all of them, and all the disputes will be set as LOST.
While documents might vary depending on the dispute reason, documents must always include the following information:
- The amount debited to the end user
- The date of the payment
- The nature of the payment (the name of the platform must be visible)
If the documents submitted are not in English, please include a simple translation of the main elements in English.
Caution - Deadline set by the issuing bank
The ContestDeadlineDate is set 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.
Settling the dispute
When losing disputes, platforms need to settle their debt towards Mangopay by resetting their Repudiation Wallet balance to zero.
They need to use the dedicated Settlement Transfer endpoint to wire funds to the Repudiation Wallet.
Dispute reasons
Each dispute created is associated with a reason that determines which forms of compelling evidence the platform should submit. This information can be found in the DisputeReasonType parameter of the Dispute object.
| DisputeReasonType | Action |
|---|---|
| AUTHORISATION_DISPUTED | Evidence to provide A document with:
|
| AUTHORISATION_DISPUTED | What to do Contact the Mangopay Fraud team through the Hub for more information. |
| DUPLICATE | What to do Prove that the two transactions are both legitimate, and that you didn’t charge the customer twice for the same goods or service. Evidence to provide Two separate invoices must therefore be provided. |
| FRAUD | What to do Prove that the transaction was initiated by the cardholder. Evidence to provide
If there are two or more transactions for the same user that were not contested nor reported as fraudulent in the past 120 to 365 days before the contested payment, you also need to provide at least two of the following elements about the user who initiated the chargeback:
One of the two pieces of information provided must be the IP address or the device ID. |
| OTHER | What to do Contact the Mangopay Fraud team through the Hub for more information. |
| PRODUCT_NOT_PROVIDED | What to do Prove that the product was delivered. Evidence to provide
|
| PRODUCT_UNACCEPTABLE | What to do Prove that the product is not a counterfeit. Evidence to provide
|
| REFUND_CONVERSION_RATE | What to do Prove that the charged amount was the right one, regardless of the currency exchange rate applied. Evidence to provide The Terms and Conditions that highlight the refund policy mentioning that foreign currency exchange rates are subject to fluctuations. |
| REFUND_NOT_PROCESSED | What to do Prove that the cardholder has been reimbursed or compensated, or that the refund doesn’t apply. Evidence to provide
|
| TRANSACTION_NOT_RECOGNIZED | What to do Prove that the transaction was initiated by the cardholder. Evidence to provide
|
| UNKNOWN | Evidence to provide A document with:
|
Related resources
Endpoint
The Dispute object