JUSPAY Unified Dashboard

Batch Mandates

Overview

The Batch Mandates module provides comprehensive bulk mandate processing capabilities for processing multiple mandate orders simultaneously through CSV file uploads. It offers real-time progress tracking, status monitoring, and detailed reporting for all mandate operations processed through the Juspay payment platform.

This module is designed for a wide range of users, including:

  • Operations Teams: For processing mandate orders in bulk and monitoring mandate processing performance across different payment methods and gateways with comprehensive operational logs.

  • Finance Teams: For bulk mandate processing, financial reconciliation, and tracking mandate amounts across multiple transactions with detailed audit trails.

  • Customer Support: To process customer mandate requests in bulk, track mandate status, and provide accurate updates to customers on mandate processing and execution.

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 Mandates tab from the bulk operations navigation.

  5. The navigation URL for this module is https://portal.juspay.in/batch/batch-mandateslink icon.

    Batch Mandate
    Batch Mandate

Step-by-Step Usage Instructions

Creating Batch Mandates

Step 1: Access the Batch Mandates Interface

  1. Navigate to the Batch Mandates module using the steps above.

  2. You will see the main dashboard with a description: "This module helps in creating mandates 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 mandate uploaded is displayed."

  3. The interface displays any previously uploaded batch mandate files in a table format.

Step 2: Initiate New Batch Mandate Upload

  1. Click the "Create Batch Mandates" 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 mandate 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 Mandate
    Batch Mandate

Step 3: Prepare and Upload CSV File

  1. Download Sample File: Click on the sample file link to download the CSV template (batch_mandate_sample.csv).

  2. Prepare Your Data: Fill in your mandate 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, Amount, Customer ID, Mandate ID)

    • 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 (orderid, amount, customerid, mandate_id)

    • Data type validation for each column

    • Amount validation (must be positive numeric value)

    • Row count validation (maximum 1000 rows)

  2. Error Handling: If validation fails, specific error messages are displayed:

    • Missing mandatory fields

    • Invalid data types

    • Invalid amount values

    • 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

    • Mandate processing begins

Step 5: Monitor Processing Status

  1. Real-time Updates: The dashboard automatically updates with processing status.

  2. Status Indicators:

    • ACCEPTED: Successfully processed mandates (Green indicator)

    • FAILED: Failed mandate attempts (Red indicator)

    • QUEUED: Mandates waiting in processing queue (Blue indicator)

Monitoring and Managing Batch Mandates

Viewing Batch Mandate 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

    • Date Created: File upload timestamp

    • Last Modified: Last update timestamp

    • Total Tasks: Number of mandate 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

      • Current status with color-coded indicators

    • Progress Statistics: Individual task counts for:

      • Total Accepted Tasks: Successfully processed mandates

      • Total Rejected Tasks: Failed mandate attempts

      • Total Queued Tasks: Mandates in processing queue

        Batch Mandate Detailed View
        Batch Mandate 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, 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 mandate data with the following headers:

      • Order ID

      • Amount

      • Customer ID

      • Mandate ID

      • Mandate Status

      • Unique Id

      • epgTxnId

      • Udf1 through Udf10 (User Defined Fields)

      • Task Status

      • Error Message

      • Created At

      • Updated At

  3. File Format:

    • CSV format with comma-separated values

    • Filename format: batch_mandate.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 mandate status with payment gateway systems.

  3. Real-time Updates: Status updates are reflected immediately in the interface.

    Batch Mandate
    Batch Mandate

Metadata Configuration

Overview

The Batch Mandates module supports custom metadata configuration, allowing you to add additional columns to your CSV files for enhanced data tracking and processing flexibility.

Accessing Metadata Configuration

  1. Upload Interface: When creating a new batch mandate upload, you'll see two tabs:

    • Upload CSV File: Standard file upload functionality

    • Configure Metadata: Custom metadata field configuration

  2. Configure Metadata Tab: Click on the "Configure Metadata" tab to access metadata configuration options.

Configuring Custom Metadata Fields

