Batch transaction upload
Last updated: October 1, 2026
For a full understanding of the transaction model please start with our Transactions API documentation.
When you upload transactions in a batch to be evaluated by Transaction Monitoring in Mesh, you can include a wide variety of fields.
There are a minimum set of fields that must be present (marked as required below). Any data you send is stored securely in Mesh and returned via API and in the web app.
Having more data in one place not only provides a single view of your transactions but can increase the efficiency of your team as they don't need to navigate between many platforms to find what they need.
Managing customers
Transactions need to be attached to a customer record. For the fastest evaluation of transactions users should attach the transaction to a pre-existing customer. However, we also offer the ability for the user to update or create a customer at the time of transaction processing.
Full details of your options are on our API docs.
Restriction: each file uploaded to the batch uploader must contain only one of the following methods:
The customer external ID is provided at the top level and the customer object is not provided. i.e. all transactions use existing customers with no in-line customer creation or update.
The customer external ID is provided at the top level and the customer object is also provided. i.e. all transactions include customer details in the customer object to update existing customers or create new customers.
How to set up your file headings
Row 1 must contain the name of the fields.
All supported fields are listed below by customer type, you can exclude any that are not relevant to you.
Fields indicated below with [X] can take more than one value.
Each value must be entered in a new column where headers are differentiated by replacing [X] with [1], [2], [3] etc.
For example, for a person's nationality:
If there is only 1 nationality, the heading would be customer[1].person.nationality[1].
If there is a second nationality, it must be filled into a separate column with the heading customer[1].person.nationality[2].
Fields that are not required can be left blank, even if you include the headers in your file
You will need to provide the required fields from the Transaction and Customer sections for each transaction you are submitting.
There are csv and xslx template files available to download in the web application.
Supported attributes and descriptions
Transaction
Common
The following fields are required for all transaction types.
Field | Accepted values or format | Required | Description | Max length |
|
| Yes | Classification of the transaction. Currently we only support monetary transaction types. | |
|
| Yes | The specific type of transaction this represents. | |
| n/a | Yes | The identifier for the scenario configuration you have set up in Mesh | |
| n/a | Yes | The identifier you assign each transaction to uniquely identify them | 255 |
| ISO-8601 | Yes | The timestamp of the transaction. For a monetary transaction this could be the timestamp of the card swipe or the settlement date of the transaction. | |
| IANA timezone | No | The IANA timezone in which the timestamp exists, for example "Europe/Andorra", "America/New_York", etc. | |
| No | The reference text supplied as part of the financial transaction. | 255 | |
| No | 255 | ||
| number | No | The amount of the financial transaction in the currency it occurred in. | |
| ISO 4217 currency code | No | The currency the financial transaction occurred in. | |
| number | Yes | The amount of the financial transaction in the reference base currency. | |
| ISO 4217 currency code | No | The reference base currency for the account. | |
| n/a | n/a | You can provide up to 10 custom fields per transaction. The fields should be repeated; with the number in the column name incremented for each custom field. | |
| The key of the custom field. | 255 | ||
| You can provide one of String representation of the custom field value. | 255 | ||
| You can provide one of Decimal representation of the custom field value. | |||
|
| No | The classification code used to identify the nature of a cash-in or cash-out event for BSA reporting purposes on Currency Transaction Report (Form 112). | |
| No | The Geographic Targeting Order (GTO) specific alphanumeric identifier required by FinCEN to be entered in Field 45 of the Currency Transaction Report. (e.g., "MSB0326GTO"). | ||
| No | The identifier you assigned to uniquely identify the location of this transaction. | ||
| Decimal number | No | The cash portion of this transaction's amount, in the currency given by | |
| ISO 4217 currency code | No | The currency the cash transaction occurred in. |
Bank Payment
The following fields are required (along with the common fields) if the transaction is a bank payment.
Field | Accepted values or format | Required | Description | Max length |
|
| No | The state of the payment. | |
|
| No | The payment scheme that was used to initiate the payment. | |
|
| No | The payment channel used to initiate the payment. | |
| number | No | The account balance of the customer. | |
| ISO 4217 currency code | No | The currency of the account balance of the customer. | |
| Yes | The debtor's name. | 255 | |
| n/a | n/a | You can provide one of | |
| No | The first line of the address | 50 | |
| No | The second line of the address | 50 | |
| No | The town or city | 50 | |
| No | The zip code or postal code | 50 | |
| No | The country subdivision or state | 50 | |
| ISO 3166-1 alpha-2 | No | The address country | |
|
| No | The address type | |
| n/a | You can provide one of | ||
| No | Unstructured local address information. This could be just a street number and name, a comma separated list of various local parts of an address such as a flat number, street and town etc. | 255 | |
| No | Unstructured country information, when available. This may be a country name, partial name, internal short code or a 2 or 3 character ISO code, etc. | 255 | |
| Yes | The identifier you assign each customer to uniquely identify them. A customer external identifier is required in one; and only one; of the following slots: debtor creditor ultimate debtor ultimate creditor | 255 | |
| No | The ultimate debtor's name. | 255 | |
| n/a | n/a | You can provide one of | |
| No | The first line of the address | 50 | |
| No | The second line of the address | 50 | |
| No | The town or city | 50 | |
| No | The zip code or postal code | 50 | |
| No | The country subdivision or state | 50 | |
| ISO 3166-1 alpha-2 | No | The address country | |
|
| No | The address type | |
| n/a | n/a | You can provide one of | |
| No | Unstructured local address information. This could be just a street number and name, a comma separated list of various local parts of an address such as a flat number, street and town etc. | 255 | |
| No | Unstructured country information, when available. This may be a country name, partial name, internal short code or a 2 or 3 character ISO code, etc. | 255 | |
| No | You can optionally provide a counterparty external identifier in one; and only one; of the following slots: debtor creditor ultimate debtor ultimate creditor | 255 | |
| Yes | The identifier you assign each customer to uniquely identify them. A customer external identifier is required in one; and only one; of the following slots: debtor creditor ultimate debtor ultimate creditor | ||
| Yes | The creditor's name. | 255 | |
| n/a | n/a | You can provide one of | |
| No | The first line of the address | 50 | |
| No | The second line of the address | 50 | |
| No | The town or city | 50 | |
| No | The zip code or postal code | 50 | |
| No | The country subdivision or state | 50 | |
| ISO 3166-1 alpha-2 | No | The address country | |
|
| No | The address type | |
| n/a | n/a | You can provide one of | |
| No | Unstructured local address information. This could be just a street number and name, a comma separated list of various local parts of an address such as a flat number, street and town etc. | 255 | |
| No | Unstructured country information, when available. This may be a country name, partial name, internal short code or a 2 or 3 character ISO code, etc. | 255 | |
| No | You can optionally provide a counterparty external identifier in one; and only one; of the following slots: debtor creditor ultimate debtor ultimate creditor | 255 | |
| Yes | The identifier you assign each customer to uniquely identify them. A customer external identifier is required in one; and only one; of the following slots: debtor creditor ultimate debtor ultimate creditor | 255 | |
| No | The ultimate creditor's name. | 255 | |
| n/a | n/a | You can provide one of | |
| No | The first line of the address | 50 | |
| No | The second line of the address | 50 | |
| No | The town or city | 50 | |
| No | The zip code or postal code | 50 | |
| No | The country subdivision or state | 50 | |
| ISO 3166-1 alpha-2 | No | The address country | |
|
| No | The address type | |
| n/a | n/a | You can provide one of | |
| No | Unstructured local address information. This could be just a street number and name, a comma separated list of various local parts of an address such as a flat number, street and town etc. | 255 | |
| No | Unstructured country information, when available. This may be a country name, partial name, internal short code or a 2 or 3 character ISO code, etc. | 255 | |
| No | You can optionally provide a counterparty external identifier in one; and only one; of the following slots: debtor creditor ultimate debtor ultimate creditor | 255 | |
| Yes | The identifier you assign each customer to uniquely identify them. A customer external identifier is required in one; and only one; of the following slots: debtor creditor ultimate debtor ultimate creditor | 255 | |
| n/a | n/a | You can provide details for up to 10 agents per transaction. Each agent’s fields (like role and name) should be repeated. The order of the agents is taken from the index field. | |
| number between 1 and 10 | No | Indicates where this agent appeared in the original list of agents. | |
|
| No | The role the agent has within a financial transaction. | |
| No | The reference text supplied by an agent. | 255 | |
| No | The name of the bank. This can be the legal name, or a trading name, or a general name. | 255 | |
| BIC code | No | The 8-11 character BIC of the bank. | 11 |
| No | The first line of the address | 50 | |
| No | The second line of the address | 50 | |
| No | The town or city | 50 | |
| No | The zip code or postal code | 50 | |
| No | The country subdivision or state | 50 | |
| ISO 3166-1 alpha-2 | No | The address country | |
|
| No | The address type |
Card Payment
The following fields are required (along with the common fields) if the transaction is a card payment.
Field | Accepted values or format | Required | Description | Max length |
|
| No | Indicates the card payment type, representing the business purpose or nature of the transaction. | |
|
| No | Represents the different stages of a card payment lifecycle. | |
|
| No | Indicates the geographical scope of the card payment transaction. | |
|
| No | Card scheme/network that issued the card (e.g., Visa, Mastercard, American Express). | |
| No | The parent transaction related to the current transaction. This is applicable for when you want to link a refund operation to the original transaction. | 100 | |
| n/a | n/a | Represents a payment card with its key identifying attributes. | |
|
| No | Type of card funding (credit, debit, prepaid, unknown). | |
| Yes | Unique fingerprint to identify the card across transactions. This is a hashed or tokenized representation that allows identification without exposing sensitive card details. | 150 | |
| No | Wallet identifier if the card is associated with a digital wallet. Optional field as not all cards are wallet-based. | 50 | |
|
| No | Type of digital wallet used for this card transaction. | |
| n/a | n/a | Represents card verification results including CVV, AVS, and identity checks. | |
|
| No | Address Verification System (AVS) check result. | |
| No | Optional description providing additional details about the AVS check result. | 200 | |
|
| No | Card Verification Code (CVC) check result. | |
| No | Optional description providing additional details about the CVC check result. | 200 | |
|
| No | 3D Secure authentication check result. | |
| No | Optional description providing additional details about the 3D Secure check result. | 200 | |
| n/a | n/a | Card holder details including party identification and onboarding information. | |
| No | The card holder's name. | 255 | |
| No | You can optionally provide a counterparty external identifier in one; and only one; of the following slots:
merchant
| ||
| Yes | The identifier you assign each customer to uniquely identify them. A customer external identifier is required in one; and only one; of the following slots:
merchant
| 255 | |
| n/a | n/a | You can provide one of | |
| No | The first line of the address | 50 | |
| No | The second line of the address | 50 | |
| No | The town or city | 50 | |
| No | The zip code or postal code | 50 | |
| No | The country subdivision or state | 50 | |
| ISO 3166-1 alpha-2 | No | The address country | |
|
| No | The address type | |
| n/a | You can provide one of | ||
| No | Unstructured local address information. This could be just a street number and name, a comma separated list of various local parts of an address such as a flat number, street and town etc. | 255 | |
| No | Unstructured country information, when available. This may be a country name, partial name, internal short code or a 2 or 3 character ISO code, etc. | 255 | |
| n/a | n/a | Represents details of a card issuer. | |
| No | Bank Identification Number (BIN) - first 6-8 digits of the card number. | 8 | |
| No | The issuer's name. | 255 | |
| You can optionally provide a counterparty external identifier in one; and only one; of the following slots:
merchant
| |||
| n/a | n/a | You can provide one of | |
| No | The first line of the address | 50 | |
| No | The second line of the address | 50 | |
| No | The town or city | 50 | |
| No | The zip code or postal code | 50 | |
| No | The country subdivision or state | 50 | |
| ISO 3166-1 alpha-2 | No | The address country | |
|
| No | The address type | |
| n/a | n/a | You can provide one of | |
| No | Unstructured local address information. This could be just a street number and name, a comma separated list of various local parts of an address such as a flat number, street and town etc. | 255 | |
| No | Unstructured country information, when available. This may be a country name, partial name, internal short code or a 2 or 3 character ISO code, etc. | 255 | |
| Represents details of a card acquirer including acquirer ID and identification information. | |||
| No | Unique identifier for the acquirer (assigned by card networks). | 100 | |
| No | The acquirer's name. | 255 | |
| No | You can optionally provide a counterparty external identifier in one; and only one; of the following slots:
merchant
| ||
| n/a | n/a | You can provide one of | |
| No | The first line of the address | 50 | |
| No | The second line of the address | 50 | |
| No | The town or city | 50 | |
| No | The zip code or postal code | 50 | |
| No | The country subdivision or state | 50 | |
| ISO 3166-1 alpha-2 | No | The address country | |
|
| No | The address type | |
| n/a | You can provide one of | ||
| No | Unstructured local address information. This could be just a street number and name, a comma separated list of various local parts of an address such as a flat number, street and town etc. | 255 | |
| No | Unstructured country information, when available. This may be a country name, partial name, internal short code or a 2 or 3 character ISO code, etc. | 255 | |
| n/a | n/a | Details of a principal merchant (e.g., Payment Facilitator). | |
|
| No | Category types for Merchant Category Codes based on industry code ranges. | |
| number | No | 4-digit MCC code (e.g., 5812, 6012). | 4 |
| No | Human-readable description of the MCC (e.g., "Grocery Stores, Supermarkets"). | 200 | |
| No | The merchant's name. | 255 | |
| No | You can optionally provide a counterparty external identifier in one; and only one; of the following slots:
merchant
| 100 | |
| Yes | The identifier you assign each customer to uniquely identify them. A customer external identifier is required in one; and only one; of the following slots:
merchant
| 255 | |
| n/a | n/a | You can provide one of | |
| No | The first line of the address | 50 | |
| No | The second line of the address | 50 | |
| No | The town or city | 50 | |
| No | The zip code or postal code | 50 | |
| No | The country subdivision or state | 50 | |
| ISO 3166-1 alpha-2 | No | The address country | |
|
| No | The address type | |
| n/a | n/a | You can provide one of | |
| No | Unstructured local address information. This could be just a street number and name, a comma separated list of various local parts of an address such as a flat number, street and town etc. | 255 | |
| No | Unstructured country information, when available. This may be a country name, partial name, internal short code or a 2 or 3 character ISO code, etc. | 255 | |
| n/a | n/a | Details of the sub-merchant where the transaction originated. This field is optional as not all card payments involve sub-merchants. | |
|
| No | Category types for Merchant Category Codes based on industry code ranges. | |
| number | No | 4-digit MCC code (e.g., 5812, 6012). | 4 |
| No | Human-readable description of the MCC (e.g., "Grocery Stores, Supermarkets"). | 200 | |
| No | The sub-merchant's name. | 255 | |
| You can optionally provide a counterparty external identifier in one; and only one; of the following slots:
merchant
| 100 | ||
| Yes | The identifier you assign each customer to uniquely identify them. A customer external identifier is required in one; and only one; of the following slots:
merchant
| 255 | |
| n/a | n/a | You can provide one of | |
| No | The first line of the address | 50 | |
| No | The second line of the address | 50 | |
| No | The town or city | 50 | |
| No | The zip code or postal code | 50 | |
| No | The country subdivision or state | 50 | |
| ISO 3166-1 alpha-2 | No | The address country | |
|
| No | The address type | |
| n/a | You can provide one of | ||
| No | Unstructured local address information. This could be just a street number and name, a comma separated list of various local parts of an address such as a flat number, street and town etc. | 255 | |
| No | Unstructured country information, when available. This may be a country name, partial name, internal short code or a 2 or 3 character ISO code, etc. | 255 | |
| n/a | Contextual information about the card payment environment. | ||
| Must be exactly 2 digits | No | POS condition code with description indicating the specific conditions or environment under which the transaction took place at the point-of-sale. | 2 |
| No | Human-readable description of the code. | 200 | |
| No | Point of Service Entry Mode indicating how the cardholder's account number (PAN) was physically entered or captured at the point-of-sale terminal. This represents the technical method of card data input. | 2 | |
| No | Human-readable description of the code. | 200 | |
| n/a | n/a | Authorization Information | |
| No | Current state of the authorization. | ||
| No | Reason code for the authorization response. | 50 | |
| No | Unique identifier for the authorization. | 100 | |
| number | No | The amount of the authorization in the currency it occurred in. | |
| ISO 4217 currency code | No | The currency the authorization occurred in. | |
|
| No | Type of authorization for a card payment. | |
| n/a | n/a | Settlement information. | |
| ISO 8601 date & time with offset | No | Timestamp when the settlement occurred. | |
| number | No | The amount of the settlement in the currency it occurred in. | |
| ISO 4217 currency code | No | The currency the settlement occurred in. | |
| n/a | n/a | Reversal information. | |
| ISO 8601 date & time with offset | No | Timestamp when the reversal occurred. | |
| number | No | The amount of the reversal in the currency it occurred in. | |
| ISO 4217 currency code | No | The currency the reversal occurred in. | |
| No | Unique identifier for the reversal. | ||
| n/a | n/a | Refund information - although refunds are not part of the transaction, you can provide context of the refund here. | |
| ISO 8601 date & time with offset | No | Timestamp when the refund occurred. | |
| No | Reason code for the refund. | 50 | |
| No | Human-readable description of the code. | 200 | |
| n/a | n/a | ||
| number | No | The amount of the chargeback in the currency it occurred in. | |
| ISO 4217 currency code | No | The currency the chargeback occurred in. | |
| ISO 8601 date & time with offset | No | Timestamp when the chargeback occurred. | |
| No | Reason classification of the chargeback. | 50 | |
| No | Description of the chargeback reason. | 500 | |
|
| No | The outcome of the chargeback. |
Remittance Transaction
The following fields are required (along with the common fields) if the transaction is a remittance.
Field | Accepted values or format | Required | Type | Notes | Max length |
|
| No | Enum | Payment scheme/network used to route the transaction | |
| No | Enum | Service provider facilitating the remittance transfer | ||
| No | String | Service provider identifier | 150 | |
| No | String | Service provider name | 150 | |
Payment Methods | |||||
|
| No | Enum | Payment method used by sender to initiate remittance | |
|
| No | Enum | Method by which recipient will collect remittance | |
Remittance Transaction Context | |||||
|
| No | Enum | Relationship between sender and recipient | |
|
| No | Enum | Purpose or reason for the remittance transfer | |
|
| No | Enum | Information about where the money originated | |
Cash Pickup Details | |||||
| No | String | Unique identifier for pickup location | 100 | |
| ISO 3166-1 alpha-2 | No | String | Country of pickup location | |
| No | String | Agent network facilitating pickup Western Union, MoneyGram agent Western Union, MoneyGram agent | 100 | |
Agent Information | |||||
|
| No | Enum | The role the agent has within a financial transaction | |
| No | Text | The reference text supplied by an agent | 255 | |
| No | Integer | Index in which the agent came in the original list | ||
| No | String | |||
| Address fields: | No | Object | The address has similar fields as the address in the PartyIdentification model | |
| No | String | The first line of the address | 50 | |
| No | String | The second line of the address | 50 | |
| No | String | The town or city | 50 | |
| No | String | The zip code or postal code | 50 | |
| No | String | The country subdivision or state | 50 | |
| ISO 3166-1 alpha-2 | No | String | The address country | |
|
| No | Enum | The address type | |
| No | Text | Money Transfer Operator name | 255 | |
| No | Text | Money Transfer Operator identifier | 255 | |
| No | Text | Online Remittance Platform name | 255 | |
| No | Text | Online Remittance Platform identifier | 255 |
Customer
The common fields must be submitted on all transactions. At present, you are limited to providing one customer only.
If your customer already exists in Mesh, you just need to provide the external_identifier from the common fields.
If the customer does not exist in Mesh, or you want to update them, you will need to provide the common fields, plus the fields from one of person or company.
Common
Field | Accepted values or format | Required | Description | Max length |
| n/a | Yes | The identifier you assign each customer to uniquely identify them | 255 |
| n/a | No | The acquisition source of a customer | 255 |
| number between 1 and 31 | No | The day of customer acquisition | |
| number between 1 and 12 | No | The month of customer acquisition | |
| number | No | The year of customer acquisition |
Person
If your customer is a person, you also need to provide the following fields.
Field | Accepted values or format | Required | Description | Max length |
| n/a | No | The person's title | 50 |
| n/a | Yes (if | The person's full name, if any other name fields are populated this field should be null | 255 |
| n/a | No | The person's first name | 50 |
| n/a | No | The person's middle name | 50 |
| n/a | Yes (if | The person's last name | 50 |
| n/a | No | The person's suffix | 50 |
| n/a | No | The last name of the person's mother | 50 |
| n/a | No | The last name of the person's father | 50 |
| number between 1 and 31 | No | The day of birth | |
| number between 1 and 12 | No | The month of birth | |
| number | No | The year of birth | |
|
| No | The person's gender | |
| iso-3166-alpha-2 | No | The person's nationality | |
| iso-3166-alpha-2 | No | The person's country of birth | |
| iso-3166-alpha-2 | No | The person's country of residence or citizenship | |
|
| No | The residential status the person holds for that country of residence | |
|
| No | The address type | |
| n/a | No | The first line of the address | 50 |
| n/a | No | The second line of the address | 50 |
| n/a | No | The town or city | 50 |
| n/a | No | The zip code or postal code | 50 |
| n/a | No | The country subdivision or state | 50 |
| iso-3166-alpha-2 | No | The address country | |
| n/a | No | The customer's email address | |
| Must start with a '+' followed by the country code and then the rest of the number | No | The customer's fax number | |
| Must start with a '+' followed by the country code and then the rest of the number | No | The customer's phone number | |
| RFC-2369 (like http://www.complyadvantage.com | No | The customer's URL | |
|
| No | The type of identity document | |
| n/a | No | The identity document's official number or identifier | |
| iso-3166-alpha-2 | No | The country that issued the identity document | |
| iso-3166-2 | No | The country subdivision that issued the identity document | |
| number between 1 and 31 | No | The day the document was issued | |
| number between 1 and 12 | No | The month the document was issued | |
| number | No | The year the document was issued | |
| number between 1 and 31 | No | The day the document expires | |
| number between 1 and 12 | No | The month the document expires | |
| number | No | The year the document was expires | |
| n/a | No | The person's profession or occupation | |
| n/a | No | The person's source of wealth | |
| number | No | The upper limit for the person's annual salary | |
| number | No | The lower limit for the person's annual salary | |
| iso-4217 | No | The currency of the person's salary | |
| n/a | No | The person's profession or occupation industry | 50 |
| number | No | The person's net worth amount | |
| iso-4217 | No | The person's net worth amount currency | |
| n/a | No | The person's source of income | 50 |
Company
If your customer is a company, you also need to provide the following fields.
Field | Accepted values or format | Required | Description | Max length |
| n/a | Yes | The company's legal name | 255 |
| n/a | No | Any aliases for the company, including trading names and "doing business as" | 50 |
| n/a | No | The industry the company operates in | 50 |
| n/a | No | The source of income of the company | |
| n/a | No | The official company legal type | 50 |
| number between 1 and 31 | No | The day the company was incorporated | 50 |
| number between 1 and 12 | No | The month of the company was incorporated | |
| number | No | The year of the company was incorporated | |
| iso-3166, iso3166-2 | No | The country or state where the company is registered | 6 |
| n/a | No | The official identification number for the company, as it appears on the registry | 50 |
|
| No | The official status for the company, as it appears on the registry | |
|
| No | The address type | |
| n/a | No | The first line of the address | 50 |
| n/a | No | The second line of the address | 50 |
| n/a | No | The town or city | 50 |
| n/a | No | The zip code or postal code | 50 |
| n/a | No | The country subdivision or state | 50 |
| iso-3166-alpha-2 | No | The address country |