Documentation
User guideDeveloper guideAPI ReferenceContact
  1. MAS Guide
  2. Payments

Using batch files

Batch files are used to upload any type of transaction to our system - whether it's immediate or deferred, queued or queued deferred, and whether you have receipient details or want to use a stored recipient.

Batch File Basics

A batch file consists of multiple transaction requests. Each line in the batch file consists of a set of fields that are mapped to properties of a transaction request to our system.

The batch file progresses through the following stages:

  1. Upload
  2. Validation
  3. Approval
  4. Processing

Each line in the batch is validated to ensure that all mandatory fields contain appropriate values and that field lengths are correct. Any lines that could not be read correctly or failed validation are marked with an error, which can be viewed in MAS. It is also possible to export the lines containing errors for correction.

The approval process is configurable, allowing an administrator to define the number of approvers—ranging from none to multiple—required to review and approve/reject the batch. Once all required approvers have granted approval, each valid line is processed as a transaction request.

CSV Fields

A batch file contains up to four sets of fields, which are as follows:

  • Transaction fields apply to the transaction itself
  • Recipient fields apply to who is receiving the funds
  • Account fields describe, for the given recipient country and currency combination, the bank account information such as an IBAN and SWIFT code.
  • Originator fields - describe the original source of the transaction request (often optional)

CSV File Rules

The CSV format is a text file with rows of fields separated by commas. Typically, the set of fields is fixed, meaning each file has the same number of columns and a variable number of rows.

However, our batch file format does not require all fields to be defined in the file, making it a flexible and forgiving format. In this section, we will outline the rules for our batch file.

Rule 1: All batch files must have a header row

The header row is always the first row in the file and consists solely of column headers separated by commas.

Note that headers are not case-sensitive, allowing variations such as SendCurrency, SENDCURRENCY, or sendcurrency. And the order of the columns is not important.

An example is shown below:

SendCurrency,SendValue,RecipientName,RecipientCountry,RecipientCurrency,RecipientReference,AccountIban,AccountSwift

Rule 2: You don't have to add every field - just those you have data for

Batches are designed to work with whatever is provided (within the 70+ supported fields), as long as all mandatory fields are populated.

For example, the following batch file consists of three GBP payments to France, using AccountIban and AccountSwift:

SendCurrency,SendValue,RecipientName,RecipientCountry,RecipientCurrency,RecipientReference,AccountIban,AccountSwift
GBP,100,Jules Verne,FR,EUR,Book Payment,FR14 2004 1010 0505 0001 3M02 606,CCBPFRPPINS
GBP,450,Jacques Cousteau,FR,EUR,Diving Equipment,FR15 3323 5645 3343 1232 4M36 565,CCBPFRPPINS
GBP,1034.45,Claude Monet,FR,EUR,Painting Supplies,FR87 1094 3343 6765 3875 2M44 123,CCBPFRPPINS

Sending payments to the UK requires different fields associated with the account: AccountNumber and AccountSortCode:

SendCurrency,SendValue,RecipientName,RecipientCountry,RecipientCurrency,RecipientReference,AccountNumber,AccountSortCode
GBP,85.99,Tony Iommi,GB,GBP,Guitar Tuning,88833434,334422
GBP,125.00,Ian Anderson,GB,GBP,Flute Repairs,49483948,124412

Rule 3: Any field that is not required can be left blank.

Additional values can be added for extra fields, and payments to different countries can also be included in the same file. The sparse file format is used, where the header row contains the names of each field in the file, but the detail rows can include blank values for any column of data that is not applicable.

For example, combining the above batch files into one would result in the following:

SendCurrency,SendValue,RecipientName,RecipientCountry,RecipientCurrency,RecipientReference,AccountIban,AccountSwift,AccountNumber,AccountSortCode
GBP,100,Jules Verne,FR,EUR,Book Payment,FR14 2004 1010 0505 0001 3M02 606,CCBPFRPPINS,,
GBP,450,Jacques Cousteau,FR,EUR,Diving Equipment,FR15 3323 5645 3343 1232 4M36 565,CCBPFRPPINS,,
GBP,1034.45,Claude Monet,FR,EUR,Painting Supplies,FR87 1094 3343 6765 3875 2M44 123,CCBPFRPPINS,,
GBP,85.99,Tony Iommi,GB,GBP,Guitar Tuning,,,88833434,334422
GBP,125.00,Ian Anderson,GB,GBP,Flute Repairs,,,49483948,124412

The above example shows blank elements in the file, which correspond to fields that are not applicable for a given route. For payments to France, IBAN and SWIFT values are required, while the account number and sort code, needed for UK payments, are not. Similarly, for the last two payments, which are for recipients in the UK, the IBAN and SWIFT fields are left blank.

Rule 4: Use universal formats for date formats.

When uploading a batch file, various date formats will be read and parsed appropriately. However, an issue arises with how dates are stored and uploaded, which depends on the regional settings of your browser.

For example, in the UK, Europe, and much of the world, a date of 04-01-2021 is interpreted as 4th January 2021. However, in the US, the same date would be read as 1st April 2021. If a browser with regional settings set to the US is used, it will be interpreted as 1st April; if the browser region is set to the UK, it will be read as 4th January.

To avoid confusion, the recommended approach is to always specify dates in a universal format, such as:

  • YYYY-MM-DD
  • YYYY/MM/DD
  • YYYYMMDD

Although formats like NN-NN-NNNN and NN/NN/NNNN will also be parsed into valid dates, it's important to consider the impact of regional settings as described.

Updated 24 days ago