Bulk Upload (CSV Upload)

Introduction

Currencycloud’s Bulk Upload functionality provides the capability to make conversions and payments in bulk through the Currencycloud Direct application. This is achieved via a file upload (.csv) containing payments, conversions and/or beneficiary information through the application interface.

Please see below for further information and if you have any questions, please contact us at [email protected] or speak to your Relationship Manager.

Bulk upload process

Bulk upload begins by selecting the required file. After the file is validated, i.e. it is in the right format (.csv) and contains all the required information for payments and conversions, the file is then processed and the conversions and/or payments are executed. The history of bulk upload activity is available to the user through the Currencycloud Direct application UI.

File format for bulk upload

The file format that is used for the bulk upload of payments and/or conversions is CSV. The first line of the CSV file must contain the headers of the different fields provided in the file. In Appendix A, you can find all the different values that can be provided through the upload of the CSV file, with the corresponding header text. Note that headers are required in order to successfully process a file. The headers should have the exact same spelling as those provided in Appendix A. If the headers provided do not exactly match the expected ones, a validation error will occur and it will not be possible to process the file any further. Depending on the account setup (Cash Manager Enabled or not), each line of the file may contain a conversion, a payment, a payer, a beneficiary or a combination of these entities. Note: If Microsoft Excel is used for the file creation/editing, please ensure that all the fields are formatted as “Text” in order to avoid any auto-formatting of numbers that could result in a validation failure.

.CSV Examples

Beneficiary reference and update through bulk upload

When uploading payments, existing beneficiaries on the system can be used. In order to reference the correct beneficiary, the “beneficiary_external_reference” field should be used. The first time a beneficiary is paid, the external beneficiary reference along with all the beneficiary details must be provided on the CSV file. For any follow up payments, just the external beneficiary reference value is needed. In the instance that the beneficiary details need to be updated, the external beneficiary reference value needs to be provided along with the values of the fields that need to be updated. Note that only the fields that require updating are needed, all other fields that are already stored on the system, are not required. As an example, if the bank account_number of an existing beneficiary has changed, the only two fields needed to update it through bulk upload are the external beneficiary reference and the new account_number. If these values are provided in the file along with payment instructions, then the beneficiary will be updated first and then the payment will be made based on the updated beneficiary.

Bulk upload main screen

On this screen, the history of bulk upload activity and the status of past bulk uploads can be found. The user can filter the list of existing bulk uploads or search for a specific upload by using the search.

By clicking on the “View Details” button for a specific bulk upload, the user is forwarded to a screen containing the details of the bulk upload or the list of validation errors depending on the status of the bulk upload.

From the “Bulk Upload” main screen and more specifically from the “Bulk Upload” tab, a user can initiate the process to upload a file with payments and/or conversions.

Selecting a file to upload

Through the “Upload File” tab users can start the process of uploading a new file. They can drag and drop the file on the relevant area of the screen or click on the “Browse” link to search for the file they want to upload.

After a file is selected, the validation process starts.

File validation

As soon as a file is selected for upload, the validation process starts. The screen will provide information on the progress of the validation process for the file. The user can navigate away from the page and return back later. As soon as the validation process is completed, an email notification is sent to the user, informing them of the validation process outcome (validation passed or failed). The user can navigate back to the “Bulk Upload” main screen and by selecting the corresponding bulk upload on the list they can see the validation process result (passed or failed).

If there are validation errors, the user can see a list of the errors as well as information on how to resolve them. Based on this feedback the user should be able to update the file and re-upload it on the platform for validation. If no errors are found, the user can proceed further with the processing of the file by clicking on the “Process File” button. At this stage, the user is also able to see an overview of the file contents on the screen.

File processing

After the user clicks the “Process File” button, the file is submitted and the user will see the progress on this screen. The user is able to navigate away from this screen and return back to the “Bulk Upload” main screen where they are able to check the status of the file processing. As soon as the processing is complete, an email notification is sent to the user, informing them of the process outcome.

File format

