Using CSV Uploads
- Technical Writer
- 1 1. Introduction
- 2 2. Masspay payout instructions
- 3 3. The ‘n eyes’
- 4 4. Troubleshooting
- 4.1 4.1. The same CSV file has been previously uploaded
- 4.2 4.2. The CSV file has an invalid field
- 4.3 4.3. The CSV file has more than 1000 rows
- 4.4 4.4. The CSV file is larger than 5MB
- 4.5 4.5. There are insufficient funds in the selected IBAN to cover all payments
- 4.6 4.6. The sender’s IBAN is same as the receiver’s IBAN
- 4.7 4.7. The CSV file does not contain any data
- 4.8 4.8. The CSV file contains duplicate data
- 4.9 4.9. Unable to complete the transaction
- 5 5. Reports
1. Introduction
The Masspay payout instruction functionality is implemented to allow a user to perform multiple payout requests with a single click. Efficiency and productivity are the main drivers of this feature as it allows a user to perform up to 1000 payouts in a single operation.
The focus of this guide is Masspay payout instruction functionality via CSV uploads.
This guide assumes you can access the iSXMoney Dashboard and the Finance menu option.
There are several steps involved in this process as per the following:
What is a CSV file?
As may be noted from the above, a key element in this process is the use of a CSV file. A CSV (comma-separated values) file is essentially a plain text file in which each row includes the data required to create an individual request. The values in each row are separated with commas (not spaces) and rows are separated with a carriage return (i.e., enter). Even though a CSV file can be manually created with a simple text editor, the easiest way is to input the data in Microsoft Excel (or a similar spreadsheet program) and then export the file as a comma-delimited CSV file.
A troubleshooting guide has been included to assist a user in case of errors.
2. Masspay payout instructions
2.1. Access the Masspay Payout Instruction page
On the Dashboard, navigate to the Finance menu on the header and select the Payout Instruction option.
The Masspay Payout Instruction page will load, and a user will be able to view a table of previous payout requests, including batch and individual requests, as per the following:
In the Actions column of the table, the transaction will have two buttons:
The Download button downloads a CSV file that was uploaded for the chosen payout request.
The Report button downloads a CSV file containing a report for the chosen payout request. Refer to Section 5 for more details regarding reports.
Clicking on an entry (i.e., row) in the table (Figure 1) displays the batch details of a payout request, as per the following:
Then, clicking on an entry (i.e., row) in the Associated Payout Transactions table (Figure 2) displays the transaction details of a transaction from a payout request, as per the following:
The following schematic summarises the above-mentioned flow:
Once again, on the Dashboard, navigate to the Finance menu and select the Payout Instruction option.
Prior to creating a payout instruction, a CSV file, in a format that the system can recognize, must be generated. Therefore, a sample CSV file is provided, which may be used as a template to complete the relevant data.
2.2. Download the template CSV file
To download the sample CSV file, a user must click on the arrow icon next to the Actions button (Figure 4).
A drop-down menu will appear. The second and third options in this menu are the “Download sample CSV file version 1” option and the “Download sample CSV file version 2” option respectively.
The difference between the version 1 and version 2 of the sample CSV files is that version 2 includes three additional fields (i.e., Beneficiary Address, Beneficiary City, and Beneficiary Country).
Click on the second or the third option of the menu and a sample CSV file will be downloaded. If this file is not automatically downloaded, then the browser’s permissions to download files must be checked.
Once a sample CSV file has been downloaded, it must be opened with Microsoft Excel (or a similar spreadsheet program). Once opened, a CSV file should resemble one of the figures below, depending on the version downloaded:
The contents of a sample CSV file must be replaced with the actual payout data.
2.3. Create a CSV instruction file
For a payout to be successfully processed, all of the following data must be provided, if version 1 of the downloaded CSV file:
Payment Details (mandatory): a free text description to be used in the account statement. Maximum field length: 75 characters. Alphanumeric characters are allowed. These details are passed into the description fields of the outgoing transactions of ISX Money. The following special characters are allowed: [ ] ? : - + . ' / \ ( ) .
Beneficiary Name (mandatory): the name of the account holder. Maximum field length: 75 characters. Only alphabetic characters are allowed. The following special characters are allowed: [ ] ? : - + . ' / \ ( ) .
Beneficiary Reference (mandatory): a beneficiary reference field that is only visible on the iSXMoney dashboard. This is a description to the merchant that explains the nature of a transaction. Maximum field length: 75 characters. Alphanumeric characters are allowed. The following special characters are allowed: [ ] ? : - + . ' / \ ( ) .
Beneficiary IBAN (mandatory): the IBAN to which the funds will be paid out.
Payment Amount (mandatory): the amount of money to be paid out. Decimals must be separated with a period, not a comma.
Currency (mandatory): the value of this field must always be EUR. This is a case-sensitive field.
Reference ID (mandatory): an arbitrary unique (for the batch) ID that is only visible on the iSXMoney dashboard. Maximum field length: 75 characters. Alphanumeric characters are allowed. The following special characters are allowed: [ ] ? : - + . ' / \ ( ) _.
For a payout to be successfully processed, all of the following data must be provided, if version 2 of the downloaded CSV file:
Payment Details (mandatory): a free text description to be used in the account statement. Maximum field length: 75 characters. Alphanumeric characters are allowed. The following special characters are allowed: [ ] ? : - + . ' / \ ( ) . These details are passed into the description fields of the outgoing transactions of ISX Money.
Beneficiary Name (mandatory): the name of the account holder. Maximum field length: 75 characters. Only alphabetic characters are allowed. The following special characters are allowed: [ ] ? : - + . ' / \ ( ) .
Beneficiary Reference (mandatory): a beneficiary reference field that is only visible on the iSXMoney dashboard. This is a description to the merchant that explains the nature of a transaction. Maximum field length: 75 characters. Alphanumeric characters are allowed. The following special characters are allowed: [ ] ? : - + . ' / \ ( ) .
Beneficiary IBAN (mandatory): the IBAN to which the funds will be paid out.
Payment Amount (mandatory): the amount of money to be paid out. Decimals must be separated with a period, not a comma.
Currency (mandatory): the value of this field must always be EUR. This is a case-sensitive field.
Reference ID (mandatory): an arbitrary unique (for the batch) ID that is only visible on the iSXMoney dashboard. Maximum field length: 75 characters. Alphanumeric characters are allowed. The following special characters are allowed: [ ] ? : - + . ' / \ ( ) _.
Beneficiary Address (conditional): the address of the beneficiary. Maximum field length: 75 characters. Alphanumeric characters are allowed.
Beneficiary City (conditional): the city of the beneficiary. Maximum field length: 75 characters. Alphanumeric characters are allowed.
Beneficiary Country (conditional): the country code representing the country of the beneficiary. Only alphabetic characters are allowed. This field must be expressed as an ISO 3166-1 Alpha-2 code.
Conditional fields
The Beneficiary Address, Beneficiary City, and Beneficiary Country fields are conditional because all three of these fields must be completed or none of them.
Character sets
Certain restrictions are imposed on transfer protocols in terms of the allowed character sets. For instance, SEPA only accepts the Latin character set. Therefore, a user must ascertain that text fields (e.g., Payment Details, Beneficiary Name, Beneficiary Reference, and Reference ID) comply with these restrictions.
Complete the previously downloaded sample CSV file. For each payout, supply the above-mentioned data on a separate row.
For explanatory purposes, the following figures depict sample data of CSV files that are formatted correctly:
Once a CSV file has been completed, save it, ensuring that the file format being saved is set to CSV.
2.4. Create a new Batch
With a CSV file now completed and saved, access the Payout Instruction page.
Once again, click on the arrow icon next to the Actions button (Figure 9).
A drop-down menu will appear. The first option in this menu is the Create a new Batch option.
Click on this option. The following modal window should now be loaded:
Complete the fields below in the modal window:
API client (mandatory): select the appropriate credentials from the drop-down widget.
Merchant (mandatory): select the appropriate merchant ID from the drop-down widget.
Sender’s IBAN (mandatory): select the appropriate IBAN from the drop-down widget.
Description: a free text field where an informative description may be added for future reference.
With the above-mentioned data provided, a CSV file that was previously created may now be uploaded. To do this, click on the applicable grey area and then find and select a CSV file.
Once a CSV file has been successfully uploaded, a green confirmation message will be displayed with a summary outlining the number of total transactions and the total fees. The figure below (Figure 11) shows an example of this message. At this stage, a user has two possible options:
Click the Start button to execute the transaction; or
Click the Close button to cancel the process.
If the data processing fails, a red error message will be displayed, and a user will be instructed to make any relevant amendments.
2.5. Payout instruction execution
Clicking on the Start button will redirect a user to the Payout Instruction Batch Details page where the state and details of the batch payout will be displayed.
The State of the batch payout will show only one of the following:
Processing: the execution of the batch payout is still being processed.
Waiting_network: the API call has been attempted for all batch records at least once.
Complete: the batch payout has been sent successfully.
The data related to each transaction can be reviewed by clicking on each transaction in the list of the Associated Payout Transactions.
2.6. Batch statuses & transaction states
On the Payout Instruction page, a user is able to view a table of previous payout requests, including batch and individual requests.
Clicking on an entry (i.e., row) in the table displays the batch details of a payout request.
In the table, there are various columns that indicate batch statuses and transaction states.
2.6.1. Batch statuses
Batch status | Final | Comment |
|---|---|---|
Pending | No | Submitted batch request received. Batch is being loaded & validated. User review may be required. |
Pending_approval | No | User has confirmed to proceed with a batch submission but there are conditions in place to require approval by someone else. |
Cancelled | Yes | User has decided not to proceed with a previously submitted batch. |
Failed | Yes | Batch encountered a fatal error, or it never received confirmation for proceeding or cancelling. |
Processing | No | Transactions are being processed. |
Waiting_network | No | Funds for one or more transactions in the batch are awaiting settlement. |
Reprocessing | No | Transactions have been executed using instant processing. However, if even transaction fails, the system then uses alternative methods. |
Complete | Yes | All transactions in a batch have been finalised. |
2.6.2. Transaction states
Transaction state | Final | Comment |
|---|---|---|
Cancelled | Yes | Upon review, a user decided not to proceed with batch execution. |
Pending | No | Transaction execution is initiated. But, before transferring any funds pertaining to the transaction, further validations take place. |
Failed | Yes | A transaction has encountered a fatal error, for example, it failed validation or one of the dependent systems is experiencing issues. |
Succeeded | Yes | A transaction has been processed successfully & has been settled. |
3. The ‘n eyes’
It is important to point out that in the previous scenarios, no approval was required for the batch payouts to take place. However, in reality, it is not always this simple because there are usually various parties involved in the process, hence, the ‘n eyes’ title.
In general, the user that starts the batch payouts process is known as the ‘Payouts initiator’ and the user that approves the batch payouts is known as the ‘Payouts approver’. In this case, since there are two users involved, the process is known as ‘4 eyes’. In essence, the payouts initiator and payout approver are simply users allocated with necessary permissions in order to perform their tasks. In our case in Section 1, the user that started the batch payouts process and the user that did the approving was one and the same user.
3.1. Payout initiation
During the batch payout initiation process, the process is exactly the same as before, with the exception of the turquoise button near the bottom of the modal window. Because an initiator is required in this case, the label of the button has changed from ‘Start’ to ‘Submit for Approval’ as per the figure below:
Clicking on the Submit for Approval button will redirect a user to the Payout Instruction Batch Details page where the state and details of the batch payout will be displayed.
The striking difference on this screen is that the state of the batch payout will now show Pending Approval as per the figure below:
Therefore, a payout approver now needs to approve or reject this batch payout.
3.2. Payout approval
As soon as the payout approver logs into the system, the Payout Instruction Batch Details page loads where the state and details of the batch payout will be displayed as per the following figure:
As may be noticed from Figure 15 above, there are now two additional buttons next to the Download button in the Actions column of the table:
The Approve button allows a payouts approver to approve the batch payout.
The Reject button allows a payouts approver to reject the batch payout.
Assuming, in this case, that the batch payout is to be approved. The payout approver must click on the Approve button in the Actions column of the table (Figure 14).
Having clicked on the Approve button, the table on the Payout Instruction Batch Details page should resemble the following figure:
In the State column of the table, the batch payout will show only one of the following:
Processing: the execution of the batch payout is still being processed.
Waiting_network: the API call has been attempted for all batch records at least once.
Complete: the batch payout has been sent successfully.
In the Actions column of the table, the batch payout will now have two buttons:
The Download button downloads a CSV file that was uploaded for the chosen payout request.
The Report button downloads a CSV file containing a report for the chosen payout request. Refer to Section 5 for more details regarding reports.
3.3. Payout rejection
In the above subsection, the payout approval process was discussed. Conversely, in this subsection, the payout rejection procedure will be considered.
Once again, as soon as the payout approver logs into the system, the Payout Instruction Batch Details page loads where the state and details of the batch transaction will be displayed as per the following figure:
As may be observed from Figure 16 above, there are now two additional buttons next to the Download button in the Actions column of the table:
The Approve button allows a payouts approver to approve the batch payout.
The Reject button allows a payouts approver to reject the batch payout.
Assuming, in this case, that the batch payout is to be rejected. The payout approver must click on the Reject button in the Actions column of the table (Figure 16).
Having clicked on the Reject button, the table on the Payout Instruction Batch Details page should resemble the following figure:
In the State column of the table, the batch payout will show only the following:
Cancelled: the execution of a batch payout was manually cancelled by an approver.
In the Actions column of the table, the batch payout will now have only one button:
The Download button downloads a CSV file that was uploaded for the chosen payout request.
4. Troubleshooting
4.1. The same CSV file has been previously uploaded
If a CSV file has been successfully processed previously, the system will not allow the same file to be uploaded and processed again. The system reviews the CSV file and if the file has been previously used, it will not allow a user to proceed and it will present the following error message:
Suggested solution
This error is caused when the contents of an uploaded CSV file match exactly the contents of a file used in a previous payout instruction. This error is triggered to avoid erroneously filling duplicate payout instructions. If the contents of a file are correct, then slightly adjust the description message or the reference ID of one of the transactions; then, save the file and re-upload it.
4.2. The CSV file has an invalid field
If a CSV file has an invalid field entry or an error, a user will be presented with the following error message:
Suggested solution
Follow the instructions in the error message and correct the errors in the CSV file; then, save the file and re-upload it.
4.3. The CSV file has more than 1000 rows
The maximum number of rows and transactions per batch are 1000. If more than 1000 transactions or rows are included in a CSV file, then the transaction will be rejected, and the following error message will be presented:
Suggested solution
There is the limit of 1000 transactions per payout instruction. To process more than 1000 transactions, create multiple CSV files containing payout instructions with less than 1000 entries in each file.
4.4. The CSV file is larger than 5MB
Should a CSV file be larger than 5MB, then the system will reject the file and a user will be presented with the following error message:
The 5MB file size limit per CSV file has been added as an additional security feature. A correctly formatted CSV file with 1000 transactions should be significantly smaller than 5MB. Check that the CSV file is correctly formatted and that the correct file is being uploaded.
4.5. There are insufficient funds in the selected IBAN to cover all payments
If there are not enough funds in an account to cover all payments, then the following error will be presented:
Suggested solution
Top up the required funds in the relevant account to cover the total payout transaction amount or select a different account with a sufficient balance.
4.6. The sender’s IBAN is same as the receiver’s IBAN
If a user has accidentally requested a transaction to be sent to the same IBAN as that of the sender, then the following error message will be presented:
Suggested solution
Review the entries in the CSV file; then, save the file and re-upload it.
4.7. The CSV file does not contain any data
If a user has uploaded a CSV file that does not contain any data (i.e., records), then the following error message will be presented:
Suggested solution
Review the entries in the CSV file; then, save the file and re-upload it.
4.8. The CSV file contains duplicate data
If a user has added multiple rows to a CSV file, which contain the same data, then the following error message will be presented:
Suggested solution
This error is caused when several rows of an uploaded CSV file match each other exactly. This error is triggered to avoid erroneously filling duplicate payout instructions. If the contents of a file are correct, then slightly adjust the description message or the reference ID of one of the transactions; then, save the file and re-upload it.
4.9. Unable to complete the transaction
If the system is having issues completing the transaction, then the following error message will be presented:
Suggested solution
This error is caused when the system is experiencing issues processing the transaction. Retry the process by creating a new batch. If the issue persists, then contact your system administrator.
5. Reports
A report is available for download on the Paydentity dashboard for every batch payout via the corresponding Report button.
The report is downloadable only in CSV file format.
The report contains the following columns:
Payment_Details
Beneficiary_Name
Beneficiary_Reference
Beneficiary_IBAN
Payment_Amount
Currency
Reference_ID
Beneficiary_Address
Beneficiary_City
Beneficiary_Country
Type
Rejected_Transaction_Ref_No
Transaction_Ref_No
Status
Notes
BIC
All the columns in the above report are self-explanatory. However, some columns require elaboration.
When a credit transfer is rejected, it is also added to this report. This aids in linking the rejected credit transfer in an account statement with the payouts product. The rejected credit transfer ID is reflected in the Rejected_Result_Reference column.
In payouts, Result_Status column reflects the following credit transfer statuses (refer to Figure 20):
Processing.
Processed.
Rejected.
© ISX Financial EU PLC 2024. All rights reserved.