--- page_source: https://juspay.io/sea/docs/dashboard-sea/docs/payments/batch-refunds page_title: Batch Refunds --- # Batch Refunds ## Overview The Batch Refunds module provides comprehensive bulk refund processing capabilities for processing multiple refunds simultaneously through CSV file uploads. It offers real-time progress tracking, status monitoring, and detailed reporting for all refund operations processed through the Juspay payment platform. This module is designed for a wide range of users, including: * **Operations Teams** : For processing large volumes of refunds efficiently and monitoring refund processing performance across different payment methods and gateways. * **Finance Teams** : For bulk refund processing, financial reconciliation, and tracking refund amounts across multiple transactions with detailed audit trails. * **Customer Support** : To process customer refund requests in bulk, track refund status, and provide accurate updates to customers on refund processing. ## Accessing the Module 1. **Log in** to the Juspay dashboard. 2. From the main navigation menu on the left, click on **Payments** . 3. Select **Bulk Operations** from the Payments submenu. 4. Click on the **Refunds** tab from the bulk operations navigation. 5. The navigation URL for this module is [https://portal.juspay.in/batch/batch-refunds](https://portal.juspay.in/batch/batch-refunds). ![Image](https://dth95m2xtyv8v.cloudfront.net/tesseract/assets/dashboard/Screenshot%202025-09-25%20at%2012.41.38%E2%80%AFPM.png) *Bulk Operations - Batch Refunds* ## Step-by-Step Usage Instructions ### Creating Batch Refunds #### Step 1: Access the Batch Refunds Interface 1. Navigate to the Batch Refunds module using the steps above. 2. You will see the main dashboard with a description: "This module helps in creating refunds in bulk using a file upload. It provides a holistic view of the files uploaded. Upon clicking the filename in the table below a detailed view of each refund uploaded is displayed." 3. The interface displays any previously uploaded batch refund files in a table format. #### Step 2: Initiate New Batch Refund Upload 1. Click the **"Create Batch Refunds"** button (visible only to users with appropriate permissions). 2. If maker-checker workflow is enabled for your account, you will first see a description modal: * Enter a description for the batch refund request in the text field. * Click **"Submit"** to proceed to the file upload interface. 3. If maker-checker is not enabled, you will directly access the file upload interface. ![Image](https://dth95m2xtyv8v.cloudfront.net/tesseract/assets/dashboard/Screenshot%202025-09-25%20at%2012.47.23%E2%80%AFPM.png) *Batch Refunds* #### Step 3: Prepare and Upload CSV File 1. **Download Sample File** : Click on the sample file link to download the CSV template (`batch_refunds_sample.csv`). 2. **Prepare Your Data** : Fill in your refund data following the CSV field specifications (see table below). 3. **File Limitations** : * Maximum 1000 rows per file * CSV format only * File size limitations apply 4. **Upload Process** : * Click **"Choose File"** or drag and drop your CSV file * The system validates the file format and structure * Mandatory fields are checked (Order ID and Amount) * Column types are validated (Order ID as String, Amount as Number) #### Step 4: File Processing and Validation 1. **File Validation** : The system performs the following checks: * CSV format validation * Mandatory field presence (order_id, amount) * Data type validation for each column * Row count validation (maximum 1000 rows) 2. **Error Handling** : If validation fails, specific error messages are displayed: * Missing mandatory fields * Invalid data types * File format errors * Row limit exceeded 3. **Successful Upload** : Upon successful validation: * File is queued for processing * Batch ID is generated * Initial status is set to processing #### Step 5: Monitor Processing Status 1. **Status Indicators** : * **ACCEPTED** : Successfully processed refunds (Green indicator) * **FAILED** : Failed refund attempts (Red indicator) * **QUEUED** : Refunds waiting in processing queue (Blue indicator) ![Image](https://dth95m2xtyv8v.cloudfront.net/tesseract/assets/dashboard/Screenshot%202025-09-25%20at%201.43.30%E2%80%AFPM.png) *Batch Refunds - List View* ### Monitoring and Managing Batch Refunds #### Viewing Batch Refund Details 1. **Table View** : The main interface displays all uploaded batch files with: * File Name: Name of the uploaded CSV file * File Upload Status: Current processing status with color-coded labels * Amount: Sum of refund amounts in the uploaded file (displayed in INR currency) * Date Created: File upload timestamp * Last Modified: Last update timestamp * Total Tasks: Number of refund requests in the file * Tasks Progress: Visual progress bar showing completion status * Actions: Sync with Gateway button for manual synchronization 2. **Detailed View** : Click on any filename to access detailed information: * **Batch Details Card** : Expandable/collapsible interface showing: * Batch ID: Unique identifier for the uploaded file * Date Created and Date Updated timestamps * Total Amount with currency formatting * Current status with color-coded indicators * **Progress Statistics** : Individual task counts for: * Total Accepted Tasks: Successfully processed refunds * Total Rejected Tasks: Failed refund attempts * Total Queued Tasks: Refunds in processing queue ![Image](https://dth95m2xtyv8v.cloudfront.net/tesseract/assets/dashboard/Screenshot%202025-09-25%20at%201.42.49%E2%80%AFPM.png) *Batch Refunds - Detailed View* #### Search and Filter Capabilities 1. **File Name Search** : * Use the search input field with search icon * Enter filename to filter results * Search is case-sensitive and supports partial matches * Clear search using the cross icon 2. **Table Sorting** : * Click column headers to sort data * Available sorting for: File Name, Status, Amount, Date Created, Total Tasks * Toggle between ascending and descending order ### Data Export and Download #### Downloading Processed Data 1. **Access Download** : Click the **"Download Data"** button in the batch details view. 2. **CSV Export** : Downloads include: * Serial numbers (S.No column) * All processed refund data with the following headers: * Order/Transaction Id * Amount * Refund Status * Unique Id * GW Transaction Id * Udf1 through Udf10 (User Defined Fields) * Task Status * Refund Type * Error Message * Created At * Updated At 3. **File Format** : * CSV format with comma-separated values * Filename format: `batch_refund.csv` * Includes header row with column names #### Gateway Synchronization 1. **Manual Sync** : Click the **"Sync with Gateway"** button for individual batch files. 2. **Purpose** : Synchronizes refund status with payment gateway systems. 3. **Real-time Updates** : Status updates are reflected immediately in the interface. ![Image](https://dth95m2xtyv8v.cloudfront.net/tesseract/assets/dashboard/Screenshot%202025-09-25%20at%201.43.30%E2%80%AFPM-4hdrp.png) *Sync With Gateway - Batch Refunds* ## CSV File Upload Specifications ### CSV Field Requirements | Field Name | Mandatory/Optional | Data Type | Description | Sample Value | Validation Rules | |---|---|---|---|---|---| | order_id | Mandatory | String | Unique order identifier for the transaction to be refunded | "ORD_123456789" | Must be a valid string, cannot be empty | | amount | Mandatory | Number | Refund amount to be processed | 100.50 | Must be a valid numeric value, supports decimal places | | txn_id | Optional | String | Transaction ID for the specific transaction | "TXN_987654321" | String value, can be empty | | unique_id | Optional | String | Unique identifier for the refund request | "REFUNIQUE001" | String value, can be empty | | marketplace_amount | Optional | Number | Amount for marketplace in split settlement | 75.25 | Numeric value for split settlement scenarios | | vendor1_id | Optional | String | First vendor ID for split settlement | "VENDOR_001" | String value for split settlement | | vendor1_amount | Optional | Number | Amount for first vendor in split settlement | 15.00 | Numeric value for split settlement | | vendor2_id | Optional | String | Second vendor ID for split settlement | "VENDOR_002" | String value for split settlement | | vendor2_amount | Optional | Number | Amount for second vendor in split settlement | 10.25 | Numeric value for split settlement | | udf1 | Optional | String | User Defined Field 1 | "CustomValue1" | String value, custom data field | | udf2 | Optional | String | User Defined Field 2 | "CustomValue2" | String value, custom data field | | udf3 | Optional | String | User Defined Field 3 | "CustomValue3" | String value, custom data field | | udf4 | Optional | String | User Defined Field 4 | "CustomValue4" | String value, custom data field | | udf5 | Optional | String | User Defined Field 5 | "CustomValue5" | String value, custom data field | | udf6 | Optional | String | User Defined Field 6 | "CustomValue6" | String value, custom data field | | udf7 | Optional | String | User Defined Field 7 | "CustomValue7" | String value, custom data field | | udf8 | Optional | String | User Defined Field 8 | "CustomValue8" | String value, custom data field | | udf9 | Optional | String | User Defined Field 9 | "CustomValue9" | String value, custom data field | | udf10 | Optional | String | User Defined Field 10 | "CustomValue10" | String value, custom data field | ### CSV Format Examples **Standard Format with Sample Data:** #### csv Code Snippet: ```csv order_id,amount,txn_id[OPTIONAL],unique_id[OPTIONAL],marketplace_amount[OPTIONAL],vendor1_id[OPTIONAL],vendor1_amount[OPTIONAL],vendor2_id[OPTIONAL],vendor2_amount[OPTIONAL],udf1[OPTIONAL],udf2[OPTIONAL],udf3[OPTIONAL],udf4[OPTIONAL],udf5[OPTIONAL],udf6[OPTIONAL],udf7[OPTIONAL],udf8[OPTIONAL],udf9[OPTIONAL],udf10[OPTIONAL] ORD_123456789,100.50,TXN_987654321,REF_UNIQUE_001,75.25,VENDOR_001,15.00,VENDOR_002,10.25,Custom_Value_1,Custom_Value_2,,,,,,, ORD_987654321,250.00,TXN_123456789,REF_UNIQUE_002,200.00,VENDOR_003,30.00,VENDOR_004,20.00,Custom_Value_3,Custom_Value_4,,,,,,, ``` ### File Upload Constraints * **Maximum Rows** : 1000 rows per CSV file * **File Format** : CSV (Comma Separated Values) only * **Encoding** : UTF-8 encoding recommended * **File Size** : Standard file size limitations apply * **Column Order** : Must match the specified header format * **Empty Values** : Optional fields can be left empty but commas must be maintained ## Understanding Split Settlement Refunds Split Settlement is a payment processing feature that allows a single transaction amount to be distributed across multiple parties - typically a marketplace and one or more vendors. When refunds are processed for split settlement transactions, the refund amounts must also be distributed proportionally among the same parties. ### How Split Settlement Works in Refunds **Marketplace Model** : In a typical marketplace scenario: * **Marketplace Amount** : The portion of the refund that goes back to the marketplace (platform fee, commission, etc.) * **Vendor Amounts** : The portions that go back to individual vendors who provided goods or services **Key Components** : * **marketplace_amount** : The refund amount allocated to the marketplace/platform * **vendor1_id & vendor1_amount** : First vendor's identifier and their refund portion * **vendor2_id & vendor2_amount** : Second vendor's identifier and their refund portion ### When to Use Split Settlement Refunds **E-commerce Marketplaces** : When customers return products sold by different vendors through a single marketplace platform. **Service Platforms** : When refunding payments for services that involved multiple service providers. **Commission-based Models** : When refunds need to account for platform fees, vendor payments, and other distributed amounts. ### Example Scenario Original Transaction: ₹1000 * Marketplace keeps: ₹100 (platform fee) * Vendor A receives: ₹600 (product cost) * Vendor B receives: ₹300 (shipping/handling) Refund Processing: ₹1000 refund * marketplace_amount: ₹100 * vendor1_id: "VENDOR_ A", vendor1_amount: ₹600 * vendor2_id: "VENDOR_ B", vendor2_amount: ₹300 The system ensures that each party receives their proportional refund amount, maintaining accurate financial records and proper settlement distribution. ## Split Settlement CSV File Upload Specifications Split Settlement refunds are designed for marketplace and multi-vendor scenarios where a single transaction amount needs to be distributed across multiple parties during the refund process. This section provides comprehensive guidance for processing split settlement refunds through CSV uploads. ### Split Settlement Field Requirements | Field Name | Mandatory/Optional | Data Type | Description | Sample Value | Validation Rules | |---|---|---|---|---|---| | order_id | Mandatory | String | Unique order identifier for the transaction to be refunded | "ORDMARKETPLACE001" | Must be a valid string, cannot be empty | | amount | Mandatory | Number | Total refund amount to be processed | 1000.00 | Must be a valid numeric value, supports decimal places | | marketplace_amount | Optional | Number | Amount allocated to the marketplace/platform | 100.00 | Numeric value, represents platform fee or commission portion | | vendor1_id | Optional | String | First vendor identifier in the split settlement | "VENDORELECTRONICS001" | String value, vendor identification code | | vendor1_amount | Optional | Number | Refund amount for the first vendor | 600.00 | Numeric value, must be positive if vendor1_id is provided | | vendor2_id | Optional | String | Second vendor identifier in the split settlement | "VENDORSHIPPING002" | String value, vendor identification code | | vendor2_amount | Optional | Number | Refund amount for the second vendor | 300.00 | Numeric value, must be positive if vendor2_id is provided | | txn_id | Optional | String | Transaction ID for the specific transaction | "TXNSPLIT001" | String value, can be empty | | unique_id | Optional | String | Unique identifier for the refund request | "REFSPLIT001" | String value, can be empty | ### Split Settlement Validation Rules #### Amount Distribution Validation * **Total Amount Consistency** : The sum of `marketplace_amount + vendor1_amount + vendor2_amount` should equal the total `amount` field * **Positive Values** : All amount fields must contain positive numeric values when specified * **Decimal Precision** : Supports up to 2 decimal places for currency precision * **Minimum Amount** : Each split amount must be greater than 0 if the corresponding vendor ID is provided #### Vendor ID Requirements * **Vendor-Amount Pairing** : If `vendor1_id` is provided, `vendor1_amount` must also be specified, and vice versa * **Unique Vendor IDs** : `vendor1_id` and `vendor2_id` must be different if both are provided #### Business Logic Constraints * **Marketplace Scenarios** : At least one of `marketplace_amount`, `vendor1_amount`, or `vendor2_amount` must be specified for split settlement * **Single Vendor** : Split settlement can be used even with only one vendor (marketplace + single vendor scenario) * **Maximum Vendors** : Current system supports up to 2 vendors plus marketplace in a single split settlement ### Split Settlement CSV Format Examples #### E-commerce Marketplace Scenario #### csv Code Snippet: ```csv order_id,amount,txn_id[OPTIONAL],unique_id[OPTIONAL],marketplace_amount[OPTIONAL],vendor1_id[OPTIONAL],vendor1_amount[OPTIONAL],vendor2_id[OPTIONAL],vendor2_amount[OPTIONAL] ORD_ECOM_001,1000.00,TXN_ECOM_001,REF_ECOM_001,100.00,ELECTRONICS_VENDOR,700.00,SHIPPING_PARTNER,200.00 ORD_ECOM_002,500.00,TXN_ECOM_002,REF_ECOM_002,50.00,FASHION_VENDOR,450.00,, ORD_ECOM_003,750.00,TXN_ECOM_003,REF_ECOM_003,75.00,BOOKS_VENDOR,400.00,GIFT_WRAP_SERVICE,275.00 ``` ## Use Cases ### Bulk Customer Refund Processing 1. Export failed transaction data from transaction reports 2. Prepare CSV file with order IDs and refund amounts 3. Upload file through Batch Refunds interface 4. Monitor processing status and download results ### Split Settlement Refund Management 1. Prepare CSV with marketplace and vendor amount breakdowns 2. Include vendor IDs and respective refund amounts 3. Upload file for automated split settlement processing 4. Track individual vendor refund status ### Monthly Refund Reconciliation 1. Compile monthly refund requests from customer support 2. Create CSV with order IDs, amounts, and reference data in UDF fields 3. Process bulk refunds and export results for financial reconciliation 4. Use downloaded data for accounting and audit purposes ## Troubleshooting **File Upload Validation Errors:** * **"Invalid file format"** : Ensure file is in CSV format with proper comma separation * **"Missing mandatory fields"** : Verify that order_id and amount columns are present and not empty * **"Row limit exceeded"** : Reduce file size to maximum 1000 rows per upload * **"Invalid data type"** : Check that amount field contains only numeric values ## Permissions and Roles Access to the Batch Refunds module is controlled by the following permissions: * **Refunds Module Access** : Required for accessing the batch refunds interface (ACL: `refunds`) * **Refunds Write Permission** : Required for creating and uploading batch refund files (ACL: `refunds` with ReadWrite access)