Disputes

Testing and Go Live

Availability
Managing disputes via the API is only available to merchants who can access disputes in the Braintree Control Panel.
We strongly recommend that you test your dispute workflows in the sandbox before using them in production.

You can use the following test card number in the sandbox to create sale transactions of any amount* that are instantly disputed:

Test ValueCard TypeDescription
4023898493988028Visa Creates a settled sale transaction that has a dispute with an open status

*Some transaction amounts trigger specific dispute behavior in the sandbox; see creating test disputes that require compelling evidence below.

In addition to creating a test dispute, using this test card to create sandbox transactions will allow you to:

  • Receive a dispute email notification
  • Receive a Dispute Opened webhook (if set up)
  • Search for or find the dispute in the Control Panel or via the API
  • Respond to the dispute in the Control Panel or via the API with specific evidence that will update the dispute status to won or lost
Creating test disputes that require compelling evidenceAnchorIcon

The following transaction amounts will set the dispute Transaction: Sale accordingly:

AmountDispute Reason Code
83.0083 Visa Fraud
10.401040 Visa Fraud
13.101310 Visa Fraud
70.307030 Discover Fraud
Creating test Venmo disputesAnchorIcon

If you have Venmo enabled, you can also create disputes for Venmo transactions in the sandbox.

Creating a disputed test transactionAnchorIcon

Use Transaction: Sale to create a test transaction via the API. When specifying a credit card number for the test transaction, you can use the test card number above.

  1. Ruby
result = gateway.transaction.sale(
 :amount => '10.00',
 :credit_card => {
   :expiration_date => '01/2022',
   :number => Braintree::Test::CreditCardNumbers::Disputes::Chargeback
 },
)

if result.success?
  # Do something with the result.transaction.disputes
end

Simulating a won disputeAnchorIcon

Specify the string "compelling_evidence" when adding text evidence in the sandbox. Once finalized, this will update the dispute status to won.

  1. Ruby
dispute = gateway.dispute.find("a_dispute_id")

gateway.dispute.add_text_evidence(dispute.id, "compelling_evidence")

gateway.dispute.finalize(dispute.id)

Simulating a lost disputeAnchorIcon

Specify the string "losing_evidence" when adding text evidence in the sandbox. Once finalized, this will update the dispute status to lost.

  1. Ruby
dispute = gateway.dispute.find("a_dispute_id")

gateway.dispute.add_text_evidence(dispute.id, "losing_evidence")

gateway.dispute.finalize(dispute.id)

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more