> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bafanglaicai88.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Describe only the public 123hub merchant API documented on this site. The primary endpoint is POST /public/api/multihub/v1.
> Preserve API method names, field names, header names, and error codes exactly as documented. Do not invent endpoints or parameters.
> Treat every amount as an integer in minor units unless a page explicitly states otherwise.
> Never expose, request, or fabricate a merchant secret key. The SDK pages contain reference implementations, not official SDK packages.

# Chargeback history

> Read merchant-scoped chargeback history, summaries, and evidence attachments

# Chargeback history

Chargeback methods expose read-only dispute history and safe evidence for your payments. Creation, evidence upload, status changes, and operational notes remain operator-managed.

<Info>
  **Prerequisites:** use an API credential with `chargebacks.read`. New
  chargeback webhook subscriptions are opt-in and are not added to existing
  subscriptions automatically.
</Info>

## Methods

| Method                        | Purpose                                                        |
| ----------------------------- | -------------------------------------------------------------- |
| `chargeback.get`              | Read one chargeback by its UUID `h_id`                         |
| `chargeback.list`             | List merchant chargebacks, optionally filtered by payment/date |
| `chargeback.summary`          | Aggregate counts by reason and count/amount by currency        |
| `chargeback.attachments.list` | List safe evidence metadata for one chargeback                 |
| `attachment.get`              | Obtain a five-minute download URL for visible evidence         |

All methods require `chargebacks.read` and are sent to `POST /public/api/multihub/v1` without `service_id`.

## Get a chargeback

Chargebacks intentionally have no merchant `c_id`; use the server-generated UUID directly.

<CodeGroup>
  ```bash cURL theme={null}
  BODY='{"method":"chargeback.get","params":{"h_id":"f1c5d252-953a-48c7-b8f7-c67dc946413a"}}'
  SECRET='your_secret_key'
  HASH=$(printf '%s%s' "$BODY" "$SECRET" | openssl dgst -sha512 -r | awk '{print $1}')
  curl -X POST 'https://api.bafanglaicai88.com/public/api/multihub/v1' \
    -H 'Content-Type: application/json' -H 'X-Data-Application-Id: 1' \
    -H "X-Data-Hash: $HASH" -H "X-Data-Timestamp: $(date +%s)" \
    -H "X-Data-Nonce: $(uuidgen)" --data-binary "$BODY"
  ```

  ```python Python theme={null}
  import hashlib, json, time, uuid, requests

  payload = {"method": "chargeback.get", "params": {
      "h_id": "f1c5d252-953a-48c7-b8f7-c67dc946413a",
  }}
  body = json.dumps(payload, separators=(",", ":")); secret = "your_secret_key"
  response = requests.post("https://api.bafanglaicai88.com/public/api/multihub/v1", data=body, headers={
      "Content-Type": "application/json", "X-Data-Application-Id": "1",
      "X-Data-Hash": hashlib.sha512((body + secret).encode()).hexdigest(),
      "X-Data-Timestamp": str(int(time.time())), "X-Data-Nonce": str(uuid.uuid4()),
  }, timeout=30)
  print(response.json())
  ```

  ```javascript Node.js theme={null}
  import crypto from "node:crypto";

  const body = JSON.stringify({
    method: "chargeback.get",
    params: {
      h_id: "f1c5d252-953a-48c7-b8f7-c67dc946413a",
    },
  });
  const secret = "your_secret_key";
  const response = await fetch("https://api.bafanglaicai88.com/public/api/multihub/v1", {
    method: "POST",
    body,
    headers: {
      "Content-Type": "application/json",
      "X-Data-Application-Id": "1",
      "X-Data-Hash": crypto
        .createHash("sha512")
        .update(body + secret)
        .digest("hex"),
      "X-Data-Timestamp": String(Math.floor(Date.now() / 1000)),
      "X-Data-Nonce": crypto.randomUUID(),
    },
  });
  console.log(await response.json());
  ```
</CodeGroup>

Example projection:

```json theme={null}
{
  "success": true,
  "result": {
    "identifiers": { "h_id": "f1c5d252-953a-48c7-b8f7-c67dc946413a" },
    "payment": { "h_id": "3c3708bc-78d6-4bcb-b626-43dc9c05d0d6" },
    "amount": "12500",
    "currency": "INR",
    "reason": "customer_dispute",
    "description": "Cardholder dispute received",
    "bank_reference": "CB-2026-1042",
    "chargeback_at": "2026-07-14T08:30:00.000Z",
    "created_at": "2026-07-14T09:00:00.000Z",
    "updated_at": "2026-07-14T09:00:00.000Z"
  },
  "request_id": "0d606423-5eb5-489d-b1d8-83c6eef0ae45",
  "processing_time": 12
}
```

`amount` is a digit-string in minor units. Reasons can be `fraud`, `duplicate`, `product_not_received`, `customer_dispute`, `bank_reversal`, or `other`.

## List and summarize

`chargeback.list` accepts an optional payment reference, ISO 8601 `created_from`/`created_to`, `limit`, and `cursor`:

```json theme={null}
{
  "method": "chargeback.list",
  "params": {
    "payment": { "c_id": "order-8401" },
    "created_from": "2026-07-01T00:00:00Z",
    "limit": 25
  }
}
```

Results contain `items` and `next_cursor`; `total` is omitted. `chargeback.summary` returns:

```json theme={null}
{
  "by_currency": {
    "INR": { "count": 3, "amount": "37500" }
  },
  "by_reason": {
    "customer_dispute": 2,
    "duplicate": 1
  }
}
```

Currency totals remain digit-strings in minor units.

## Evidence attachments

List evidence metadata using the parent chargeback UUID:

```json theme={null}
{
  "method": "chargeback.attachments.list",
  "params": {
    "chargeback_h_id": "f1c5d252-953a-48c7-b8f7-c67dc946413a",
    "limit": 25
  }
}
```

Each item contains only `identifiers.h_id`, `name`, `mime_type`, `size`, and `created_at`. Pass its `h_id` to `attachment.get` to receive a five-minute signed `download_url`. Object keys, staff identities, raw metadata, internal notes, and payout details are never returned.

## Error handling

|    Code | HTTP | Meaning                                               | Recovery                                      |
| ------: | :--: | ----------------------------------------------------- | --------------------------------------------- |
| `12001` |  404 | Chargeback is missing or belongs to another merchant  | Verify the UUID and credential                |
| `13001` |  404 | Evidence is missing or not visible through its parent | Refresh the attachment list                   |
|  `3008` |  403 | Credential lacks `chargebacks.read`                   | Use an appropriately scoped key               |
|  `2002` |  503 | Support data is temporarily unavailable               | Retry the read with backoff and a fresh nonce |

## Best practices

* Store chargeback `h_id` and payment `h_id` together for reconciliation.
* Treat webhook events as change notifications and query the current projection for details.
* Download evidence only when needed; signed URLs expire after five minutes.
* Never infer that `404` proves an identifier is unused globally; not-found behavior is tenant-safe.