Header Description Conditions
to_amount If you know the exact amount you want the beneficiary to receive, please provide a value in this field Number that can contain two decimal places. If you don’t specify a to_amount, you must specify a from_amount. Please do not specify both.
to_currency The currency you want the beneficiary to receive 3 character code from the International currency code standard ISO 4217
from_amount If you know the exact amount you want to send and convert into the to_currency, please provide a value in this field Number can contain up to two decimal places. If you don’t specify a from_amount, you must specify a to_amount. Please do not specify both
from_currency The currency you want to convert from 3 character code from the International currency code standard ISO 4217
delivery_date The date you want the payment to be processed and sent to the beneficiary Date field in the ISO 8601 format (YYYY-MM-DD). Mandatory for payments and conversions
bank_account_holder_name The exact name of the beneficiary on the bank account you are paying to. Warning – if this differs to the name the bank has on record, they may reject the payment. Up to 50 characters. Mandatory for payments.
destination_country_code The country of the bank account you are making the payment to 2 character code from the International country code standard
payment_type You can make a “priority” payment which is fast and more expensive, or a “regular” payment which can be slower but is cheaper. The value of this field should be either “priority” or “regular”. Field with options of “priority” or “regular”. Mandatory for payments.
purpose_code When initiating cross-border payments, the central bank of the country may require a purpose to be included with your transaction in order for your payment to be accepted and processed. If a payment purpose code is required but not provided, your payment may be delayed or rejected by the beneficiary bank. Mandatory for specific currencies and countries.
payment_unique_request_id User defined unique id for the payment. An optional field to ensure no duplicate payments are made. Optional field. Up to 255 characters
reference A payment reference which we will attempt to pass to the beneficiary, but may not arrive due to limitations in the banking network Can be up to 50 alphanumeric characters long, but support for this depends on the banking network in the destination country. Mandatory for payments.
reason The reason for the payment Can be up to 50 alphanumeric characters long. Mandatory for payments and conversions.
bic_swift A bank identifier used worldwide 8 or 11 characters and mandatory for most standard payments
account_number The account_number of the beneficiaries’ bank account Conditional field
iban The international bank account_number, mainly used in Europe Up to 32 alphanumeric characters
aba The American Bankers Association number, only used in the USA 9 digit number which is mandatory for regular payments to the USA
bank_code A bank identifier code used for regular payments 4 digit number which is mandatory for regular payments to Singapore

OR

3 digit number which is mandatory for regular payments to Canada

branch_code A bank identifier code used for regular payments 3 digit number which is mandatory for regular payments to Singapore

OR

5 digit number which is mandatory for regular payments to Canada

sort_code A bank identifier code used for regular payments 6 digit number which is mandatory for local payments to the United Kingdom
bank_name The name of the bank receiving the funds Will be automatically populated by us if you specify bic_swift, IBAN, aba or sort_code, otherwise it may need to be provided on the file.
bank_account_type Identifies the type of bank account Required only for regular payments in USD to USA – one of either “checking” or “savings”
beneficiary_external_reference A beneficiary reference that is known to the user, e.g. the beneficiary reference/id used in the users external system/platform String – Required if a payment is made to an existing beneficiary OR if the user wants to update an existing beneficiary record. Up to 50 characters long.
beneficiary_type Identifies the type of beneficiary, which will drive the type of name below One of either “company” or “individual”
beneficiary_company_name The legal name of the company String up to 50 characters long – mandatory if beneficiary_type is “company”
beneficiary_first_name The legal first name of the individual String up to 50 characters long – mandatory if beneficiary_type is “individual”
beneficiary_last_name The legal last name of the individual String up to 50 characters long – required if beneficiary_type is “individual”
beneficiary_address First line of address including building number or name. This should be the legally registered address of the company or primary residence of the individual who is receiving the payment. String up to 50 characters long – mandatory if beneficiary_type is set
beneficiary_city The city or town from the beneficiary’s address String up to 50 characters long – mandatory if beneficiary_type is set
beneficiary_postcode The postal code or zip code from the beneficiary’s address String – mandatory for some countries (US, MX or CA) and if beneficiary_type is set
beneficiary_state_or_province The state or province from the beneficiaries address String – mandatory for some countries (US, MX or CA) and if beneficiary_type is set
beneficiary_country The country code from the beneficiaries address 2 char ISO 3166-1 alpha-2 country code – mandatory if beneficiary_type is set
payer_type Identifies the type of payer, which will drive the type of name below One of either “company” or “individual”
payer_company_name The legal name of the company String up to 50 characters long – mandatory if payer_type is”company”
payer_first_name The legal first name of the individual String up to 50 characters long – mandatory if payer_type is “individual”
payer_last_name The legal last name of the individual String up to 50 characters long – mandatory if payer_type is “individual”
payer_address First line of address including building number or name. This should be the legally registered address of the company, or primary residence of the individual who is making the payment. String up to 50 characters long – mandatory if payer_type is set
payer_city The city or town from the payer’s address String up to 50 characters long – mandatory if payer_type is set
payer_postcode The postal code or zip code from the payer’s address String – mandatory for some countries (US, MX or CA) and if payer_type is set
payer_state_or_province The state or province from the payer’s address Sting – mandatory for some countries (US, MX or CA) and if payer_type is set
payer_country The country code from the payer’s address 2 char ISO country code – mandatory if payer_type is set
payer_date_of_birth If payer is an individual, this is the payer’s date of birth Mandatory date field in the ISO 8601 format (YYYY-MM-DD)
payer_identification_type If payer is a company and this is a priority payment, payer_identification_type. is mandatory and it must be set to incorporation_number Can be up to 50 alphanumeric characters long
payer_identification_value If payer_identification_type is set to incorporation_number this is the actual incorporation number Can be up to 50 alphanumeric characters long

