Chargeback Analytics

Retrieve time-series chargeback analytics data with configurable granularity.

GEThttps://api.zenpayz.com/merchant/api/v1/chargebacks/analytics

Bearer · API key

Request

Headers

Header	Description
Authorization REQUIRED	Bearer {api_key}
X-Signature REQUIRED	HMAC-SHA256 signature
X-Timestamp REQUIRED	ISO 8601 timestamp
X-Secret-Salt REQUIRED	Secret salt for HMAC validation
Content-Type REQUIRED	application/json
X-Merchant-Id REQUIRED	Merchant identifier
X-Request-Id REQUIRED	Unique request identifier

Query Parameters

Parameter	Type	Description
startDate OPTIONAL	string	Start date filter (ISO 8601)
endDate OPTIONAL	string	End date filter (ISO 8601)
granularity OPTIONAL	string	Time bucket size: day, week, month (default: day)
currency OPTIONAL	string	Filter by ISO 4217 currency code

Response

Success (200 OK)

{
  "success": true,
  "data": {
    "granularity": "day",
    "currency": "USD",
    "timeSeries": [
      {
        "date": "2024-01-13",
        "totalChargebacks": 3,
        "totalAmount": 450.00,
        "wonCount": 1,
        "lostCount": 1,
        "pendingCount": 1
      },
      {
        "date": "2024-01-14",
        "totalChargebacks": 5,
        "totalAmount": 820.50,
        "wonCount": 3,
        "lostCount": 0,
        "pendingCount": 2
      },
      {
        "date": "2024-01-15",
        "totalChargebacks": 2,
        "totalAmount": 175.25,
        "wonCount": 0,
        "lostCount": 1,
        "pendingCount": 1
      }
    ]
  },
  "message": "Chargeback analytics retrieved successfully",
  "error": null,
  "meta": {
    "request_id": "req_xxxxx",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "processing_time_ms": 68,
    "api_version": "v1",
    "endpoint": "GET /chargebacks/analytics",
    "user_type": "merchant"
  }
}

Error Responses

Code	HTTP	Message
VALIDATION_ERROR	400	Invalid query parameters
UNAUTHORIZED	401	Invalid API key

Examples

cURL

curl -X GET "https://api.zenpayz.com/merchant/api/v1/chargebacks/analytics?startDate=2024-01-01T00:00:00.000Z&endDate=2024-01-31T23:59:59.000Z&granularity=day&currency=USD" \
  -H "Authorization: Bearer zp_test_xxxxx" \
  -H "X-Timestamp: 2024-01-15T10:30:00.000Z" \
  -H "X-Signature: a1b2c3d4e5f6..." \
  -H "X-Secret-Salt: your_secret_salt" \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Id: merch_xxxxx" \
  -H "X-Request-Id: req_xxxxx"

JavaScript

const params = new URLSearchParams({
  startDate: '2024-01-01T00:00:00.000Z',
  endDate: '2024-01-31T23:59:59.000Z',
  granularity: 'day',
  currency: 'USD',
});

const response = await fetch(`https://api.zenpayz.com/merchant/api/v1/chargebacks/analytics?${params}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'X-Timestamp': timestamp,
    'X-Signature': signature,
    'X-Secret-Salt': secretSalt,
    'Content-Type': 'application/json',
    'X-Merchant-Id': merchantId,
    'X-Request-Id': requestId,
  },
});

const result = await response.json();
console.log(result.data.timeSeries); // [{ date: "2024-01-13", totalChargebacks: 3, ... }]
console.log(result.data.granularity); // "day"

SDK

const analytics = await zenpays.chargebacks.analytics({
  startDate: '2024-01-01T00:00:00.000Z',
  endDate: '2024-01-31T23:59:59.000Z',
  granularity: 'day',
  currency: 'USD',
});

console.log(analytics.timeSeries); // [{ date: "2024-01-13", totalChargebacks: 3, ... }]
console.log(analytics.granularity); // "day"

Related Endpoints

• Chargeback Stats
• List Chargebacks
• Get Chargeback