Skip to main content

Getting Started | Batch Upload

Updated

Table of Contents

Overview

Effortlessly scale your payment processing with NMI’s Batch Upload interface—the ultimate solution for merchants handling high-volume transactions. Whether you’re working with Excel spreadsheets, CSVs, or TXT files, Batch Upload makes it easy to upload and process transactions via SFTP or manual web uploads. 

The Batch Upload feature allows merchants to:

  • Process Sales, Authorizations, Refunds, Voids, Captures, Offline, Updates and Credits.
  • Add customers to the Customer Vault.
  • Create and manage Recurring subscriptions and plans
  • Upload to the Product Manager
  • Create Invoices

The Getting Started article will guide the merchants through creating their files to process transactions. For instructions on uploading using other payment gateway features, please visit our "Batch Upload | Vault, Invoicing, Products, Recurring".

Prerequisites

The user will need the 'Batch Access' permission to access the option.

Navigating to Batch Upload

In the Merchant Portal, on the left side panel, click on Other Services → Batch Upload ; or from the homepage under Services→ click on Batch Upload.

Note: Mobile only accounts do not have this feature.

How to Convert Cells from General Format to Text in Excel

For Excel Uploads the merchant must complete this conversion before beginning the batch upload process.

Changing the format of cells from General to Text ensures that data is treated as plain text, preventing Excel from interpreting it as formulas. Follow these steps to convert the cells:

  1. Select the entire worksheet:
    • Press Ctrl + A (Windows) or Command + A (Mac) to highlight all the cells in the active worksheet.
    • Alternatively, click the Select All button (the gray box at the top-left corner of the worksheet, where the row numbers and column letters intersect).
  2. Then change the format:
    • Right-click on the selected cells and choose Format Cells from the menu.
    • Alternatively, go to the Home tab and click the dropdown menu in the Number Format group.
  3. Select Text Format:
    • In the Format Cells dialog box, go to the Number tab and select Text from the list of categories.
  4. Click OK to apply the changes.

Auto Detect File Format

With Auto-Detect, our smart system identifies your file's structure, allowing you to map fields or ignore unnecessary ones, and even save your preferences for future uploads.  The system will show you the fields it has detected and will allow you to change and/or assign fields not detected. For each field, select the system field from the dropdown. If there is a field that does not map, you can select "Ignore this Field". Once completed, you can name the format so you can use it for future uploads as well as set it as default. Prefer a straightforward approach? Use our Original format for a seamless, no-fuss upload experience.

File Formats

If you prefer to manually configure the format instead of relying on automatic detection, navigate to Configure Formats. Then, select your desired file format from the dropdown.

How-to Upload a Batch

The gateway supports batch upload files in CSV, XLS, or TXT files via SFTP, or manual web upload.
Our system will process uploaded files in parallel and easily scales with single batch files including
hundreds of thousands of transactions, however, it works just as well with a very small amount of
records, 10, 100, 1000, etc.

Note: If the file was previously uploaded, you will get a message that says "This file has already been uploaded! Press Next if you want to reprocess it".

CSV, XLS, or TXT

To upload:

  1. Login to the merchant portal.
  2. Go to Other Services →  Batch Upload.
  3. Prepare the file.
  4. Click on the 'Upload Batch' tab →'Choose File'
  5. Upload the file from your computer.
  6. Select 'Auto Detect File Format' or 'Selected Format'.
  7. Click the 'Upload Batch' Button.
  8. If the merchant chooses the Auto Detect File option, they will need to  match the headers from their file → Click Next.
    • Optionally save the format for future use.

The system will then immediately start processing the file showing a progress line as it processes
the transactions. Once complete the merchant can click 'View Batch History' to show the current status of the uploaded batches with the latest one last.

Note: Affiliate Partners can enable 'Return an extended file batch response'. If the setting is enabled it will returns extra fields in the Batch Upload Response file. The response text for each of the fields depends on the processor.

View Batch History

