Refunds API

The Refunds API allows you to create and manage refunds.

Methods

create

Create a refund for a transaction.

const refund = await zenpays.refunds.create({
  transactionId: 'txn_xxx',
  amount: 500, // Partial refund
  reason: 'Customer request',
})

Parameters:

Field	Type	Required	Description
transactionId	string	Yes	Transaction to refund
amount	number	No	Amount to refund (full if not specified)
reason	string	No	Reason for refund
customerId	string	No	Customer ID
metadata	Record<string, unknown>	No	Custom metadata

Returns: Refund

---

createBatch

Create multiple refunds at once.

const result = await zenpays.refunds.createBatch({
  refunds: [
    { transactionId: 'txn_1', reason: 'Duplicate charge' },
    { transactionId: 'txn_2', amount: 500, reason: 'Partial refund' },
  ],
})

console.log(`Succeeded: ${result.succeeded}, Failed: ${result.failed}`)

Returns: BatchRefundResponse

---

get

Get a refund by ID.

const refund = await zenpays.refunds.get('ref_xxx')

---

list

List refunds with filters.

const { data } = await zenpays.refunds.list({
  status: 'completed',
  from: '2024-01-01',
  limit: 50,
})

---

cancel

Cancel a pending refund.

const refund = await zenpays.refunds.cancel('ref_xxx')

---

getStats

Get refund statistics.

const stats = await zenpays.refunds.getStats('2024-01-01', '2024-12-31')
console.log('Total refunded:', stats.completedAmount)

Types

Refund

interface Refund {
  id: string
  merchantId: string
  transactionId: string
  customerId?: string
  amount: number
  currency: string
  status: RefundStatus
  reason?: string
  failureReason?: string
  processedAt?: string
  createdAt: string
}

RefundStatus

type RefundStatus
  = | 'pending'
    | 'processing'
    | 'completed'
    | 'failed'
    | 'cancelled'