Step 1: Add Metadata Fields

  1. Add Metadata Columns: Use the "Add Metadata Columns" section on the right side of the interface.

  2. Field Input: Enter your custom metadata field names in the input field.

  3. Field Prefix: All metadata fields will be automatically prefixed with "metadata." in the CSV template.

  4. Add Multiple Fields: Click the "Add Metadata" button to add multiple custom fields as needed.

    Batch Mandate - Configure Metadata
    Batch Mandate - Configure Metadata

Step 2: Download Enhanced Template

  1. Template Generation: After configuring metadata fields, the system generates an enhanced CSV template.

  2. Download Sample: Click "Download Sample CSV" to get the template with your custom metadata columns.

  3. Column Structure: The downloaded template includes:

    • All standard mandate fields

    • Your custom metadata fields (prefixed with "metadata.")

    • Proper column ordering and formatting

Metadata Configuration Guidelines

Security and Data Privacy

  • Sensitive Information Warning: Do not include sensitive personal or financial information in metadata fields

  • Prohibited Data: Avoid including:

    • Names, Aadhaar numbers, PAN details

    • Bank account numbers, IFSC codes

    • Mobile numbers or personal identifiers

  • Data Protection: Ensure metadata complies with data protection regulations

Best Practices for Metadata Fields

  1. Field Naming: Use descriptive, clear field names for easy identification

  2. Data Consistency: Maintain consistent data formats across all metadata fields

  3. Field Purpose: Document the purpose of each metadata field for team reference

  4. Validation: Ensure metadata values are properly formatted and validated before upload

Metadata Field Examples

  • metadata.campaign_id: Marketing campaign identifier

  • metadata.source_system: Originating system reference

  • metadata.priority_level: Processing priority indicator

  • metadata.business_unit: Department or business unit reference

  • metadata.external_ref: External system reference number

Instructions for Metadata Usage

  1. Pre-Configuration: Add metadata fields before downloading the CSV file template to ensure they are included as columns in the sheet.

  2. Template Download: Always download the sample CSV after configuring metadata to get the correct column structure.

  3. Data Population: Fill in both standard mandate fields and custom metadata fields in the downloaded template.

  4. Upload Process: Upload the completed CSV file with both standard and metadata columns populated.

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 mandate
"ORD_123456789"
Must be a valid string, cannot be empty
amount
Mandatory
Number
Mandate amount to be processed
100.50
Must be a valid numeric value, supports decimal places
customer_id
Mandatory
String
Customer identifier for the mandate
"CUST_987654321"
Must be a valid string, cannot be empty
mandate_id
Mandatory
String
Mandate identifier for processing
"MAN_456789123"
Must be a valid string, cannot be empty
notification_id
Optional
String
Notification identifier for the mandate
"NOTIF_123456"
String value, can be empty
currency
Optional
String
Currency code for the mandate amount
"INR"
Valid currency code (ISO 4217 format)
customer_email
Optional
String
Customer email address
"customer@example.com"
Valid email format
customer_phone
Optional
String
Customer phone number
"+919876543210"
Valid phone number format
description
Optional
String
Description of the mandate
"Monthly subscription payment"
String value, descriptive text
return_url
Optional
String
Return URL after mandate processing
"https://merchant.com/return"
Valid URL format
product_id
Optional
String
Product identifier for the mandate
"PROD_789123"
String value, product reference
display_invoice_number
Optional
String
Invoice number for display
"INV2023001"
String value, invoice reference
execution_date
Optional
String
Scheduled execution date for the mandate
"2023-12-31"
Date format (YYYY-MM-DD)
billing_address_first_name
Optional
String
Billing address first name
"John"
String value, customer name
billing_address_last_name
Optional
String
Billing address last name
"Doe"
String value, customer surname
billing_address_line1
Optional
String
Billing address line 1
"123 Main Street"
String value, address line
billing_address_line2
Optional
String
Billing address line 2
"Apartment 4B"
String value, address line
billing_address_line3
Optional
String
Billing address line 3
"Near City Center"
String value, address line
billing_address_city
Optional
String
Billing address city
"Mumbai"
String value, city name
billing_address_state
Optional
String
Billing address state
"Maharashtra"
String value, state name
billing_address_country
Optional
String
Billing address country
"India"
String value, country name
billing_address_postal_code
Optional
String
Billing address postal code
"400001"
String value, postal code
billing_address_phone
Optional
String
Billing address phone number
"+919876543210"
Valid phone number format
billing_address_country_code_iso
Optional
String
Billing address ISO country code
"IN"
ISO country code (2-letter)
shipping_address_first_name
Optional
String
Shipping address first name
"John"
String value, customer name
shipping_address_last_name
Optional
String
Shipping address last name
"Doe"
String value, customer surname
shipping_address_line1
Optional
String
Shipping address line 1
"456 Oak Avenue"
String value, address line
shipping_address_line2
Optional
String
Shipping address line 2
"Building C"
String value, address line
shipping_address_line3
Optional
String
Shipping address line 3
"Tech Park"
String value, address line
shipping_address_city
Optional
String
Shipping address city
"Bangalore"
String value, city name
shipping_address_state
Optional
String
Shipping address state
"Karnataka"
String value, state name
shipping_address_country
Optional
String
Shipping address country
"India"
String value, country name
shipping_address_postal_code
Optional
String
Shipping address postal code
"560001"
String value, postal code
shipping_address_phone
Optional
String
Shipping address phone number
"+919876543210"
Valid phone number format
shipping_address_country_code_iso
Optional
String
Shipping address ISO country code
"IN"
ISO country code (2-letter)
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

