Field mappings

📘
This page relates to bank transfer payment batches. For cheques, refer to Issuing cheques

As mentioned in the overview on batches, the fields within the batch file are mapped to properties of a transaction request as follows.

There are four distinct sections that make up a transaction request, and for simplicity we've tried to ensure that an appropriate naming convention is used so you can determine where a given field will be mapped based solely on its name. These sections, and the fields that make up these sections are discussed below.

Transaction Fields

These fields are associated with the transaction itself, and do not have a prefix. The transaction is considered to the the "container" for recipient data, as the recipient is in effect a sub-object of the transaction.

📘
Parameters with an * (asterisk) are mandatory. Bracketed asterisks (*) are for mandatory parameters with exceptions.

Name	Datatype	Comments
CorrelationId	String (64)	This could be the unique ID in your system, or a unique request ID. We only store this value, nothing is done with it.
DateSearchMode	String: 'Forward' or 'Backward' (default)	Used for queued transactions to determine which direction to search for a value date. See Queued Transaction Overview for details.
ExternalReference1	String (128)	Optional data provided by your system. Typically used to store the primary key of a transaction in your system.
ExternalReference2	String (128)	Optional data provided by your system.
ExternalReference3	String (128)	Optional data provided by your sysem.
Extra	String (4000)	An optional string that your system can send to ours which allows you to store additional data alongside the transaction. This is typically used to store structred data as JSON.
FundingType	String: 'Immediate' (default), 'Deferred' or 'FundingMerchantLookup'	This defines the funding model for the transaction. For details of what this field is used for, please see Funding Type
LatePaymentMode	String: 'Cancel' (default) or 'Continue'	Defines what happens with a queued deferred transaction if your payment doesn't show up in time. See Queued Deferred Transaction Overview for details.
RateGroupDurationInDays	Integer	Specifies the number of days to use when creating a rate group (for deferred transactions). Either RateGroupDurationInDays or RateGroupId needs to be specified for deferred TX. See here for further details.
RateGroupId	Integer	If used, defines the rate group used when creating deferred transactions. Either RateGroupDurationInDays or RateGroupId needs to be specified for deferred TX. See here for further details.
ReceiveValue(*)	Decimal	The amount you wish the recipient to receive. See the notes below.
RequestedValueDate	Date	For queued or queued deferred transactions, this is the date you would like the recipient to receive their funds. Note - this is not the Value Date - we compute that in our system and return it to you. See Queued Transaction Overview for more details.
RouteType	String. If omitted, 'BankAccount' is the default.	See the documenttation on Rules for further details here.
SendAccountId	Integer	You may have linked accounts setup, in which case this allows you to select which available account to debit funds from.
SendCurrency*	ISO 4217 currency code such as 'GBP', 'EUR' and 'USD'.
SendValue(*)	Decimal	The amount you wish to send to the recipient, in the SendCurrency. See notes below.
Source	String (64)	Another optional field, you may wish to use this to define which of your systems the transaction came from. Typically unused.

📘
(*) When posting a transaction, you need to either specify how much you want to send, with a value in the SendValue column, or how much you want the recipient to receive, in which case you use the ReceiveValue field. Use one or the other of these values, but not both.

Recipients (both types)

There are two types of recipient in our system - regular recipients (i.e. recipients you are only likely to pay once), and stored recipients, which you may wish to pay multiple times.

Recipient Fields

The following are the fields to specify for a recipient.

📘
Parameters with an * (asterisk) are mandatory.

Name	Datatype	Comments
RecipientAddress	String (256)	For unstructured addresses, and will be overwritten by the structured address if both are supplied.
RecipientAddressStreetName	String (128)	For structured addresses
RecipientAddressBuildingNumber	String (16)	For structured addresses
RecipientAddressLine1	String (128)	For structured addresses
RecipientAddressLine2	String (128)	For structured addresses
RecipientAddressTownName	String (128)	For structured addresses: City
RecipientAddressPostCode	String (128)	For structured addresses: Zip Code
RecipientAddressCountrySubDivision	String (128)	For structured addresses: e.g. US States
RecipientAddressCountry	String (2)	For structured addresses: Country Code
RecipientBirthdate	Date
RecipientCountry*	String (2) - ISO 3166 Alpha 2 such as GB, DE and FR
RecipientCurrency*	String (3) - ISO 4217 such as GBP, USD or AUD
RecipientEmail	String (128)
RecipientName*	String (256)
RecipientNationality	String (2) - ISO 3166 Alpha 2 such as GB, DE and FR
RecipientPhoneNumber	String (32)
RecipientReference*	String (128)*	This is the reference that typically shows on the recipients bank statement
RecipientType	Person (the default if not supplied) or Business	Defines the type of recipient. This is typically an individual but may be a business entity.

