Merchants using Bolt’s Disputes product can choose to retrieve information about their disputes via webhook.

On dispute creation, Bolt sends a payload with basic dispute information (chargeback amount, transaction details, etc.) to the provided endpoints. On terminal dispute scenarios (dispute resolution such as won, loss, etc.), we will send a message to the provided endpoint(s).

Step 1: Configure Webhooks in the Dashboard

Create the link between the Merchant’s server and the Bolt servers.

1. In your Merchant Dashboard, add the webhook url(s) where you will receive notifications. This url should be generally available to the public, but you will need to verify the authenticity of every request to ensure that the webhook notification is getting sent from Bolt.
2. Notify Bolt so Bolt can register those endpoint(s) and assign them to the WebhookTypeDisputeCreated and WebhookTypeDisputeTerminal webhook types.

Step 2: Receive Dispute Payload

Bolt will be sending the following payloads:

• Dispute Created
• Dispute Terminal

Dispute Created

This payload sends when a new dispute for a transaction is entered into our system.

A single transaction can contain multiple disputes. If a shopper disputes one item at some point in time, they can always dispute another one at a different point in time which would create two disputes for the same transaction.

  {
    "type": "dispute_created",
    "object": "dispute",
    "data": {
      "dispute_inputs": {
        "arn": "123456789",
        "chargeback_amount": 21.58,
        "chargeback_at": "2023-01-16T22:52:41.140485Z",
        "chargeback_currency": "USD",
        "credit_card_company": "VISA",
        "gateway": "Bolt",
        "id": "123456789", // self-service disputes merchants should use this in rebuttal letters to identify proper case to Bolt
        "reason_code": "13.1",
        "reason_description": "Collaboration Flow - Consumer - Merchandise/Services Not Received",
        "respond_by": "2023-09-16T00:00:58.833346Z",
        "transaction_id": "P4NT-Z6QT-6TW7",
        "type": "cb",
        "card_issuer": "Wells Fargo Bank"
      }
    }
  }

Dispute Terminal

This payload sends when the dispute has reached a terminal (resolved) state. You can have multiple terminal states in the process of a dispute. Ultimately, this means a won/lost determination at specific states (First Chargeback, Pre-Arbitration, or Arbitration).

  {
    "type": "dispute_terminal",
    "object": "dispute",
    "data": {
      "dispute_inputs": {
        "arn": "123456789",
        "chargeback_amount": 80.33,
        "chargeback_at": "2023-01-16T22:52:41.140485Z",
        "chargeback_currency": "USD",
        "credit_card_company": "VISA",
        "dispute_details": {
          "case_id": "123456789",
          "dispute_type": "arbitrary_court",
          "disputed_at": "2023-06-06T21:14:44.206176Z",
          "expected_resolution_date": "2023-09-16T00:00:58.833346Z",
          "status": "won"
        },
        "gateway": "Bolt",
        "id": "123456789", // self-service disputes merchants should use this in rebuttal letters to identify proper case to Bolt
        "reason_code": "13.1",
        "reason_description": "Collaboration Flow - Consumer - Merchandise/Services Not Received",
        "respond_by": "2023-09-16T00:00:58.833346Z",
        "transaction_id": "H348-MKW7-JTHZ",
        "type": "cb",
        "card_issuer": "Wells Fargo Bank"
      }
    }
  }

Step 3: Configure Response to Bolt

It is very important to return the appropriate response to us upon successful ingestion of the dispute payload. Otherwise, Bolt will resend the notification with a retry mechanism.

{
  "status": "success"
}

Testing Checklist

To ensure successful implementation:

• Expose public endpoints to Bolt that will consume the two dispute webhooks.
• Follow our documentation on authenticating a webhook to protect the exposed endpoint.