Refunds

Process refunds for INR transactions -- full, partial, and bulk. Access via zenpays.refunds.

Methods

getTemplate

Ask which beneficiary fields this transaction's payment provider actually requires, before you build a refund form. Different providers need different fields, so hard-coding them breaks the moment a transaction is routed elsewhere.

const template = await zenpays.refunds.getTemplate('txn_xxx')

if (template.requiredFields.length > 0) {
  // Render a form for exactly the fields this provider needs
}
else {
  // Nothing extra needed — refund directly
  await zenpays.refunds.create({ transactionId: 'txn_xxx' })
}

// Partial refund: pass the amount to preview fees and limits for that amount
const partial = await zenpays.refunds.getTemplate('txn_xxx', 500)

Parameter	Type	Required	Description
transactionId	string	Yes	Transaction to be refunded
amount	number	No	Refund amount. Omit for a full refund

Returns a RefundPreview:

Field	Type	Description
tspProvider	string	Provider slug, e.g. sulifu_pay, stripe
tspDisplayName	string	Human-readable provider name
requiredFields	RefundFieldDefinition[]	Fields that must be supplied to create
optionalFields	RefundFieldDefinition[]	Fields that may be supplied
oneOfGroups	string[][]	Groups where at least one complete group is required
prefilled	object	Values carried over from the original transaction

preview

Alias for getTemplate, taking the amount as an options object instead of a positional argument.

const preview = await zenpays.refunds.preview('txn_xxx', { amount: 500 })

create

Create a refund. Provide the customer's bank account details so they receive the funds via IMPS.

JavaScript

// Full refund
const refund = await zenpays.refunds.create({
  transactionId: 'txn_xxx',
  reason: 'Customer request',
  beneficiaryEmail: 'customer@example.com',
  beneficiaryAccount: '50100012345678',
  beneficiaryIfsc: 'HDFC0001234',
})

// Partial refund
const partialRefund = await zenpays.refunds.create({
  transactionId: 'txn_xxx',
  amount: 500,
  reason: 'Partial item return',
  beneficiaryEmail: 'customer@example.com',
  beneficiaryAccount: '91020034567890',
  beneficiaryIfsc: 'SBIN0001234',
  beneficiaryName: 'Priya Sharma',
})

Python

# Full refund
refund = zenpays.refunds.create({
    "transactionId": "txn_xxx",
    "reason": "Customer request",
    "beneficiaryEmail": "customer@example.com",
    "beneficiaryAccount": "50100012345678",
    "beneficiaryIfsc": "HDFC0001234",
})

# Partial refund
partial_refund = zenpays.refunds.create({
    "transactionId": "txn_xxx",
    "amount": 500,
    "reason": "Partial item return",
    "beneficiaryEmail": "customer@example.com",
    "beneficiaryAccount": "91020034567890",
    "beneficiaryIfsc": "SBIN0001234",
    "beneficiaryName": "Priya Sharma",
})

Parameters:

Field	Type	Required	Description
transactionId	string	Yes	Transaction to refund
reason	string	Yes	Refund reason
amount	number	No	Partial refund amount (omit for full refund)
beneficiaryEmail	string	Yes	Customer email
beneficiaryAccount	string	Yes	Bank account number
beneficiaryIfsc	string	Yes	IFSC code (e.g. HDFC0001234)
beneficiaryName	string	No	Beneficiary name
beneficiaryMobile	string	No	Mobile number
beneficiaryCity	string	No	City
customerId	string	No	Customer ID (auto-resolved if omitted)

Try it out

Test refund creation interactively using the API Simulator.

---

bulkUpload

Create multiple refunds in a single call.

JavaScript

const result = await zenpays.refunds.bulkUpload({
  refunds: [
    {
      transactionId: 'txn_aaa',
      reason: 'Customer request',
      beneficiaryEmail: 'john@example.com',
      beneficiaryAccount: '50100012345678',
      beneficiaryIfsc: 'HDFC0001234',
    },
    {
      transactionId: 'txn_bbb',
      amount: 500,
      reason: 'Partial refund',
      beneficiaryEmail: 'jane@example.com',
      beneficiaryAccount: '91020034567890',
      beneficiaryIfsc: 'SBIN0001234',
    },
  ],
})

Python

result = zenpays.refunds.bulk_upload({
    "refunds": [
        {
            "transactionId": "txn_aaa",
            "reason": "Customer request",
            "beneficiaryEmail": "john@example.com",
            "beneficiaryAccount": "50100012345678",
            "beneficiaryIfsc": "HDFC0001234",
        },
        {
            "transactionId": "txn_bbb",
            "amount": 500,
            "reason": "Partial refund",
            "beneficiaryEmail": "jane@example.com",
            "beneficiaryAccount": "91020034567890",
            "beneficiaryIfsc": "SBIN0001234",
        },
    ],
})

---

get

JavaScript

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

Python

refund = zenpays.refunds.get("refund_xxx")

---

list

JavaScript

const { data } = await zenpays.refunds.list({
  status: 'completed',
  currency: 'INR',
  limit: 20,
})

Python

result = zenpays.refunds.list({"status": "completed", "currency": "INR", "limit": 20})

---

cancel

Cancel a refund that is still in pending_approval status.

JavaScript

const cancelled = await zenpays.refunds.cancel('refund_xxx')

Python

cancelled = zenpays.refunds.cancel("refund_xxx")

---

getStats

JavaScript

const stats = await zenpays.refunds.getStats('2026-01-01', '2026-12-31', 'INR')

Python

stats = zenpays.refunds.get_stats("2026-01-01", "2026-12-31", "INR")

---

getAnalytics

JavaScript

const analytics = await zenpays.refunds.getAnalytics({
  startDate: '2026-01-01',
  endDate: '2026-12-31',
  granularity: 'day',
  currency: 'INR',
})

Python

analytics = zenpays.refunds.get_analytics({
    "startDate": "2026-01-01",
    "endDate": "2026-12-31",
    "granularity": "day",
    "currency": "INR",
})

---

export

JavaScript

const downloadUrl = await zenpays.refunds.export(
  { status: 'completed', currency: 'INR' },
  'csv'
)

Python

download_url = zenpays.refunds.export({"status": "completed", "currency": "INR"}, "csv")