Beneficiary rules by country

Please see below for the beneficiary rules for each payment type, then for each country in alphabetical order. More information related to the payment requirements can be found on the Payment Guides.

Priority payments

If you want a payment to reach the beneficiary as soon as possible and you don’t mind paying for an international wire transfer, you should request a priority payment.

The beneficiary rules for priority payments, are as follows:

  • For GBP payments to the UK (including Jersey, Guernsey and the Isle of Man) – supply account_number and sort_code
  • For payments to the US – supply account_number and aba or account_number and bic_swift
  • To countries that use IBAN (all of Europe and a few other countries – see link below) – supply IBAN and bic_swift
  • For all other types of standard payment – supply account_number and bic_swift

List of countries that use IBAN (PDF)

For any priority payments, following payer and beneficiary info is mandatory:

Field Description Conditions
beneficiary_type Identifies the type of beneficiary, which will drive the type of name below One of either company or individual
beneficiary_company_name The legal name of the company String – required if beneficiary_type is company
beneficiary_first_name The legal first name of the individual String – required if beneficiary_type is individual
beneficiary_last_name The legal last name of the individual String – required if beneficiary_type is individual
beneficiary_address First line of address including building number or name.  This should be the legally registered address of the company, or primary residence of the individual who is receiving the payment. String – required if beneficiary_type is set
beneficiary_city The city or town from the beneficiaries address String – required if beneficiary_type is set
beneficiary_postcode The postal code or zip code from the beneficiaries address String – required for some countries (US, MX or CA) and if beneficiary_type is set
beneficiary_state_or_province The state or province from the beneficiaries address String – required for some countries (US, MX or CA) and if beneficiary_type is set
beneficiary_country The country code from the beneficiaries address 2 char ISO country code – required if beneficiary_type is set
payer_type Identifies the type of payer, which will drive the type of name below One of either company or individual
payer_company_name The legal name of the company String – required if payer_type is company
payer_first_name The legal first name of the individual String – required if payer_type is individual
payer_last_name The legal last name of the individual String – required if payer_type is individual
payer_address First line of address including building number or name.  This should be the legally registered address of the company, or primary residence of the individual who is making the payment. String – required if payer_type is set
payer_city The city or town from the payers address String – required if payer_type is set
payer_postcode The postal code or zip code from the payers address String – required for some countries (US, MX or CA) and if payer_type is set
payer_state_or_province The state or province from the payers address String – required for some countries (US, MX or CA) and if payer_type is set
payer_country The country code from the payers address 2 char ISO country code – required if payer_type is set
payer_date_of_birth If payer is an individual, this is the payer date of birth Mandatory date field in the ISO 8601 format (YYYY-MM-DD)
payer_identification_type If payer is a company and this is a Priority payment, payer_identification_type is mandatory and it must be set to incorporation_number Can be up to 50 alphanumeric characters long
payer_identification_value If payer_identification_type is set to incorporation_number this is the actual incorporation number Can be up to 50 alphanumeric characters long

UAE  – Priority

Field Description Conditions
purpose_code When initiating cross-border payments, the central bank of the country may require a purpose to be included with your transaction in order for your payment to be accepted and processed. If a payment purpose code is required but not provided, your payment may be delayed or rejected by the beneficiary bank. Mandatory. The list of codes for payments to UAE can be found on the relevant support article.

Regular local payments

If you want to send funds using a cheaper method and ensure the amount of money you send arrives with your beneficiary, then you should make a regular payment.

Please see below for the specific beneficiary rules for each destination country Currencycloud currently support regular payments to. These rules are in addition to the mandatory fields mentioned in the CSV File format described earlier in this document, which has been omitted from the list below in the interests of brevity.

Australia – Regular

Field Description Conditions
to_currency The currency you want the beneficiary to receive AUD
account_number The account_number of the beneficiaries bank account Mandatory and between 5 and 20 characters
bic_swift A bank identifier used worldwide Mandatory and 8 or 11 characters
bsb_code A bank branch identifier used in Australia Mandatory and 6 digit number

 Austria – Regular

