List Refunds

Retrieve a paginated list of refunds with optional filters.

GEThttps://api.zenpayz.com/merchant/api/v1/refund-intents

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

Query Parameters

Parameter	Type	Description
page OPTIONAL	integer1	Page number
limit OPTIONAL	integer20	Items per page (max 100)
customerId OPTIONAL	string-	Filter by customer
transactionId OPTIONAL	string-	Filter by transaction
status OPTIONAL	string-	Filter by status
startDate OPTIONAL	string-	Start date (ISO 8601)
endDate OPTIONAL	string-	End date (ISO 8601)
currency OPTIONAL	string-	Filter by currency

Refund Status Values

Status	Description
requires_beneficiary	Beneficiary details needed — re-submit with required fields
pending_approval	Awaiting admin approval
approved	Approved, being sent to provider
processing	Being processed by payment provider
completed	Refund completed successfully
failed	Refund failed — check failureReason
rejected	Rejected by admin
cancelled	Cancelled before processing

Response

Success (200 OK)

{
  "success": true,
  "data": [
    {
      "refundId": "refund_1774683026458_oann5ibjf",
      "merchantId": "ZP_FIN_1774592804_0781001264",
      "customerId": "cust_mn8yfewm_37ntht",
      "transactionId": "txn_1774619159530_1_mn8yfmph_5iwb9b",
      "paymentIntentId": "pi_1774619159530_66d8s8v25",
      "amount": 30,
      "originalAmount": 100,
      "currency": "INR",
      "refundType": "partial",
      "status": "pending_approval",
      "tspProvider": "sulifu_pay",
      "externalRefundId": null,
      "reason": "Customer requested refund",
      "createdAt": "2026-03-28T07:30:26.479Z",
      "completedAt": null,
      "failureReason": null,
      "processingTimeMs": null
    }
  ],
  "metadata": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 45,
      "totalPages": 3
    }
  }
}

Examples

cURL

curl -X GET "https://api.zenpayz.com/merchant/api/v1/refund-intents?status=completed&limit=50" \
  -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"

JavaScript

const crypto = require('crypto');

const apiKey = process.env.ZENPAYS_API_KEY;
const secretSalt = process.env.ZENPAYS_SECRET_SALT;
const timestamp = new Date().toISOString();

const signature = crypto
  .createHmac('sha256', secretSalt)
  .update(timestamp + '{}')
  .digest('hex');

const params = new URLSearchParams({
  status: 'completed',
  limit: '50',
});

const response = await fetch(
  `https://api.zenpayz.com/merchant/api/v1/refund-intents?${params}`,
  {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'X-Timestamp': timestamp,
      'X-Signature': signature,
      'X-Secret-Salt': secretSalt,
    },
  }
);

const result = await response.json();
console.log(`Found ${result.pagination.total} refunds`);

SDK (Recommended)

const { data, total } = await zenpays.refunds.list({
  status: 'completed',
  limit: 50,
});

console.log(`Found ${total} refunds`);

Related Endpoints

• Confirm Refund Intent
• Get Refund
• Refund Statistics