The merchant can view their previously uploaded files under the View History tab. Adjust the date range or use the calendar icon and click Submit to see more uploads.

  • Batch - the batch column contains the file name link that takes you to the transaction reports page and shows any transactions that were processed.
  • Status - the status column will let you know when it is pending and complete.
  • Approved - the approved column will include any action that was approved and processed.
  • Declined - the declined column will include any declined transactions. Transactions that were processed but not approved.
  • Errors - the errors column will display any issues found in the file, including mistakes or instances where the file couldn't be read properly.
  • Total - the total column is the total amount of actions it processed from the file (this includes the  headers row).
  • Action - the action column includes a 'Download' link that if you click on to see the line by line results of the transactions. The first three columns will show the Transaction Number, the result (1=approved, 2=declined and 3=fatal error) and the text result ("Approved", "Declined", or the reason for the error). 

Configure Formats

The Configure Formats section allows you to create, edit, delete and make batch upload file formats the default option. 

Here is a breakdown on some of the links you can click on:

  • View - see details such as the fields file format, description, and more.

  • Edit - make any changes to the batch format.
  • Delete - delete a batch format.
  • Make Default -  make a batch format the default upload option.

Adding a Batch Format

  1. Click on the add batch format.
  2. Specify a description for this file format:
    • Description - this will be the name of your custom file format. For example, if you're using it specifically for processing sales, you can name it "Sales Only."
    • Field Delimiter - a field delimiter is a character used to separate fields in a data file or database. It defines boundaries between different data values in a structured format.
      • Example: A CSV file with a comma as a delimiter:
Name, Age, City
John Doe, 30, New York 
Jane Smith, 25, Los Angeles
  • Field Encapsulation - is the practice of enclosing data fields within a specific character (often quotation marks) to prevent issues when delimiters appear inside the data.
  • Escaped by - when a field encapsulation character appears within a field, it must be escaped to prevent misinterpretation. The two most common escape methods are double characters (""), and backslash (\).