The RecipientReference field supports a maximum of 128 characters, however, depending on the route this value may be significantly shorter. See the documentation on Rules for further information as to how to determine the fields that are mandatory for a given route. The field validations are route dependent and details can be found on the Route Types page.

Stored Recipient Fields

The following fields are those that are used when selecting an existing recipient.

📘
Parameters with an * (asterisk) are mandatory.

Name	Datatype	Comments
RecipientEmail	String (128)
RecipientReference*	String (128)*	This is the reference that typically shows on the recipients bank statement
StoredRecipientId*	String (64)	This defines the unique ID of the stored recipient, and is typically the primary key in your system for the stored recipient. When you create stored recipients in our system, you can supply this value at that point. For more information please see the documentation on Recipients. This value is the ExternalStoredRecipientId from the stored recipient API.

Name

Datatype

Comments

RecipientEmail

String (128)

RecipientReference*

String (128)*

This is the reference that typically shows on the recipients bank statement

StoredRecipientId*

String (64)

This defines the unique ID of the stored recipient, and is typically the primary key in your system for the stored recipient.

When you create stored recipients in our system, you can supply this value at that point.

For more information please see the documentation on Recipients.

This value is the ExternalStoredRecipientId from the stored recipient API.

As for regular recipients, the length of the RecipientReference field is dependant on the destination country.

Account Fields

There are a large number of fields associated with an account, and these are all dependant on the destinarion country and currency. You can omit any of these fields you're not using - so if for example your batch file contains only payments to Europe, you can just specify the IBAN and SWIFT codes and omuit all other columns entirely. You only need column headers in the file for the columns you're using.

Property	Type	Description
AccountAbaCode	String	ABA code
AccountNumber	String	Account number
AccountBankAccountType	String	Bank account type. Values will vary by country. For US/USD, you can use "Checking" or "Savings", if omitted then the deafult is "Checking".
AccountBankAddress	String	Bank address
AccountBankCity	String	Bank city
AccountBankMfo	String	Payee's bank MFO
AccountBankName	String	Bank name
AccountBban	String	BBAN
AccountBIK	String	BIK Code
AccountBinOrIin	String	BIN or IIN
AccountBranchAgencyCode	String	Branch agency code
AccountBranchCode	String	Branch code
AccountBranchName	String	Branch name
AccountBsbCode	String	Bank State Branch code
AccountChineseId	String	Chinese Id
AccountClabe	String	CLABE
AccountIban	String	IBAN
AccountIdCardOrPassportNumber	String	ID card or passport number
AccountIfscCode	String	IFSC code
AccountKnpOrUpdc	String	KNP or UPDC
AccountKonstant Symbol	String	Konstant symbol
AccountNibCode	String	NIB code
AccountNuban	String	NUBAN
AccountPaymentCode	String	Payment code
AccountPaymentPurpose	String	Purpose of payment
AccountProvince	String	Province
AccountRegistrationNumber	String	Registration number
AccountRoutingNumber	String	Routing number
AccountSortCode	String	Sort code
AccountSpecificSymbol	String	Specific symbol
AccountSwift	String	Swift code
AccountTaxId	String	Tax Id
AccountVariableSymbol	String	Variable symbol
AccountVoCode	String	VO code
AccountBankGiro	String	Swedish BankGiro Number
AccountPlusGiro	String	Swedish PlusGiro Number
AccountOcrReferenceNumber	String	OCR Reference Number
AccountBankCode	String	Bank Code
AccountKidReferenceNumber	String	Swedish KID Reference Number

All of the account fields have validation associated with them based on rules. Please see the Rules section for details, and login to the Merchant Administration System for the details of specific country/currency combinations.

Originator Fields (optional)

Some of our merchants send in tranasctions for which they are not the originator - this might be the case if you are an aggregator and receive transactions from your customers which are passed on to us.

In this case we'll have set you up as requiring to send originator details to us. These fields identify the originator of the funds. The fields are as follows and are all mandatory, should you wish to add originator data to the batch line.

Name	Datatype	Comments
OriginatorAddress	String (256)
OriginatorIdentifier	String (256)	Commonly the primary key in your system for the originator, but could also be details such as a National Insurance number in the UK, or a Social Security number in the US.
OriginatorName	String (256)