availability

Managing disputes via the API is only available to merchants who can access disputes in the Braintree Control Panel.

A key benefit of managing disputes via the API is the option to automate part or all of your dispute management workflow.

Automation with webhooks

One way to trigger an automated workflow is with dispute webhooks. Your flow should follow these basic steps:

  1. Inspect the incoming webhook to determine its kind
  2. If the webhook is for a newly-opened dispute, get the dispute ID from the webhook payload
  3. Use the dispute ID to find the dispute object
  4. Automatically gather and submit evidence based on your desired criteria
  5. Finalize the dispute

Below is an example of an automation workflow in Ruby for an ecommerce merchant whose products are typically shipped to customers. Because this merchant has a shipping confirmation attached to each transaction, they can automatically submit these confirmations as evidence for chargebacks with the reason Product not received.

Ruby
Copy
Copied
# Parse the incoming webhook

webhook_notification = gateway.webhook_notification.parse(
  bt_signature_param, bt_payload_param
)

# If the webhook kind is DisputeOpened, and the dispute.reason is
# "product_not_received", evidence submission can be automated
if webhook_notification.kind == Braintree::WebhookNotification::Kind::DisputeOpened
  dispute = gateway.dispute.find(webhook_notification.dispute.id)

  if dispute.reason == Braintree::Dispute::Reason::ProductNotReceived
    transaction_id = dispute.transaction.id

    result = gateway.document_upload.create(
      kind: Braintree::DocumentUpload::Kind::EvidenceDocument,
      file: File.read("/shipping_confirmations/#{transaction_id}.pdf"),
    )

    if result.success?
      gateway.dispute.add_file_evidence(
        dispute.id,
        result.document.id,
      )
      gateway.dispute.finalize(dispute.id)
    end
  else
    # Persist the webhook and follow another workflow to address the dispute
  end
end
This code snippet now uses gateway instance methods instead of class-level methods. Learn more.

We’ll add more automation examples in more server-side languages in the near future. Check back soon for updates!

Next: Testing and Go Live →

Still have questions?

If you can’t find an answer, contact our Support team.