RAVEN Files

There is one universal file format used for all batch payment requests and responses between you and the RAVEN processing platform. A RAVEN file consists of a number of lines in a specific order, that are composed of one or more “fields” or values. In general, all Request, Receipt, and Result files must be ASCII or UTF8 text (BOM is mandatory), in comma separated value format (CSV). The first few lines contain some header information. These are followed by any number of payment lines containing the fields defined in the header line. The payment lines are followed by a footer line and in some cases a summary section.

RAVEN batch payments involve the following file formats:

1. Request Files – These are files that originate from you, the client.
2. Receipt Files – RAVEN will produce a Receipt file to confirm every Request file you upload to a directory. Uploading files with a web browser will not result in a Receipt file.
3. Reject Files – If RAVEN cannot process a file because of some significant structural problem, it will produce a Reject file. A Reject file consists of an explanation for the rejection, along with an exact copy of the original Request file.
4. Result Files – Upon completion of processing, RAVEN will produce a result file describing the outcome of each payment request line in the original Request file.
5. Return Files – If our processing bank advises us of returned transactions, RAVEN will generate a Return file containing the payment information of the original Request file and the reason for the return.

The five types of files are explained in greater detail below:

Request files

These are files that originate from you, and are destined for the RAVEN system for processing. They define what transactions are to be executed and on whose behalf.

A simple request file for credit card processing may look like this:

This file consists of the following elements:

• the header

RavenPaymentFile_v2.2.

The header tells RAVEN to expect a payment file matching the file specification version 2.2.

• the Field Names Line

PRN, PymtType, Currency, Expiry, CardNumber, Amount, Reference


Field names are specific to each payment type. The Field Names line is a line of names separated by commas that specify the order for the fields in any following payment request/response lines. The only constraint is that the first field of the Field Names line must always be “PaymentRoutingNumber”. Other fields, such as “Currency” and “Amount”, can be presented in any order.

Following the field names line are one or more Payment Lines:

840033, cc_debit, USD, 1217,4000000000000028, 1200, BWL037A

All of the information presented in each Payment line must correspond with the order presented in the Field Names line. For example in this case the first field (983572) is the PRN and the last element (12000) is the Amount.

Finally, each Request file ends with a footer line. The footer starts with RavenFooter and then indicates the total number of payments and the sum of all the amounts in the file irrespective of whether they are credits or debits. For example:

RavenFooter, 2, 12000

Every valid payment file has these four line types. Optional lines are blank lines and comment lines: A comment line is any line starting with the “#” character. These lines are ignored by RAVEN and discarded when encountered. Comment lines may be placed anywhere in the file, before the Header line and after the Footer line. They may be used for comments, notes, or any other kind of information that you require for your own reference. Blank lines (containing only tabs or spaces, or lines containing only empty fields) are also ignored and may occur anywhere in the file before the Header line and after the Footer.

For example:

#This is a comment
#This is another comment, there is a blank line between the two comments

Use of Commas and Double Quotes

If commas form part of a field, for example, Suite 23, 234 Main Street,  then the field must be surrounded by double quote characters (“) like this: "Suite 23, 234 Main Street". If a value includes a “ character, for example, Alexander "Alex" Smith, then you must precede each double quote character by an additional double quote character and then place double quote characters around the entire field like this: "Alexander ""Alex"" Smith".

Mixed Types

A file may contain different types of payments, such as credit card debits and credits (cc_credit and cc_debit) but should only contain payments of one “family”, as identified by the characters before the first underscore of the payment type, per payment file. E.g. you cannot mix cc payments with deeft payments. Or even deeft payments with nleft payments. However, you may submit payments of various currencies within the same payment file.

File naming

You may use any naming scheme that you wish. We recommend you never use the same file name twice. The best practice is to adopt a naming protocol which is consistent, and which uses sequential or consecutive numbers.  For example, you can incorporate the company name, the date and a sequential number into a file name pattern like this:

AthleticDigest_DDMMYY_1.txt.