Field Description Conditions
to_currency The currency you want the beneficiary to receive EUR
iban The international bank account_number, mainly used in Europe 20 alphanumeric characters and mandatory
bic_swift A bank identifier used worldwide 8 or 11 characters and mandatory

Belgium – Regular

Field Description Conditions
to_currency The currency you want the beneficiary to receive EUR
iban The international bank account_number, mainly used in Europe 16 alphanumeric characters and mandatory
bic_swift A bank identifier used worldwide 8 or 11 characters and mandatory

Cyprus – Regular

Field Description Conditions
to_currency The currency you want the beneficiary to receive EUR
iban The international bank account_number, mainly used in Europe 28 alphanumeric characters and mandatory
bic_swift A bank identifier used worldwide 8 or 11 characters and mandatory

Czech Republic – Regular

Field Description Conditions
to_currency The currency you want the beneficiary to receive CZK
iban The international bank account_number, mainly used in Europe 24 alphanumeric characters and mandatory
bic_swift A bank identifier used worldwide 8 or 11 characters and mandatory

Denmark – Regular

Field Description Conditions
to_currency The currency you want the beneficiary to receive DKK
iban The international bank account_number, mainly used in Europe 18 alphanumeric characters and mandatory
bic_swift A bank identifier used worldwide 8 or 11 characters and mandatory

Estonia – Regular

Field Description Conditions
to_currency The currency you want the beneficiary to receive EUR
iban The international bank account_number, mainly used in Europe 20 alphanumeric characters and mandatory
bic_swift A bank identifier used worldwide 8 or 11 characters and mandatory

Finland – Regular

Field Description Conditions
to_currency The currency you want the beneficiary to receive EUR
iban The international bank account_number, mainly used in Europe 18 alphanumeric characters and mandatory
bic_swift A bank identifier used worldwide 8 or 11 characters and mandatory

France – Regular

Field Description Conditions
to_currency The currency you want the beneficiary to receive EUR
iban The international bank account_number, mainly used in Europe 27 alphanumeric characters and mandatory
bic_swift A bank identifier used worldwide 8 or 11 characters and mandatory

Germany – Regular

Field Description Conditions
to_currency The currency you want the beneficiary to receive EUR
iban The international bank account_number, mainly used in Europe 22 alphanumeric characters and mandatory
bic_swift A bank identifier used worldwide 8 or 11 characters and mandatory

Greece – Regular

Field Description Conditions
to_currency The currency you want the beneficiary to receive EUR
iban The international bank account_number, mainly used in Europe 27 alphanumeric characters and mandatory
bic_swift A bank identifier used worldwide 8 or 11 characters and mandatory

Hong Kong – Regular

Field Description Conditions
to_currency The currency you want the beneficiary to receive HKD
account_number The account_number of the beneficiaries bank account Mandatory number between 9 and 11 digits, can include branch_code
bank_name The name of the bank receiving the funds Mandatory and up to 34 characters
bic_swift A bank identifier used worldwide  Mandatory and 8 or 11 characters

 Hungary – Regular

Field Description Conditions
to_currency The currency you want the beneficiary to receive HUF
iban The international bank account_number, mainly used in Europe 24 alphanumeric characters and mandatory
bic_swift A bank identifier used worldwide 8 or 11 characters and mandatory

Ireland – Regular

Field Description Conditions
to_currency The currency you want the beneficiary to receive EUR
iban The international bank account_number, mainly used in Europe 22 alphanumeric characters and mandatory
bic_swift A bank identifier used worldwide 8 or 11 characters and mandatory

Italy – Regular

Field Description Conditions
to_currency The currency you want the beneficiary to receive EUR
iban The international bank account_number, mainly used in Europe 27 alphanumeric characters and mandatory
bic_swift A bank identifier used worldwide 8 or 11 characters and mandatory

Luxembourg – Regular

Field Description Conditions
to_currency The currency you want the beneficiary to receive EUR
iban The international bank account_number, mainly used in Europe 20 alphanumeric characters and mandatory
bic_swift A bank identifier used worldwide 8 or 11 characters and mandatory

Malta – Regular

Field Description Conditions
to_currency The currency you want the beneficiary to receive EUR
iban The international bank account_number, mainly used in Europe 31 alphanumeric characters and mandatory
bic_swift A bank identifier used worldwide 8 or 11 characters and mandatory

Netherlands – Regular

Field Description Conditions
to_currency The currency you want the beneficiary to receive EUR
iban The international bank account_number, mainly used in Europe 18 alphanumeric characters and mandatory
bic_swift A bank identifier used worldwide 8 or 11 characters and mandatory

Norway – Regular

