Disputes | Mangopay docs

Introduction

Customers may question the validity of a transaction registered to their account and ask for a chargeback. 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.

Examples of chargebacks

Chargebacks can be requested for various reasons, whether it is about fraudulent transactions, disagreements between the merchant and the consumer, or processing issues.

Here are a few examples:

Unauthorized or excessive charges
Failure by the merchant to deliver merchandise
Defective merchandise
Dissatisfaction with the product(s) or service(s) received
Billing errors

Note on specific payment methods

Disputes are not supported on pay-ins to virtual IBAN and bank wires, because they are based on direct wire transfers. On direct debits, non-contestable disputes can occur due to late failures.

On the following alternative payment methods (APMs), users authenticate directly with their bank, so there is no dispute process and a low risk of unrecognized or fraudulent payments: iDEAL | Wero, MB WAY, Multibanco, Satispay, Swish. For other APMs, please check the dedicated guides as well as the information below.

Disputes can occur on card payments, including Apple Pay and Google Pay.

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.

Dispute for which the chargeback can be contested by providing proof (i.e., Dispute Documents) justifying the original transaction.

Dispute that is automatically closed after its creation, without any action possible for the platform.

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.

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

A user asks for a chargeback: the issuing bank orders the reversal of a pay-in.

Repudiation

Mangopay creates a dispute and debits the disputed funds from the platform’s Repudiation Wallet.

Platform's evidence

If the dispute is contestable, the platform sends proofs to justify the legitimacy of the transaction.

Issuer's response

Depending on the issuing bank’s response, the platform either wins or loses the dispute. In case of a win, the funds are put back into the repudiation wallet (refund).

Settlement

If the dispute is lost, the platform needs to make a Settlement Transfer from the user’s wallet (or a direct bank wire pay-in) to the Repudiation Wallet.

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:

If the dispute is not contestable, the next step is to settle the dispute by using the following endpoint:

POST Create a Settlement Transfer

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.

Common examples of evidence documents

Invoices
Signed proofs of delivery
Certificates of authenticity
Terms and conditions on refund policy

More information on which evidence to provide is available in the Dispute reasons section of this article.

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: The amount debited The date The nature of the payment (here the name of the platform must be visible) The proof that the product was received or service provided
AUTHORISATION_DISPUTED	What to do Contact the Mangopay Fraud team through the Dashboard 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 Invoice or any document with the name of the user, the amount paid, and the details of the purchase. Optionally, screenshots of the exchanges between the user and the platform or between the paying user and the recipient user. 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: The IP address The shipping address The device ID (for the phone, computer, etc. used for the payment). 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 Dashboard for more information.
PRODUCT_NOT_PROVIDED	What to do Prove that the product was delivered. Evidence to provide Invoice Signed proof of delivery
PRODUCT_UNACCEPTABLE	What to do Prove that the product is not a counterfeit. Evidence to provide The certificate of authenticity The Terms and Conditions that highlight the return policy. A screenshot of a good review, if the customer writes one after receiving the good or service. Also, if the cardholder has been reimbursed or compensated, then proof must be provided.
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 Proof of the refund transaction. Clear cancellation or return policy, with proof that it has been communicated to the customer prior to the purchase.
TRANSACTION_NOT_RECOGNIZED	What to do Prove that the transaction was initiated by the cardholder. Evidence to provide Invoice, or any document with the name of the user, the amount paid and the details of the purchase. Optionally, screenshots of the exchanges between the buyer and the platform or the buyer and the seller.
UNKNOWN	Evidence to provide A document with: The amount debited The date The nature of the payment (here the name of the platform must be visible) The proof that the product was received or service provided

Endpoint

The Dispute object