Mandate Validation Rules

Order ID Requirements:

  • Format: Must be a unique string identifier

  • Length: No specific length restrictions, but should be reasonable

  • Uniqueness: Each order ID should be unique within the batch

Amount Validation:

  • Format: Numeric value with optional decimal places

  • Range: Must be positive (greater than 0)

  • Precision: Supports up to 2 decimal places for currency precision

Customer and Mandate ID Requirements:

  • Format: String identifiers for customer and mandate references

  • Validation: Must be non-empty strings

  • Purpose: Used for linking mandates to customers and tracking

CSV Format Examples

Complete CSV Format with Sample Data:

CSV Format with Metadata Fields:

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

  • Metadata Fields: Custom metadata fields are optional and can be configured as needed

Use Cases

Subscription Service Management

  1. Export subscription customer data from billing systems

  2. Prepare CSV file with order IDs, amounts, customer IDs, and mandate IDs

  3. Upload file through Batch Mandates interface

  4. Monitor processing status and download results for subscription activation

Recurring Payment Setup

  1. Prepare CSV with recurring payment information for mandate creation

  2. Include customer details and billing addresses for proper mandate setup

  3. Upload file for automated mandate processing

  4. Track individual mandate status and download mandate results

Bulk Payment Processing

  1. Compile payment data from various customer sources

  2. Create CSV with mandate details and tracking references in UDF fields

  3. Process bulk mandates and export results for payment processing

  4. Use downloaded mandate data for payment execution and reconciliation

Troubleshooting

File Upload Validation Errors:

  • "Invalid file format": Ensure file is in CSV format with proper comma separation

  • "Missing mandatory fields": Verify that orderid, amount, customerid, and mandate_id 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

  • "Invalid amount value": Ensure amount values are positive numbers

Permissions and Roles

Access to the Batch Mandates module is controlled by the following permissions:

  • Mandates Module Access: Required for accessing the batch mandates interface (ACL: mandate)

  • Mandates Write Permission: Required for creating and uploading batch mandate files (ACL: mandate with ReadWrite access)

  • Mandates Read Permission: Needed to view batch mandate status and download processed data (ACL: mandate)

  • Mandate Analytics Access: Required for accessing mandate analytics and reporting features (ACL: mandate_analytics)

  • Settings Mandate Access: Required for advanced mandate configuration and revoke operations (ACL: settings_mandate)

Last updated 2 months ago