# File Based Payouts

You can instruct a payout through a file based upload in [the portal](https://payouts.fisglobal.com/) or through a secure file transfer (SFTP). The file must capture all the required fields as per the guidance below (some mandatory fields will vary depending on the country - see the [country coverage guide](/products/account-payouts/v2/coverage) for more details). If any mandatory fields are not captured, the entire file will be rejected.

Create a batch of **up to 500 payouts** within the file and initiate a single request to have these processed.

## Requirements

### Payout files must be:

* submitted as CSV (Comma Separated Value) files
* submitted using a different file name each time
* using type "text" when using Microsoft Excel - failure to do this, may result in leading zeros within fields such as 'accountNumber' being removed


Note
Field Names starting with `remitter_` should only be provided when additional information about the party, sending the funds, is required. This information is communicated during the onboarding process.

### Payout level parameters

| Field Name | Description | Data Type/Format | Required? | Min-Max Length | Validation Criteria |
|  --- | --- | --- | --- | --- | --- |
| `entity` | This 6-digit reference is given to you by your Implementation Manager during the onboarding process. | AN | Conditional | 6 | Special characters are restricted. The value supplied is checked to be valid. It must also match the entity for which authorization has been supplied. |
| `transactionReference` | Unique reference for the payout request provided by you. | AN | ✅ | 6-50 | [Special characters](/products/account-payouts/appendix#special-characters) are allowed. |
| `countryCode` | Country code of the payout destination. | A | ✅ | 2 | [ISO 3166-1 Alpha-2 code](/products/reference/supported-countries-currencies#iso-country-codes) |
| `sourceCurrency` | Source currency for the payout (if different to target currency FX is applied). | A | ✅ | 3 | ISO 4217Valid [currency codes](/products/reference/supported-countries-currencies#iso-currency-codes). |
| `sourceAmount` | Source amount (if target amount is not stated, this amount is used). FX rate of the payout is applied by us, therefore, only one of the `sourceAmount` or `targetAmount` is required in your request. | N | Conditional | 1-10 | Must be a positive value up to 2 decimal places. |
| `targetCurrency` | Target currency sent in the payout request (if different to source currency FX, is applied). | A | ✅ | 3 | ISO 4217Valid [currency codes](/products/reference/supported-countries-currencies#iso-currency-codes). |
| `targetAmount` | Target amount (if source amount is not specified, this amount is used). FX rate of the payout is applied by us, therefore, only one of the `sourceAmount` or `targetAmount` is required in your request. | N | Conditional | 1-10 | Must be a positive value up to 2 decimal places. |
| `narrative` | Reference that may appear on beneficiary statements. | String | ❌ | 6-50 | [Special characters](/products/account-payouts/appendix#special-characters) are allowed. |
| `purposeOfPaymentCode` | The code that represents the purpose of payment. This is mandatory for some payout routes - please check [country specific requirements](/products/account-payouts/v2/coverage). | A | Conditional | Value | For the full list of values see the [appendix](/products/account-payouts/v2/appendix). |
| `purposeOfPaymentNarrative` | Description for purpose of payment. | String | ❌ | 1-35 | [Special characters](/products/account-payouts/appendix#special-characters) are allowed. |
| `fastPayment` | Flag for a fast payment. If a value is provided, it must always be "Y". | A | ❌ | Value | The value supplied for the field must be "Y" or left blank. |
| `transactionTypeCode` | Type of transaction code (for example "TT04" that refers to "Business to Customer"). This is mandatory for some payout routes - please check [country specific requirements](/products/account-payouts/v2/coverage). | AN | Conditional | Value | For the full list of values see the [appendix](/products/account-payouts/v2/appendix). |
| `channel` | Preferable channel for the payment (for example "WIRE"). | A | ❌ | Value | For the full list of values see the [appendix](/products/account-payouts/v2/appendix). |
| `quoteId` | ID of the FX quote for the payment request. This must be a valid, active quote which is for the same source and target currencies as the payout request. It must have valid `intent` of "FORWARD FX" or "PAYOUT". | String | ❌ |  |  |
| `scheduleDate` | Scheduled date of the payout request. | date | ❌ | 10 | Must be a Gregorian calendar date with ISO format 8601 YYYY-MM-DD |
| `bankDetails_beneficiaryAccountTypeCode` | Type of account code (for example "AC01" that refers to "Checking"). | AN | ❌ | Value | For the full list of allowed values see the [appendix](/products/account-payouts/v2/appendix). |
| `bankDetails_beneficiaryAccountNumber` | Beneficiary bank account number. You must either provide an account number or an IBAN. | String | Conditional | 1-35 | [Special characters](/products/account-payouts/appendix#special-characters) are allowed. |
| `bankDetails_iban` | Beneficiary IBAN. You must either provide an account number or an IBAN. | AN | Conditional | 1-34 |  |
| `bankDetails_branchCode` | Beneficiary account branch code. | String | ❌ | 1-35 | [Special characters](/products/account-payouts/appendix#special-characters) are allowed. |
| `bankDetails_bankCode` | Beneficiary account bank code. | String | ❌ | 1-35 | [Special characters](/products/account-payouts/appendix#special-characters) are allowed. |
| `bankDetails_swiftBic` | Beneficiary bank account SWIFT/BIC | AN | ❌ | 8 or 11 | [Special characters](/products/account-payouts/appendix#special-characters) are allowed. |
| `bankDetails_bankName` | Beneficiary bank name | String | ✅ | 1-35 | [Special characters](/products/account-payouts/appendix#special-characters) are allowed. |
| `bankDetails_address_street` | Street address of the beneficiary's bank. | String | ❌ | 1-35 | [Special characters](/products/account-payouts/appendix#special-characters) are allowed. |
| `bankDetails_address_additionalAddressLine` | Additional address line of the beneficiary's bank. | String | ❌ | 1-35 | Special characters are allowed |
| `bankDetails_address_city` | City of the beneficiary's bank. | String | ❌ | 1-35 | Special characters are allowed |
| `bankDetails_address_state` | State or province of the beneficiary's bank. | String | ❌ | 2-35 | Special characters are allowed |
| `bankDetails_address_postCodeOrZipCode` | Postcode or ZipCode of the beneficiary's bank. | String | ❌ | 1-20 | Special characters are allowed |
| `bankDetails_address_countryCode` | Country code of the beneficiary's bank. | A | ❌ | 2 | [ISO 3166-1 Alpha-2 code](/products/reference/supported-countries-currencies#iso-country-codes) |
| `beneficiary_customerPartyId` | The ID of the remitter: Domain ID, Account Number, Tax ID, BIC, Internal Customer ID or any other numerical or alphanumerical unique identifier of the customer where the payment request has originated. This field will be available for use as part of the future enhancements to the Account Payouts API in 2025 | AN | ❌ | 1-35 | Special characters are restricted. Value supplied must be in the format of 1-35 alphanumeric characters. |
| `beneficiary_typeCode` | Entity description code for the beneficiary (for example "PD02" that refers to "Individual"). | AN | ✅ | Value | For the full list of allowed values see the [appendix](/products/account-payouts/v2/appendix). |
| `beneficiary_titleCode` | Title code for the Individual (applicable if `beneficiary_typeCode` is "Individual"). Must not be provided when type is not "Individual". | AN | Conditional | Value | For the full list of allowed values see the [appendix](/products/account-payouts/v2/appendix). |
| `beneficiary_firstName` | First name of the beneficiary. Mandatory if `beneficiary_typeCode` is "Individual". | AN | Conditional | 1-50 | [Special characters](/products/account-payouts/appendix#special-characters) are allowed. See [formatting rules](/products/reference/formatting#name-field-formatting-account-payouts-api) |
| `beneficiary_middleName` | Middle name of the beneficiary (applicable if `beneficiary_typeCod`e is "Individual"). | AN | ❌ | 1-50 | [Special characters](/products/account-payouts/appendix#special-characters) are allowed. See [formatting rules](/products/reference/formatting#name-field-formatting-account-payouts-api) |
| `beneficiary_lastName` | Last name of the beneficiary. Mandatory if `beneficiary_typeCode` is is "Individual". | AN | Conditional | 1-50 | [Special characters](/products/account-payouts/appendix#special-characters) are allowed. See [formatting rules](/products/reference/formatting#name-field-formatting-account-payouts-api) |
| `beneficiary_companyName` | Name of the party if not an individual. Mandatory if `beneficiary_typeCode` is "Institution", "Government" or "Company". Must not be provided when type is "Individual". | String | Conditional | 1-140 | [Special characters](/products/account-payouts/appendix#special-characters) are allowed. |
| `beneficiary_dateOfBirth` | Date of birth or date of incorporation of the beneficiary. | Date | ❌ | 10 | Must be a Gregorian calendar date with ISO 8601 format YYYY-MM-DD. |
| `beneficiary_email` | E-mail address of the beneficiary. This field will be available for use as part of the future enhancements to the Account Payouts API in 2025 | String | ❌ |  | A valid e-mail address format |
| `beneficiary_telephony_phoneNumber` | Phone number of the beneficiary. Mandatory if `prefix` has been provided. | N | Conditional | 1-20 | Special characters are restricted. |
| `beneficiary_telephony_prefix` | Phone dialing country code of the beneficiary.  Mandatory if `phoneNumber` has been provided. | N | Conditional | 1-3 | Special characters are restricted.International country calling code following ITU-T standard.Must be 1-3 digitse.g. "44" or "420" |
| `beneficiary_identity_identityTypeCode` | Type of identification. Mandatory if `identityNumber` is populated. | AN | Conditional | Value | For the full list of allowed values see the [appendix](/products/account-payouts/v2/appendix). |
| `beneficiary_identity_identityNumber` | Identification number that is presented in the identification type. Mandatory if `IdentityTypeCode` is populated. | String | Conditional | 1-35 | [Special characters](/products/account-payouts/appendix#special-characters) are allowed. |
| `beneficiary_identity_issuingCountry` | Country of identification type origin.  Mandatory if `identityTypeCode`/`identityNumber` is populated. | A | Conditional | 2 | [ISO 3166-1 Alpha-2 code](/products/reference/supported-countries-currencies#iso-country-codes) |
| `beneficiary_identity_issuingInstitution` | Issuing institution that provided identification type. | String | ❌ | 1-35 | [Special characters](/products/account-payouts/appendix#special-characters) are allowed.  Cannot be provided if the conditional fields in the identity section are missing. |
| `beneficiary_identity_startDate` | Identification type start date. | Date | ❌ | 10 | Must be a Gregorian calendar date with ISO 8601 format YYYY-MM-DD.  Cannot be provided if conditional fields in the identity section are missing. |
| `beneficiary_identity_endDate` | Identification type end date. | Date | ❌ | 10 | Must be a Gregorian calendar date with ISO 8601 format YYYY-MM-DD.  Cannot be provided if conditional fields in the identity section are missing. |
| `beneficiary_address_addressTypeCode` | Type of beneficiary address code (for example "AD02" that refers to "Business"). | AN | ❌ | Value | For the full list of allowed values see the [appendix](/products/account-payouts/v2/appendix). |
| `beneficiary_address_street` | Street address of the beneficiary. | String | ❌ | 1-35 | [Special characters](/products/account-payouts/appendix#special-characters) are allowed. |
| `beneficiary_address_additionalAddressLine` | Additional address line of the beneficiary. | String | ❌ | 1-35 | [Special characters](/products/account-payouts/appendix#special-characters) are allowed. |
| `beneficiary_address_city` | City of the beneficiary's address. | String | ❌ | 1-35 | [Special characters](/products/account-payouts/appendix#special-characters) are allowed. |
| `beneficiary_address_state` | State or province of the beneficiary's address. | String | ❌ | 2-35 | [Special characters](/products/account-payouts/appendix#special-characters) are allowed. |
| `beneficiary_address_postCodeOrZipCode` | Postcode/ZipCode of the beneficiary's address. | String | ❌ | 1-20 | [Special characters](/products/account-payouts/appendix#special-characters) are allowed. |
| `beneficiary_address_countryCode` | Country code (for example "GB") of the beneficiary address. | A | ❌ | 2 | [ISO 3166-1 Alpha-2 code](/products/reference/supported-countries-currencies#iso-country-codes) |
| `beneficiary_address_residentialStatusCode` | Type of residency code (for example "RS01" that refers to "Resident"). | AN | ❌ | Value | For the full list of allowed values see the [appendix](/products/account-payouts/v2/appendix). |
| `remitter_customerPartyId` | The ID of the remitter: Domain ID, Account Number, Tax ID, BIC, Internal Customer ID or any other numerical or alphanumerical unique identifier of the customer where the payment request has originated. This field will be available for use as part of the future enhancements to the Account Payouts API in 2025 | AN | ❌ | 1-35 | Special characters are restricted. Value supplied must be in the format of 1-35 alphanumeric characters. |
| `remitter_typeCode` | Entity description code for the remitter (for example "PD02" that refers to "Individual"). | AN | ✅ | Value | For the full list of allowed values see the [appendix](/products/account-payouts/v2/appendix). |
| `remitter_titleCode` | Title code for the Individual (applicable if `remitter_typeCode` is "Individual"). Must not be provided when type is not "Individual". | AN | Conditional | Value | For the full list of allowed values see the [appendix](/products/account-payouts/v2/appendix). |
| `remitter_firstName` | First name of the remitter. Mandatory if `remitter_typeCode` is "Individual". | AN | Conditional | 1-50 | [Special characters](/products/account-payouts/appendix#special-characters) are allowed. See [formatting rules](/products/reference/formatting#name-field-formatting-account-payouts-api) |
| `remitter_middleName` | Middle name of the remitter (applicable if `remitter_typeCode` is "Individual"). | AN | ❌ | 1-50 | [Special characters](/products/account-payouts/appendix#special-characters) are allowed. See [formatting rules](/products/reference/formatting#name-field-formatting-account-payouts-api) |
| `remitter_lastName` | Last name of the remitter. Mandatory if `remitter_typeCode` is "Individual". | AN | Conditional | 1-50 | [Special characters](/products/account-payouts/appendix#special-characters) are allowed. See [formatting rules](/products/reference/formatting#name-field-formatting-account-payouts-api) |
| `remitter_companyName` | Name of the party if not an individual. Mandatory if `remitter_typeCode` is "Institution", "Government" or "Company". Must not be provided when type is "Individual". | String | Conditional | 1-140 | [Special characters](/products/account-payouts/appendix#special-characters) are allowed. |
| `remitter_dateOfBirth` | Date of birth or date of incorporation of the remitter. | Date | ❌ | 10 | Must be a Gregorian calendar date with ISO 8601 format YYYY-MM-DD. |
| `remitter_email` | E-mail address of the remitter. This field will be available for use as part of the future enhancements to the Account Payouts API in 2025 | String | ❌ |  | A valid e-mail address format |
| `remitter_telephony_phoneNumber` | Phone number of the remitter.  Mandatory if `prefix` has been provided. | N | Conditional | 1-20 | Special characters are restricted. |
| `remitter_telephony_prefix` | Phone dialing country code of the remitter.  Mandatory if `phoneNumber` has been provided. | N | Conditional | 1-3 | Special characters are restricted.International country calling code following ITU-T standard.Must be 1-3 digitse.g. "44" or "420" |
| `remitter_identity_identityTypeCode` | Type of identification.  Mandatory if `identityNumber` is populated. | AN | Conditional | Value | For the full list of allowed values see the [appendix](/products/account-payouts/v2/appendix). |
| `remitter_identity_identityNumber` | Identification number that is presented in the identification type. Mandatory if `identityTypeCode` is populated. | String | Conditional | 1-35 | [Special characters](/products/account-payouts/appendix#special-characters) are allowed. |
| `remitter_identity_issuingCountry` | Country of identification type origin.  Mandatory if `identityTypeCode`/`identityNumber` is populated. | A | Conditional | 2 | [ISO 3166-1 Alpha-2 code](/products/reference/supported-countries-currencies#iso-country-codes) |
| `remitter_identity_issuingInstitution` | Issuing institution that provided `identificationType`. | String | ❌ | 1-35 | [Special characters](/products/account-payouts/appendix#special-characters) are allowed. Cannot be provided if the conditional fields in the identity section are missing. |
| `remitter_identity_startDate` | Identification type start date. | Date | ❌ | 10 | Must be a Gregorian calendar date with ISO 8601 format YYYY-MM-DD.  Cannot be provided if conditional fields in the identity section are missing. |
| `remitter_identity_endDate` | Identification type end date. | Date | ❌ | 10 | Must be a Gregorian calendar date with ISO 8601 format YYYY-MM-DD.  Cannot be provided if conditional fields in the identity section are missing. |
| `remitter_address_addressTypeCode` | Type of remitter address code (for example "AD02" that refers to "Business"). | AN | ❌ | Value | For the full list of allowed values see the [appendix](/products/account-payouts/v2/appendix). |
| `remitter_address_street` | Street address of the remitter. | String | ❌ | 1-35 | [Special characters](/products/account-payouts/appendix#special-characters) are allowed. |
| `remitter_address_additionalAddressLine` | Additional address line of the remitter. | String | ❌ | 1-35 | [Special characters](/products/account-payouts/appendix#special-characters) are allowed. |
| `remitter_address_city` | City of the remitter's address. | String | ❌ | 1-35 | [Special characters](/products/account-payouts/appendix#special-characters) are allowed. |
| `remitter_address_state` | State or province of the remitter's address. | String | ❌ | 2-35 | [Special characters](/products/account-payouts/appendix#special-characters) are allowed. |
| `remitter_address_postCodeOrZipCode` | Postcode/ZipCode of the remitter's address. | String | ❌ | 1-20 | [Special characters](/products/account-payouts/appendix#special-characters) are allowed. |
| `remitter_address_countryCode` | Country code (for example "GB") of the remitter address. | A | ❌ | 2 | [ISO 3166-1 Alpha-2 code](/products/reference/supported-countries-currencies#iso-country-codes) |
| `remitter_address_residentialStatusCode` | Type of residency code (for example "RS01" that refers to "Resident"). | AN | ❌ | Value | For the full list of allowed values see the [appendix](/products/account-payouts/v2/appendix). |
| `expandableKeyValuePairs` | JSON object of key-value pairs used to supply additional data. The keys and values that you might need to process an account payout to a specific destination, are communicated during the onboarding process. | AN | ❌ |  | Duplicate key names are not allowed |