Disputes Deep Dive


As a WePay partner, you must handle disputes for merchants. This is an educational resource on disputes in general, in addition to UI guidance and dispute-handling code snippets.

Avoid Disputes

Disputes can be a burden for merchants, and there are a few best practices that you, the platform, can implement to help avoid them in the first place:

1. Recognition

Many payers file complaints because they do not recognize a charge. To improve recognition rates, be sure to send a descriptive value for the account statement_description parameter. In practice, provide a field during onboarding asking merchants for the name of their store, business, etc. that their clients will recognize for use on card statements. If this field is not specified, it will be assigned null.

Additionally, remind payers what the charge will look like on their statement during checkout; all charges will be prefixed with WPY* and will contain the statement_description set on the merchant's WePay account. If statement_description is not specified and defaults to null, the charges will display as WPY* {name_of_merchant}.

A strategy to increase recognition specifically for shipped goods is to align the timing of delivery and capturing transactions. This will involve:

  • Setting "credit_card.auto_capture": false on POST /payments requests
  • Requiring merchants to, at minimum, ship items within 7 days of purchase
    • Ideally, items should be delivered within 7 days of purchase
  • Building out a mechanism for merchants to identify shipped orders as delivered
  • Sending a POST /payments/{id}/capture request once an order is shipped or delivered
    • At this point, the charge will appear on the payer's statement

While implementing this strategy, it's important not to capture a payment too long after delivery in order to help ensure charge recognition. It's also important to capture payments within 7 days of authorization; attempts to capture the payment more than 7 days after authorization will fail, and the payment must be re-submitted.

2. Charge identification tool

Even with effective descriptors, some card holders may still not recognize a charge. Provide a look up tool where payers can use identifying details like payment date, amount, and/or the last 4 digits of the card number to provide a reference number. Payers should also be able to login to see their payment history (along with reference numbers and merchant contact information), with the option to view a static receipt.

3. Keep records

Keep all tracking numbers, signed contracts and receipts, payer login/checkout IPs (in place of signed physical receipts); also keep records of transaction details for merchants (records should go back at least 2 years for chargeback purposes).

4. Merchant terms of service

The merchant's terms of service, including refund policies, should be prominently posted on their site, presented before checkout, and made available on electronic receipts.

You, as the platform, should require merchants to submit their terms of service to you and to keep them current. From there, you can ensure that their terms of service are present on their platform-hosted page/store, before payer checkout, and on payer receipts.

5. Merchant customer service contact

Payers should be able to easily reach out to the merchant for support related to their goods/services. To facilitate this best practice, require merchants to submit their support contact email address and/or phone number to your platform. Again, you can ensure that this contact information is sufficiently present on the merchant's platform-hosted page/store and on payer receipts.

Educate Merchants

Part of avoiding disputes is educating your merchants on best practices. Download and host the below guide of recommended documents to upload when challenging a dispute, based on dispute reason category:

Feel free to host these best practices on your platform for merchants to implement and help avoid disputes:

1. Customer service

Provide a customer service phone number and/or email address, and make this contact readily available on your site and on payer receipts.

Provide prompt and responsive customer service. Communicate with customers regarding any delays in shipping, changes to the order, etc.

Set realistic expectations with payers of shipping timelines.

2. Accurate item/service descriptions

Make certain that descriptions and promises about products match reality. A product or service not meeting expectations is one of the grounds for a chargeback.

3. Ask for ID for in person transactions

This practice will reduce fraudulent and unauthorized transactions.

4. Issuing refunds is preferable to receiving a dispute

Make returns and exchanges straightforward by thoroughly and clearly documenting your return/exchange policy, and providing prompt responses to refund requests.

Make sure your refund process itself is quick and easy so that it doesnt add to customer frustration.

Issuing refunds is preferable to receiving a dispute; the dispute process can be lengthy and time-consuming. Additionally, we monitor chargeback rates on a merchant level, and may need to close a merchant's account if their chargeback rate exceeds 2% of their total processing volume.

5. Provide a summary of services, which is signed by the customer

This practice helps align customer expectations with reality, in addition to document challenging a dispute.

Have your own audit and accounting teams go over summaries and orders to spot issues like double charging.

Dispute Edge Cases

As a reminder, the overall charge back life cycle is as follows:

Files a complaint
Investigates the claim
Submits a chargeback
Takes further action based
on cardholder's response
Transmits chargeback
Supplements information
with notifications and
status updates
Debits merchant
Notifies platform
Investigates the case
Reviews any documents from the merchant
Credits the merchant based on updates
Notifes merchant
Provides UI to submit documents
Provides regular updates on status
Provides documents
Reviews chargeback
progress updates
Sends documents to
WePay via API
Prepares evidence
Contests chargeback on behalf of the merchant
Works with processor for adjustments
Reviews evidence
Updates case with new information
Transmits updates
Reviews evidence
Provides decision
Updates case with decision
Reviews decision; Transmits
information to card holder
Card Holder
Issuing Bank
Card Network

Disputes will typically be resolved one way or another after the merchant either concedes to or challenges the dispute.


Occasionally, a card holder will submit new information about the dispute after the card network closes the case in the merchant's favor. When this happens, a second dispute (also known as a pre-arbitration chargeback) will be issued. Due to the high fees and potential penalties associated with going into arbitration (i.e. challenging the second chargeback), we will close the chargeback in the payer's favor.

Differing Dispute and Transaction Amounts

At times, a dispute amount will differ from the amount of the initial transaction. There are two reasons for this: partial disputes and exchange rate fluctuations.

  • Partial disputes occur when the card holder informs the card issuer that they were overcharged.
  • Exchange rate fluctuations can occur when the card holder's account is in a differnt currency from the merchant's account. At the time of payment, we automatically convert the payment into the merchant's currency using the current exchange rate. If a dispute occurs, we use the current exchange rate at the time of the dispute to convert the dispute to the merchant's currency. If the exchange rate differs between the time of payment and the time of dispute, the dispute amount will differ from the transaction amount.

Simultaneous Refunds and Disputes

Occasionally, a transaction will be refunded and receive a dispute at the same time. When this happens, we automatically begin the challenge process. That being said, merchants should still submit supporting documentation proving that the refund was issued in order to enhance our representment efforts.