Disputes Deep Dive


As a Clear API partner to WePay, 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_descriptor 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.

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_descriptor set on the merchant’s WePay account.

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

  • Set "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
  • Build out a merchanism for merchants to identify shipped orders as delivered
  • Once an order is shipped or delivered, send a POST /payments/{id}/capture request
    • 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 facillitate 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 this 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 time lines.

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. Thoroughly and clearly document your return/exchange policy, and p

Make sure your refund process itself is quick and easy so that it doesn’t add to customer frustration. Issuing refunds is preferable to receiving a dispute; the dispute process can be lengthy and time-consuming. Additionally, WePay monitors chargeback rates on a merchant level, and may need to close a merchant’s account if their chargeback rate exceeds

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

This pracitce 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:

chargeback flow

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


Occassionally, 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), WePay will close the chargeback in the payer’s favor.

Simultaneous Refunds and Disputes

Ocassionally, a transaction will be refunded and receive a dispute at the same time. When this happens, WePay automatically begins the challenge process. That being said, merchants should still submit supporting documentation proving that the refund was issued in order to enhance WePay’s re-presentment efforts.