It is suggested that you only use numbers, letters, -,_ and . when naming your files.

Creating CSV Files in Windows

You can use a spreadsheet program, such as Microsoft Excel, to create payment files if you choose. If you are using a spreadsheet program to create payment files, it is very important that you format all cells as TEXT.  Otherwise, Excel may automatically add decimal places to the amount column, or drop zeros from other columns while you type or when it comes time to save the file in CSV format.
Once you are satisfied with the contents of a file, save it in “comma separated values” (CSV) format.  You can do this by clicking on File, “Save As…” and then selecting “CSV (Comma delimited)” as the “Save As” file type. Excel has many automatic formulas, and using Excel to open a finished CSV file can alter the data, making it unreadable by the RAVEN system. This problem can be avoided by viewing completed CSV files in Notepad or WordPad only.

Receipt files

RAVEN returns a Receipt file to you after a Request file submitted by you has been successfully received and validated. This file is both a confirmation that processing has been initiated on your Request file and an indication on a per line basis of any payment lines that failed validation.

The Receipt file corresponding to the Request file example above would look like this:

RavenPaymentFile_v2.2, Receipt, memberships_23112005_1.txt
PRN, PymtType, Currency, Expiry, CardNumber, Amount, Reference, Status
840033, cc_debit, USD, 1217,400000***0028, 1200, BWL037A, InProgress
840033, cc_debit, CAD, 1116,400000***0010, 1000,"escaped, reference", Invalid:Expiry
RavenFooter, 2, 2200

Receipt files echo the corresponding Request file with five differences:

1. The result file will omit comment lines, blank lines and any extraneous white space between fields.
2. The header line contains two additional fields; the first is the file type and the second is the name of the request file resulting in the header: RavenPaymentFile_v2.2, Receipt, memberships_23112005_1.txt.
3. Account numbers in the payment lines will be masked.
4. Each payment line will contain the status of the payment. This will be either InProgress which means the payment has been accepted for processing or a status indicating a problem with the payment. The possible statuses are listed in the sections documenting the various payment types.
5. RAVEN Receipt files have a name that is simply the original Request name with ” RECEIPT.txt” appended to it. For example:
   
memberships_23112005.txt RECEIPT.txt

Reject files

If a Request file was successfully received but did not pass validation, RAVEN will send you a Reject file. This file indicates that the original Request file was not processed and documents what was wrong with the file. The Reject file is not intended to be readable by software. At the top of the file is English text describing the problem with the Request file, which is followed by a few lines of the original Request file.

For example:

FILE REJECTED
This payment file could not be processed because:>
The file contains a footer that indicates the wrong payment total.
======================================================================
RavenPaymentFile_v2.2
PRN, PymtType, Currency, Expiry, CardNumber, Amount, Reference
840033, cc_debit, USD, 1217,4000000000000028, 1200, BWL037A
840033, cc_debit, CAD, 1106,4000000000000010, 1000,"escaped, reference"
RavenFooter, 2, 1200

RAVEN Reject files have a name that is simply the original Request name with “REJECTED.txt” appended to it. For example:

memberships_23112005.txt REJECTED.txt

Result files

RAVEN returns one or more Result files to you after a Request file submitted by you has been preprocessed and submitted to the bank for final processing. The Result file describes the outcome of each of the individual payment requests that were made. The number of Result files you receive is dependent on the type of payment requests that were in the original Request file. For example, credit card result files include the outcome of the approval stage, but EFT result files typically only include the results of the RAVEN validation stage.

The Result file corresponding to the Request example above would look like this:

RavenPaymentFile_v2.2, Result, memberships_23112005_1.txt
PRN, PymtType, Currency, Expiry, CardNumber, Amount, Reference, Status, TrackingNumber, ApprovalCode
840033, cc_debit, USD, 1217,400000***0028, 1200, BWL037A, InProgress
840033, cc_debit, CAD, 1116,400000***0010, 1000,"escaped, reference", Invalid:Expiry
983572, cc_debit, USD, 1207, 458372***4532, 12000, BWL037A, Approved, 50000023, 00AUTH1
983572, cc_debit, CAD, 1106, 458372***4532, 10000,”spec, case”, Invalid:Expiry, 50000027,
RavenFooter, 2, 12000
RavenSummary
983572, USD, Approved, 1, 12000
983572, CAD, Invalid, 1, 10000

