# 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.
```typescript
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`](#gettemplate), taking the amount as an options object instead of a positional argument.
```typescript
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.
```typescript
// 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) |
:::tip Try it out
Test refund creation interactively using the [API Simulator](https://merchant-sample.zenpayz.com/api-simulator/refund-intents/create).
:::
---
### bulkUpload
Create multiple refunds in a single call.
```typescript
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
```typescript
const refund = await zenpays.refunds.get('refund_xxx')
```
```python
refund = zenpays.refunds.get("refund_xxx")
```
---
### list
```typescript
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.
```typescript
const cancelled = await zenpays.refunds.cancel('refund_xxx')
```
```python
cancelled = zenpays.refunds.cancel("refund_xxx")
```
---
### getStats
```typescript
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
```typescript
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
```typescript
const downloadUrl = await zenpays.refunds.export(
{ status: 'completed', currency: 'INR' },
'csv'
)
```
```python
download_url = zenpays.refunds.export({"status": "completed", "currency": "INR"}, "csv")
```