This method involves the use of a Bulk Balance Download file. Clients can upload these files to a designated <<glossary:SFTP>> folder. The PayScheduler system is then responsible for:

1. Retrieving and processing these files.
2. Updating the account balances as specified within the files.
3. Issuing a balance update <<glossary:FAST>> administrative message to confirm the successful processing of the balance file.
   1. Issuing a feedback file for any balance update failures.

File format

When providing the balance update batch file for updating the mirrored balance on <<glossary:Banking.Live>> , a <<glossary:CSV>> format is used with data elements similar to those contained within the Update balance <<glossary:API>>. These are:

❗️

IMPORTANT

Please make sure to provide only one of the following in a single balance file:

• account_id

OR

• token

Example with account_id

record_id,account_id,bill_ccy,act_balance,blk_balance,token
2a58261f-a7e0-4bc2-a21e-692309f8fe80,12345,826,5000,2000,
my_card_1234567890_balance,34567,826,6000,1800,

Example with token

record_id,account_id,bill_ccy,act_balance,blk_balance,token
1abcde456-213ghfkk-hjf78g9,,826,5000,2000,54321
this_is_my_balance123456789,,826,6000,1800,76543

File limits

The maximum record limit for batch balance update files is 1,000,000 records per file.

<<glossary:Banking.Live>> will validate the number of records in each batch file recieved prior to processing. If 1,000,000 records per file is exceeded (i.e. 1,000,001) the file will be rejected and you will be notified via a <<glossary:FAST>> administrative message. Therefore, when you are needing to update more than 1,000,000 records you will need to submit more than one file.

📓

You can read more on <<glossary:FAST>> balance update administative messages here.

Naming convention

To ensure accurate processing of balance update files, you must follow the below file naming convention:

[RegionCode]_[ClientID]_[FileType]_[ProcessingDate]_[ProcessingTime]_[SequenceNumber].csv

❗️

If a balance update file shares a name that has previously been used, the entire file will be logged as failed during processing.

Example of balance update files

Batch files for 4-JUN-2024:
EU_12345_BAL_20240604_114511_1.csv
EU_12345_BAL_20240604_114622_2.csv
EU_12345_BAL_20240604_114733_3.csv
EU_12345_BAL_20240604_114844_4.csv

Batch files for 5-JUN-2024:
EU_12345_BAL_20240605_104511_1.csv
EU_12345_BAL_20240605_104622_2.csv
EU_12345_BAL_20240605_104733_3.csv
EU_12345_BAL_20240605_104844_4.csv

❗️

In the event of a corrupted file, a new SequenceNumber must be used when transmitting the new file.

Feedback files

In the instance a balance update file fails, <<glossary:Banking.Live>> generates a detailed feedback file for each balance update record failure. This file includes the reasons for individual record failures for you to take appropriate action prior to submitting a new balance update file.

Feedback files are ONLY generated for balance update record failures. You will not receive a feedback file if the original balance update file was successful.

📓

Feedback file FAST notification

In the event of a feedback file being generated, you will be notified with a <<glossary:FAST>> notification message. You can find details on this here.

File format

You can choose to opt-in to either <<glossary:CSV>> or <<glossary:TXT>> format feedback files.

The data provided in each format type includes:

<<glossary:CSV>> example

record_id,status_code,status_description
4256c01b-2b25-4789-8aa5-18edf943aa40,26,Outdated Balance
9997fb38-0234-468d-94dc-bd0e1b216979,26,Outdated Balance            
375adc45-e152-435c-aa02-822dd4f01ffc,26,Outdated Balance
40798cf2-695e-4841-913f-97f9eac60db0,26,Outdated Balance
83b7ca19-3565-4387-b20e-33b174056837,26,Outdated Balance
16fcae58-d02f-4eed-bfe6-c1044e7913fa,30,Invalid account
ec8581e5-ecd3-4584-91db-8c4feeae18b0,33,Invalid currency code
25c4182e-cdb6-49bc-81ce-45219ceefd65,30,Invalid account
41ba3565-1d27-4e45-8d5e-2e850a1baf8c,30,Invalid account
d9811674-36b0-4203-b28a-57fb2ae82407,30,Invalid account