Like Receipt files, Result files echo the corresponding Request file with some minor differences:

• The result file will omit comment lines, blank lines and any extraneous white space between fields.
• The header line contains two additional fields; the first is the file type and the second is the name of the request file resulting in the header RavenPaymentFile_v2.2, Result, memberships_23112005_1.txt.
• The Field Names Line contains the additional fields of Status, TrackingNumber and any type specific result files. For example, card payments may include an ApprovalCode as a result field.
• Account numbers in the payment lines will be masked.
• Each payment line contains the status of the payment after processing, a TrackingNumber which identifies the payment in RAVEN and any type specific results. The possible statuses and type specific result fields are listed in the sections documenting the various payment types.
• Following the footer line there is a summary as described below.

Result Summary

The Summary only exists in Result files. It follows the footer line and provides information on the results of processing the payment file. The summary section is not intended to be read by a computer program; it is a human readable breakdown of the Result file by routing number, currency, and status. The layout of the summary may change over time. If you are developing software to process RavenResult files it is recommended that you stop processing after you have read the Footer line.

The summary section consists of the header RavenSummary followed by one Summary Detail line for each routing number/currency combination found in the original Request file. These lines start with a routing number and an ISO currency code and are followed by one or more status summaries listing a status name, payment count, and absolute (not net) payment value for that currency. For example:

RavenSummary
983572, USD, Approved, 1, 12000
983572, CAD, Invalid, 1, 10000

Raven Result files have a name that is simply the original Request name with ” RESULT.txt” appended to it.  For example:

memberships_23112005.txt RESULTS.txt

Return Files

From time to time payments submitted to the bank will be returned. The reasons vary depending on the payment type but the most common are: no funds available, incorrect account information and customer charge back (e.g. revoking authorization). Returned items will be reported to you in a Return file as they are received by RAVEN.

An example of a Return file is:

RavenPaymentFile_v2.2,returns
PaymentRoutingNumber,PaymentType,CurrencyCode,Amount,Reference,Comment,PayeeName,AccountIdentifier, Status,TrackingNumber,SubmissionDate,SubmissionFile
983572,cc_debit,USD,12000,BWL037A,,WineClub,458372***4532,
Returned:Not Authorized, 50000023,2006-01-19, memberships_23112005_1.txt
RavenFooter,1,12000

Return files are RAVEN files with the header

RavenPaymentFile_v2.2, returns

and the fixed Field Names Line:

PaymentRoutingNumber,PaymentType,CurrencyCode,Amount,Reference,Comment,PayeeName,AccountIdentifier, Status,TrackingNumber,SubmissionDate,SubmissionFile

Note the non-standard naming of some of these fields. These fields are defined as:

Field description	Format	Max. Size	Remarks
Payment Routing Number	Numeric	6	The six-digit payment routing number assigned to you.
Currency Code	Alpha	3	The three character ISO currency code of the payments in a summary line
Status	One of	50	See the section describing the specific payment type you submitted.
Payment Count	Numeric	12	Number of all payments in the status listed immediately prior.
Subtotal	Numeric	12	Total of all payment amounts in the status listed immediately prior.

The simplest way to deal with a Return file is to look up the original payment in your system using the tracking number and then handle it appropriately based on the return reason encoded in the Status.

RAVEN Return files have a name that is constructed of the following parts:

• Your account name that the original payment was processed under, e.g.: “EUROPE_1“
• The currency of your account
• A payment category identifying the kind of payments, e.g. “CC” for credit cards
• The date the return file was created in YYYY-MM-DD format, e.g. “2006-06-07”
• “RETURNS.txt“

Putting this all together results in: EUROPE_1 USD CC 2006-06-07 RETURNS.txt