A Guide to Input File Structure used in Royal Bank of Canada’s ACH Direct Payments
AUGUST 11, 2017
ACH Direct Payments is one of the five methods available to the Royal Bank of Canada (RBC) commercial account holders accepting regular payments from their clients. It eases receivables management for businesses but for developers, working with ACH Direct Payments is a challenge.
Imagine no pre-built SDKs, no sandbox environment, and no API interface. You are supposed to work under these constraints and be perfect because money is involved. The challenge is huge but not insurmountable.
We wrote 3 Techniques to Simplify Working with Royal Bank of Canada’s ACH Direct Payments for developers who are working with this payment system for the first time. This blog is a continuation of that series. Today we will share with you the Input File Structure.
What is an Input File? And Why Should You Care?
The RBC’s servers accept data as Flat, EDI, or XML files. These files are also known as input files because they contain the information that identifies a customer, such as her name, address, transaction amount, etc.
The Input Files follow a strict format which has been detailed on the RBC’s official website. Any deviation from the recommended standard may lead to bugs, or worse. Avoid such a scenario with our overview.
Input Files are Divided into Sections or Records
An input data file is divided into separate sections some of which store the file’s purpose and identify its type. Each file contains a record in each line. In a line character position is used to identify the starting and ending of different kinds of data. For example, the first 16 characters can carry a person’s first name, the second set of 16 characters can store an account holder’s last name, and the third set of 16 characters can represent a client’s account balance.
Four Essential Records
Each payment file has at least four kinds of records:
1. Routing Record
2. Header Record
3. Basic Payment Record
4. Trailer Record
Let’s view them one at a time.
The very first record in an input file, used by the RBC to decide if the information is a credit or a debit file. Each line in this record stores:
1. File type: credit or debit
2. File format
3. File’s purpose: test or real-life
4. File’s length, which can be 152 or 80 characters
The characters are put together in a fixed format which looks like:
• Green tells whether a record is a debit or a credit file. AAPA will mean you want to collect money from customers and AAPD refers to the transfer money from you to your customers.
• Orange tells the format of the file to be followed and the length of each record. Here, it tells that the input data file is in standard format and the length of the record should be 152 characters per line.
• Blue text marks the record as a test file, so it will not be processed in production environment.
• Red “NL” specifies that the records will span the full length of the standard i.e. 152, other possible value for NL is the 80. In that case, records length could be 80 characters.
Header record explains the details of basic payment records, such as: How many payment records are included? And what is file creation number and file creation date?
A file creation number is the unique number assigned to each input data file that you create. This number can be used to identify the data from the reports produced by the RBC.
ACH Direct Payments is a batch processing system. The RBC does not respond immediately. So do not upload multiple input data files if you don’t notice an immediate response. Responses will appear after an interval of 4–5 hours.
The file creation number and file creation date are a good candidate to identify the response and associate it with your input data file for further automating the payment process.
The header record also contains the client’s number and name. Once you sign up for an RBC account capable of processing ACH payments, you are assigned two client numbers both having a different functionality. The first is used in your debit file and the second in your credit file.
• For everything to work as planned, it is important to ensure a valid combination of Routing Record and client numbers is used in the Header Record.
• Apart from all this, it’s crucial to stick to the format touched upon Routing Record.
• Header Record follows Routing Record in the data file.
Routing and header records would look like the one below inside your flat input data file before encryption.
Basic Payment Record
Basic payment record is the actual payment transaction record. These are the individual’s monetary transactions that can be processed through RBC if the developer has access to data, such as a customer’s banking information, record number, customer number, amount to be deducted, and currency information.
To uniquely identify a payment and to backtrack (confirm) it from our own database we used the file creation number, customer number, and payment number field to create a unique number.
Then the fields can be used in the output data file (reports) from RBC to track the success and failure of the payments. You need to make sure that you have correctly placed the data in their required columns in your flat file as per the format guides. Otherwise, you are going to get errors back in the report. If you get error back from RBC you can check the proper reason on this link https://www.rbcroyalbank.com/ach/cid-212259.html
Some columns would have less data than the actual character length allows. In such a case, you would have to pad those places with blank value. You will get the padding and filler instructions inside the guides. Your basic payment record would look like the one below:
Trailer record is the last record in the file. This record tells that how many payment records there are in the file and what the total payment amount is. The trailer record will look something like this.
Your completed non-encrypted file would look like the one below:
After the input data file has been created, encrypt it using public-key encryption and then upload it to the SFTP location for the RBC to process. When you upload the input data file to RBC it will automatically detect the new file and process it. Usually it takes few hours to schedule the processing of the file and provide you results back.
Below is the sample code to upload the input data file to RBC SFTP. This code is in PHP and is using cURL extension of PHP.
We hope that this post will get you started on the way to developing a solid understanding of Input Data files. For questions and suggestions, feel free to comment or write to us at firstname.lastname@example.org