List Chargebacks

Retrieve a paginated list of chargebacks with optional filters for status, priority, date range, and more.

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

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
customerId OPTIONAL	string	Filter by customer ID
transactionId OPTIONAL	string	Filter by transaction ID
status OPTIONAL	string	Filter by status: initiated, pending_review, evidence_requested, evidence_submitted, under_review, resolved_won, resolved_lost, cancelled, expired
reason OPTIONAL	string	Filter by chargeback reason
outcome OPTIONAL	string	Filter by outcome: pending, won, lost, cancelled, expired
priority OPTIONAL	string	Filter by priority: low, medium, high, urgent
currency OPTIONAL	string	Filter by ISO 4217 currency code
startDate OPTIONAL	string	Start date filter (ISO 8601)
endDate OPTIONAL	string	End date filter (ISO 8601)
minAmount OPTIONAL	number	Minimum chargeback amount
maxAmount OPTIONAL	number	Maximum chargeback amount
urgentDeadlinesOnly OPTIONAL	boolean	Return only chargebacks with upcoming deadlines
search OPTIONAL	string	Free-text search across chargeback fields
page OPTIONAL	number	Page number (default: 1)
limit OPTIONAL	number	Items per page (default: 20)
sortBy OPTIONAL	string	Field to sort by (e.g. createdAt, amount, priority)
sortOrder OPTIONAL	string	Sort direction: asc, desc

Response

Success (200 OK)

{
  "success": true,
  "data": {
    "chargebacks": [
      {
        "chargebackId": "cb_a1b2c3d4e5f6g7h8",
        "transactionId": "txn_f8e7d6c5b4a39281",
        "amount": 150.00,
        "currency": "USD",
        "reason": "fraudulent",
        "source": "card_network",
        "status": "evidence_requested",
        "outcome": "pending",
        "priority": "high",
        "disputeDeadline": "2024-02-15T23:59:59.000Z",
        "evidenceDeadline": "2024-02-10T23:59:59.000Z",
        "createdAt": "2024-01-15T10:30:00.000Z",
        "updatedAt": "2024-01-18T14:22:00.000Z"
      },
      {
        "chargebackId": "cb_b2c3d4e5f6g7h8i9",
        "transactionId": "txn_e7d6c5b4a3928100",
        "amount": 75.50,
        "currency": "USD",
        "reason": "product_not_received",
        "source": "customer",
        "status": "resolved_won",
        "outcome": "won",
        "priority": "medium",
        "disputeDeadline": "2024-02-20T23:59:59.000Z",
        "evidenceDeadline": "2024-02-15T23:59:59.000Z",
        "createdAt": "2024-01-10T08:15:00.000Z",
        "updatedAt": "2024-01-25T16:45:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "totalItems": 42,
      "totalPages": 3
    }
  },
  "message": "Chargebacks retrieved successfully",
  "error": null,
  "meta": {
    "request_id": "req_xxxxx",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "processing_time_ms": 38,
    "api_version": "v1",
    "endpoint": "GET /chargebacks",
    "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?status=evidence_requested&priority=high&page=1&limit=20" \
  -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({
  status: 'evidence_requested',
  priority: 'high',
  page: '1',
  limit: '20',
});

const response = await fetch(`https://api.zenpayz.com/merchant/api/v1/chargebacks?${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.chargebacks); // [{ chargebackId: "cb_a1b2c3d4e5f6g7h8", ... }]
console.log(result.data.pagination.totalItems); // 42

SDK

const result = await zenpays.chargebacks.list({
  status: 'evidence_requested',
  priority: 'high',
  page: 1,
  limit: 20,
});

console.log(result.chargebacks); // [{ chargebackId: "cb_a1b2c3d4e5f6g7h8", ... }]
console.log(result.pagination.totalItems); // 42

Related Endpoints

• Create Chargeback
• Get Chargeback
• Chargeback Stats
• Chargeback Analytics