<<glossary:TXT>> example

Processing Date/Time: 04-JUL-2024 22:00:00 PM
Feedback Date/Time: 
File ID: EU_12345_BAL_20240604_114511_1.csv
File Type: BAL (Balance Update)
Total Records: 10000
Passed Records: 9900
Failed Records: 100

Record ID                                   Status Code   Status Description
4256c01b-2b25-4789-8aa5-18edf943aa40        26            Outdated Balance
9997fb38-0234-468d-94dc-bd0e1b216979        26            Outdated Balance
375adc45-e152-435c-aa02-822dd4f01ffc        26            Outdated Balance
40798cf2-695e-4841-913f-97f9eac60db0        26            Outdated Balance
83b7ca19-3565-4387-b20e-33b174056837        26            Outdated Balance
16fcae58-d02f-4eed-bfe6-c1044e7913fa        30            Invalid account
ec8581e5-ecd3-4584-91db-8c4feeae18b0        33            Invalid currency code
25c4182e-cdb6-49bc-81ce-45219ceefd65        30            Invalid account
41ba3565-1d27-4e45-8d5e-2e850a1baf8c        30            Invalid account
d9811674-36b0-4203-b28a-57fb2ae82407        30            Invalid account

Naming convention

The feedback filename will include the original file name followed by the keyword _FEEDBACK. For example:

• EU_123456_BAL_20240818_134515_2_FEEDBACK.csv

or

• EU_123456_BAL_20240818_134515_2_FEEDBACK.txt

File delivery method

Feedback files are delivered to your configured <<glossary:SFTP>> server location.

Batch file processing notifications

Balance update <<glossary:FAST>> adminstrative messages are sent to you when you upload a balance update batch file.

The balance update <<glossary:FAST>> administrative messages are currently running v1.0 and v2.0.

📓

All new clients will be onboarded to v2.0.

These messages advise you if the balance update file submitted was successful, partially successful or failed and includes the number of passed and failed records.

In the event a balance update file was not successful, a <<glossary:FAST>> balance update feedback file notification is sent to you.

v1.0 (no longer offered)

Below is the basic message structure and JSON schema of v1.0 messages, they are consistent across the message triggers and are in the form of an envelope message.

{
    "MESSAGE_TYPE": {
        "Message_Type": "0600",
        "Message_Desc": "Administrative Message"
    },
    "SUMMARY": {
        "Client_Id": "",
        "Job_Id": "",
        "File_Name": "",
        "File_Date_Time": "",
        "Processing_Time_Secs": "",
        "Total_Records": "",
        "Passed_Records": "",
        "Failed_Records": "",
        "Status": "",
        "Details": ""
    }
}

v2.0

📓

Notable differences

Below are the notable differences between v1.0 and v2.0:

Message structure changes:

• Removal of "Status" field
• Removal of "Details" field
• Addition of a new field "Status_Code"
• Addition of a new field "Status_Description"
• Addition of a new field "Feedback_File_Name"

Message logic changes:

• v2.0 no longer provides the list of accounts/tokens that failed along with the failure reason. Instead a feedback file is generated and sent to you via <<glossary:SFTP>> with the list of failures along with the failure reason. The name of this feedback file is provided in the "Feedback_File_Name" field.

Below is the basic message structure and JSON schema of v2.0 messages, they are consistent across the message triggers and are in the form of an envelope message.

v2.0 basic message structure

v2.0 JSON schema

{
    "MESSAGE_TYPE": {
        "Message_Type": "0600",
        "Message_Desc": "Administrative Message"
    },
    "SUMMARY": {
        "Client_Id": "",
        "Job_Id": "",
        "File_Name": "",
        "File_Date_Time": "",
        "Feedback_File_Name": "",
        "Processing_Time_Secs": "",
        "Total_Records": "",
        "Passed_Records": "",
        "Failed_Records": "",
        "Status_Code": "",
        "Status_Description": ""
    }
}

Status codes and descriptions

📓

You can view sample balance update administrative messages here.

📓

Best practices

For more information on how to best use the balance update batch files for balance listing, you can refer to our Balance listing - Best practices.