Disputes

Automating Dispute Management

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:

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

Below is an example of an automation workflow 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

# 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_upload.id,
      )
      gateway.dispute.finalize(dispute.id)
    end
  else
    # Persist the webhook and follow another workflow to address the dispute
  end
end

Next Page: Testing and Go Live →