COMPANY030 — How to Validate Mass Pay Files

Last updated: August 26, 2026

Learn how to validate mass payment files prior to submission to ensure accurate formatting, retrieve missing wallet IDs, and minimize processing errors.

Overview

Mass pay file validation allows you to pre-screen payment data before final execution. By submitting your file for validation, the system generates a detailed response file that highlights missing data, formatting issues, and structural errors.

Note — Pre-validating your files significantly reduces processing time, minimizes failed transactions, and ensures payments are delivered accurately.

File Format & Submission Requirements

  • Input File Formats — Standard Excel (.xlsx) or Comma-Separated Values (.csv).

  • Validation Response Format — Always returned as a .csv file.

  • Template Source — Download the standard mass pay template HERE.

Validated Fields & Criteria

The validation tool inspects mandatory and optional fields for presence and correct formatting—

Field Name

Validation Check

Details

Email

Format

Verifies that email addresses follow standard syntax rules.

Wallet ID

Existence / Lookup

Checks if the specified Wallet ID exists. If left blank, the response file returns all available Wallet IDs and descriptions for that beneficiary.

Beneficiary Organization ID

Existence

Validates that the organization ID (e.g., SPNXXXXXXX) exists within the Xtrm system.

Beneficiary Address

Existence

Mandatory only when using the Direct to Check payment method.

Gift Card SKU

Existence

Mandatory only when using the Direct to Digital Gift Card payment method.

How to Retrieve Missing Wallet IDs

When a beneficiary maintains multiple wallets in the same currency, specifying a Wallet ID ensures funds are routed to the exact wallet intended.

1. Leave Wallet ID Blank:

In your initial mass pay file, leave the Wallet ID field blank for any beneficiaries where the specific wallet ID is unknown.

2. Upload for Validation:

Submit the file through the mass pay validation tool.

3. Review the Validation Response File:

Download the generated .csv response file. The system will populate all available Wallet IDs and corresponding descriptions associated with each beneficiary.

4. Update & Finalize Submission:

Copy the preferred Wallet ID into your final mass pay submission file.

  • Default Behavior — If you leave the Wallet ID field blank during your final submission, funds will automatically route to the beneficiary's default wallet for that currency.