Introduction

Batch Transaction Upload (BTU) allows merchants to process multiple transactions at once by uploading a single CSV or text file in the Business Center. Common batch issues include malformed files, header or trailer errors, processor rejections, missing parent MID, and batches stuck in ToBeResolved. This article explains how to prepare files correctly, diagnose validation errors, and resolve processor‑level failures.

Before You Begin – Required Pre‑Checks

• Verify merchantID: Must be active and match the login used for uploading.
• Confirm enabled services: Sales, Captures, Credits, etc.
• Use the correct file template for the transaction type.
• Ensure the file is ≤ 20 MB.
• Use YYYY‑MM‑DD date format.
• recordCount must match the number of data rows.
• For Level II/III files, ensure all tax/freight/duty fields are complete.
• Processors like APACS, SmartFDC, and TC33 may require additional formatting rules.

Batch Templates

Select the template matching your transaction type. Each file must contain only one transaction type.

How to Build a Valid Batch File

Option A – Standard Template (Recommended)

1. Import the CSV into Excel using Data › Import (prevents reformatting).
2. Complete the header fields exactly as specified.

Option B – Custom Template

merchantID=AcmeStore,batchID=BTU0426,creationDate=2025-01-12,
recordCount=2,Template=custom
merchantReferenceCode,purchaseTotals_currency,purchaseTotals_amount,ccCreditService_captureRequestID
credit_1,usd,30.00,CAPTURE123
credit_2,usd,45.00,CAPTURE456
END,75.00

Batch Status Definitions

Troubleshooting Common Batch Failures

1. Malformed Header Row

“Malformed header row” indicates the first row contains unexpected formatting, wrong delimiters, hidden characters, or incorrect field names.

Fix

• Ensure file encoding is UTF‑8 without BOM.
• Confirm consistent comma delimiters.
• Ensure no blank lines or metadata above the header.
• Remove hidden spaces before/after commas.
• Make sure header names exactly match the template.

2. Entire File Fails Validation

• Check the .validate.xml file for error codes 101–124.
• Ensure recordCount and SUM trailer lines match.
• Validate all fields required for the transaction type.

3. Batch Stuck in “ToBeResolved”

Indicates a validation error or internal issue. This status does not resolve automatically.

Common Causes

• Formatting errors in the header, data rows, or trailer.
• Incorrect field counts or missing header fields.
• Cybersource internal validation error.

Resolution

• Review .validate.xml for error details.
• Fix the formatting issues and re-upload.
• If the batch remains stuck, contact Client Services: Support – Contacting Client Services.

4. Missing parent_mid

Some batch processors require a parent MID associated with a portfolio. If missing, the entire file may reject.

• Verify your MID belongs to the correct hierarchy.
• Ensure processor configuration includes a parent MID.
• If missing, open a configuration case with Client Services.

5. Incomplete or Missing Reply Files

Indicates a processor-level failure or a cutoff window issue.

• Check for reply.all and reply.rejected files the next day.
• If no reply file appears, confirm if the batch reached the processor.

Processor-Level Batch Failures (FDC, SmartFDC, APACS, TC33)

Why Entire Files Get Rejected

• Unsupported fields for the processor.
• Missing mandatory processor fields (terminal ID, reconciliation ID).
• Unsupported card types or currencies.
• Strict field length rules (SmartFDC, APACS).
• TC33 “all-or-nothing” processing: one bad row fails entire file.

Where to Identify Processor Failures

• Batch Submission Detail Report – shows BATCH_ERROR or FAILED.
• PaymentProcessor section – identifies the processor that rejected the file.
• reply.all file – displays reason codes and processor messages.

Common Examples

Batch Validation Error Codes (101–124, 201–205, 301)

For the full table of batch error codes, remedies, and descriptions, see: Cybersource Batch Error Code Reference .

Should You Rebatch?

1. If the failure is in validate.xml: Fix and reuse the same batchID.
2. If processor rejected the entire file: Create a new batchID.
3. If duplicates appear in reply files: Contact Client Services before resubmitting.
4. If cutoff time was missed: Submit with a new batchID next day.

Additional Resources

• Batch Submission User Guide
• Support – Contacting Client Services