Field Description Conditions
to_currency The currency you want the beneficiary to receive NOK
iban The international bank account_number, mainly used in Europe 15 alphanumeric characters and mandatory
bic_swift A bank identifier used worldwide 8 or 11 characters and mandatory

Poland – Regular

Field Description Conditions
to_currency The currency you want the beneficiary to receive PLN
iban The international bank account_number, mainly used in Europe 28 alphanumeric characters and mandatory
bic_swift A bank identifier used worldwide 8 or 11 characters and mandatory

Portugal – Regular

Field Description Conditions
to_currency The currency you want the beneficiary to receive EUR
iban The international bank account_number, mainly used in Europe 25 alphanumeric characters and mandatory
bic_swift A bank identifier used worldwide 8 or 11 characters and mandatory

Singapore – Regular

Field Description Conditions
to_currency The currency you want the beneficiary to receive SGD
account_number The account_number of the beneficiaries bank account Mandatory number between 9 and 11 digits, can include branch_code
bank_name The name of the bank receiving the funds Mandatory and up to 34 characters
bank_code A bank identifier code used for Regular payments Mandatory 4 digit number
branch_code A bank identifier code used for Regular payments Mandatory 3 digit number

Slovakia – Regular

Field Description Conditions
to_currency The currency you want the beneficiary to receive EUR
iban The international bank account_number, mainly used in Europe 24 alphanumeric characters and mandatory
bic_swift A bank identifier used worldwide 8 or 11 characters and mandatory

Slovenia – Regular

Field Description Conditions
to_currency The currency you want the beneficiary to receive EUR
iban The international bank account_number, mainly used in Europe 19 alphanumeric characters and mandatory
bic_swift A bank identifier used worldwide 8 or 11 characters and mandatory

Spain – Regular

Field Description Conditions
to_currency The currency you want the beneficiary to receive EUR
iban The international bank account_number, mainly used in Europe 24 alphanumeric characters and mandatory
bic_swift A bank identifier used worldwide 8 or 11 characters and mandatory

Sweden – Regular

Field Description Conditions
to_currency The currency you want the beneficiary to receive SEK
iban The international bank account_number, mainly used in Europe 24 alphanumeric characters and mandatory
bic_swift A bank identifier used worldwide 8 or 11 characters and mandatory

UK (including Jersey, Guernsey, Isle of Man) – Regular

Field Description Conditions
to_currency The currency you want the beneficiary to receive GBP
account_number The account_number of the Beneficiaries bank account Number which is mandatory
sort_code A bank identifier code used for Regular payments 6 digit number which is mandatory for local payments to the United Kingdom

US – Regular

Field Description Conditions
to_currency The currency you want the beneficiary to receive USD
account_number The account_number of the beneficiaries bank account Mandatory and up to 17 digits in length
aba The bank identifier used in the USA, known as the American Bankers Association number 9 digit number and mandatory. Please take care to ensure the ACH routing code is supplied and not the Fedwire or Wire Transfer alternative.
bank_account_type Identifies the type of bank account One of either checking or savings
beneficiary_type Identifies the type of beneficiary, which will drive some of the fields below One of either company or individual
beneficiary_company_name The legal name of the company String – required if beneficiary_type is company
beneficiary_first_name The legal first name of the individual String – required if beneficiary_type is individual
beneficiary_last_name The legal last name of the individual String – required if beneficiary_type is individual
beneficiary_address First line of address including building number or name. This should be the legally registered address of the company, or primary residence of the individual who is receiving the payment String – required; must be a US address
beneficiary_ity The city or town from the beneficiaries address String – required; must be a US address
beneficiary_postcode The postal code or zip code from the beneficiaries address String – required; must be a US address, omit hyphens and spaces
beneficiary_state_or_province The state or province from the beneficiaries address String – required if beneficiary_country is US; must be a US address
beneficiary_country The country code from the beneficiaries address 2 char ISO country code – required; must be US
payer_type Identifies the type of payer, which will drive some of the fields below One of either company or individual
payer_company_name The legal name of the company String – required if payer_type is company
payer_first_name The legal first name of the individual String – required if payer_type is individual
payer_last_name The legal last name of the individual String – required if payer_type is individual
payer_address First line of address including building number or name. This should be the legally registered address of the company or primary residence of the individual who is making the payment String – required
payer_city The city or town from the payers address String – required
Payer Postcode The postal code or zip code from the payers address String – required if payer_country is US, omit hyphens and spaces
Payer State or Province The state or province from the payers address String – required if payer_country is US
payer_country The country code from the payers address 2 char ISO country code – required if payer_type is set

Can’t find what you’re looking for?

Contact our support team for general support or our technical support team for help with the API or platform.


Related Topics