JUSPAY Unified Dashboard

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-refundslink icon.

Bulk Operations - Batch Refunds
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.

Batch Refunds
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)

Batch Refunds - List View
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

      Batch Refunds - Detailed View
      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.

Sync With Gateway - Batch Refunds
Sync With Gateway - Batch Refunds

CSV File Upload Specifications

CSV Field Requirements

Scroll inside to view more
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:

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

  • vendor1id: "VENDORA", vendor1_amount: ₹600

  • vendor2id: "VENDORB", 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

Scroll inside to view more
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

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)

Last updated 5 months ago