Note: CSV files (Excel, databases, spreadsheets) → Use double-character escaping ("").
JSON, programming languages (Python, JavaScript, SQL, etc.) → Use backslash escaping (\").

Batch Upload Transactions

Credit Card Transaction Field Requirements

Every Credit Card transaction type has a minimum of required fields before you can process the transaction. Below, you'll find the required fields for each transaction type, along with recommended fields:

Minimum Field Requirements

Recommended Fields (Not Required but Encouraged)
Including these fields can help improve security, accuracy, and processing success rates:

  • Billing First Name
  • Billing Last Name
  • CVV
  • Billing Address 1
  • Billing City
  • Billing State
  • Billing Postal Code
  • Billing Email Address

*A full list of headers that the merchant can include are available to download at the bottom of the page.

Minimum Required Fields by Transaction Type

Credit Cards

Credit Card - Sale

Required Fields Optional but Suggested Fields
  • Transaction Type (optional for batch uploads, defaults to "Sale")
  • Total Amount
  • Credit Card Number
  • Credit Card Expiration
  • Billing First Name
  • Billing Last Name
  • CVV
  • Billing Address 1
  • Billing City
  • Billing State
  • Billing Postal Code
  • Billing Email Address

Excel Example:

Excel Example

Note - Batch Upload Defaults to 'Sale' so specifying the 'Type' on a 'Sale' transaction is optional.

Credit Card - Authorization

Required Fields Optional but Suggested Fields
  • Transaction Type
  • Total Amount
  • Credit Card Number
  • Credit Card Expiration
  • Billing First Name
  • Billing Last Name
  • CVV
  • Billing Address 1
  • Billing City
  • Billing State
  • Billing Postal Code
  • Billing Email Address

Excel Example:

Excel Example

Credit Card - Capture

Required Fields
  • Transaction Type
  • Total Amount
  • Transaction ID

Excel Example:

Excel Example

Credit Card - Refund

Required Fields
  • Transaction Type
  • Total Amount
  • Transaction ID

Excel Example:

Excel Example

Credit Card - Void

Required Fields
  • Transaction Type
  • Transaction ID

Excel Example:

Excel Example

Credit Card - Credit

Required Fields Optional but Suggested Fields
  • Transaction Type
  • Total Amount
  • Credit Card Number
  • Credit Card Expiration
  • Billing First Name
  • Billing Last Name
  • Billing Address 1
  • Billing City
  • Billing State
  • Billing Postal Code
  • Billing Email Address

Excel Example: 

*Note: Blind Credits must be enabled for the merchant account.

Credit Card - Offline

Required Fields
  • Transaction Type
  • Total Amount
  • Credit Card Number
  • Credit Card Expiration Date
  • Auth Code

Excel Example:

Excel Example

Credit Card - Update

Required Fields
  • Transaction Type
  • Transaction ID

Excel Example:

Excel Example

Check

ACH Processing only supports 'Sale', 'Refund', 'Void', 'Update' and 'Credit' transaction types. Additionally, the payment method of 'Check' must be passed since our Gateway default is 'Credit Card'. Every Check transaction type has a minimum of required fields before you can process the transaction.  The required fields have been included for the individual types:

Check - Sale

Required Fields Optional but Suggested Fields
  • Transaction Type
  • Total Amount
  • Name on Checking Account
  • Check Account Number
  • Check Routing Number
  • Payment Method
  • NACHA SEC Code
  • Billing First Name
  • Billing Last Name
  • Billing Address 1
  • Billing City
  • Billing State
  • Billing Postal Code
  • Billing Email Address

Excel Example:

Check - Refund

Required Fields
  • Transaction Type
  • Total Amount
  • Transaction ID
  • Payment Method

Excel Example:

Check - Void

Required Fields
  • Transaction Type
  • Transaction ID
  • Payment Method

Excel Example:

Check - Credit

Required Fields Optional but Suggested Fields
  • Transaction Type
  • Total Amount
  • Name on Checking Account
  • Check Account Number
  • Check Routing Number
  • Payment Method
  • NACHA SEC Code
  • Billing First Name
  • Billing Last Name
  • Billing Address 1
  • Billing City
  • Billing State
  • Billing Postal Code
  • Billing Email Address

Excel Example:

*Note: Blind Credits must be enabled for the merchant account.

Check - Update

Required Fields
  • Transaction Type
  • Transaction ID
  • Payment Method

Excel Example:

Cash

Cash - Sale

Required Fields Optional but Suggested Fields
  • Transaction Type
  • Total Amount
  • Payment Method
  • Billing First Name
  • Billing Last Name
  • Billing Address 1
  • Billing City
  • Billing State
  • Billing Postal Code
  • Billing Email Address

Excel Example:

Excel Example

Cash - Refund

Required Fields
  • Transaction Type
  • Total Amount
  • Transaction ID
  • Payment Method

Excel Example:

Cash - Credit

Required Fields Optional but Suggested Fields
  • Transaction Type
  • Total Amount
  • Transaction ID
  • Payment Method
  • Billing First Name
  • Billing Last Name
  • Billing Address 1
  • Billing City
  • Billing State
  • Billing Postal Code
  • Billing Email Address

Excel Example:

*Note: Blind Credits must be enabled for the merchant account.

Receipts 

By default the Gateway does not send email receipts when the source is Batch Upload due to the sheer volume that is sometimes present in an upload file. The feature can be enabled by the affiliate partner for the merchant.

Log in to your Partner Portal and pull up the merchant's account → go to the Advanced Merchant Features section and click on Edit → check off the feature "Enable automatic receipt sending functionality for Batch transactions"→ click on Save. The gateway will send a customer email receipt to the billing email. 

Note: An email must be included in the file that is uploaded in order for the customer to receive an emailed receipt.

Notifications

Merchants can enable Receive Upload Summaries notifications directly from the merchant portal under their user permissions. The user will receive batch upload summary with any successful, declined and transaction errors. 

Video

Frequently Asked Questions

Can a "Validation" transaction be processed using batch upload? No, this can only be done via the API.

Can I automate batch uploads? Yes, batch uploads can be automated using SFTP scripts or by scheduling uploads via an automated process. You can view the steps and processes here: Advanced Batch Upload | SFTP.

Can I do a mass void? Yes, you can upload the transactions in one single file to void. 

How long does it take for a batch file to process? Batch files are typically processed within 5-10 minutes, but processing time may vary based on the processor and the size of the batch.

Can I upload multiple batch files at the same time? Yes, you can upload multiple files. They will be processed sequentially as per the system queue.

What is the maximum file size for a batch upload? The maximum file size allowed for a single batch upload is 250 MB.

What should I do if my batch upload fails? If your batch upload fails, check the Batch Upload History in the Merchant Control Panel for error details. Common causes include incorrect file formatting, missing required fields, or authentication issues.

Does the order of the headers matter? No, you can arrange them in any order as long as the fields are mapped correctly. This ensures that during the file upload, the batch process correctly interprets the row structure and reads the file properly.