Check Issue Payments

Check issue requests are used to instruct the RAVEN system to begin validation, printing and shipping of paper checks. Printed checks can be shipped in bulk or mailed out individually, depending on the arrangement that has been made. This page describes the fields that are used to submit check issue requests; it will also help you to understand the responses from RAVEN. Instructions are included to assist you in creating a check issue request file for submission.

A correctly formatted check issue request file looks like this:
RavenPaymentFile_v2.2 PRN,PymtType,Currency,Amount,Beneficiary,AddressLine1,City,ProvState,Country,PostalCode 830044, chq_issue_credit, GBP, 1000, John Smith, 12 Hawksley Crescent, London, , GB, EC1Y 8SY 830044, chq_issue_credit, EUR, 1114, Bruno Heider, 45 Speisse Gasse, Berlin, ,DE, 1232 RavenFooter, 2, 2114

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 of version 2.2.

2. The Field Names Line

PRN, PymtType, Currency, Amount, Beneficiary, AddressLine1, City, ProvState, Country, PostalCode

To fully understand each field indicated in the sample, please refer to the table that explains these fields, which is located near the end of this page.

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

830044, chq_issue_credit, GBP, 1000, John Smith, 12 Hawksley Crescent, London, , GB, EC1Y 8SY

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 (830044) is the PRN and the last element (1232) is the Postal Code. Please note that in both payment lines there is a ‘blank’ space separated by commas:

830044, chq_issue_credit, EUR, 1114, Bruno Heider, 45 Speisse Gasse, Berlin, ,DE, 1232

This occurs because there is no ‘ProvState’ information to include with the check issued for London or Berlin. However, as the field name was included at the outset, there must exist a blank space to indicate that there is to be no information included in this field for this specific payment.

4. Finally, each Request file ends with a footer line. The footer starts with ‘RavenFooter’, followed by the total number of payments in the file, and ends with the sum of all the amounts in the file, irrespective of whether they are credits or debits.

RavenFooter, 2, 2114

Create a Check Issue Request

To create your first check issue request and issue your first batch of checks, you may use the sample as a guide. Check issue request files must be submitted in CSV format; CSV simply stands for ‘comma separated values’. However, the file need not have the .csv extension to be correctly formatted.

Follow these instructions to create a CSV file using this sample:

RavenPaymentFile_v2.2 PRN,PymtType,Currency,Amount,Beneficiary,AddressLine1,City,ProvState,Country,PostalCode 830044, chq_issue_credit, GBP, 1000, John Smith, 12 Hawksley Crescent, London, , GB, EC1Y 8SY 830044, chq_issue_credit, EUR, 1114, Bruno Heider, 45 Speisse Gasse, Berlin, , DE, 1232 RavenFooter, 2, 2114

You may choose to submit either a Notepad, Textpad or Excel file.

To create a file in Notepad or Textpad, copy the text in the sample and paste it into your file. Now, simply edit your file by replacing the data in the sample with the actual PRN you have been given and the specific details of the checks you need to issue. If you are confused about what to enter in any field, you may refer back to the table below, or contact your customer service representative.

To create a file in Excel, you must first copy the sample into a Notepad or Textpad file.

Save the file on your desktop or other location of your choice.

Next, you will need to open the Excel program and import the data from the text document into an Excel sheet.

In the open Excel sheet, click the ‘Data’ tab and select ‘From Text’. Choose your newly created text file and click the ‘Import’ button. At this point, the Text Import Wizard will appear on your Excel sheet: on the first screen, choose ‘Delimited’ and press ‘Next’, on the second screen, choose ‘Comma’ and deselect ‘Tab’, then click ‘Next’ to proceed. Leave the last screen as is and choose ‘Finish’ to complete the import. You will be prompted to indicate where you would like to put the data, choose ‘Existing worksheet’ and click ‘OK’.

The data from the text file should now exist on the excel sheet, with each field’s information separated by cells.

Now, simply edit your file by replacing the data in the sample with the actual PRN you have been given and the specific details of the checks you need to issue. If you are confused about what to enter in any field, you may refer back to the table below, or contact your customer service representative.

A file may contain a mix of countries and currencies. Make sure you provide the total number of payments and the total numeric amount in the footer line.

Once you have created the file in CSV format, log on to RAVEN Online and upload the file. Your checks will be issued and mailed according to your specifications. You can use RAVEN Online to track the status of your check issue request, view account information and get reports. You can even use the built-in web terminal to conveniently issue individual checks without the bother of uploading a file.

Request and Response Fields

The fields supported for Check Issue payments are described in the following table. The column ‘Req/Rsp’ indicates if the field forms part of the request to RAVEN (Req) or part of the response from RAVEN (Rsp). Except as noted, RAVEN will echo all request fields in the response. The column O/C/M indicates if a field is optional, conditional or mandatory.

Field Names	Type	Max. Size	Req/Rsp	O/C/M	Remarks
PRN	N	6	Req	M	The 6-digit payment routing number assigned to you.
PaymentType	T	25	Req	M	The type of payment to be issued. For outbound check payments, the PaymentType will always be: chq_issue_credit.
Amount	N	10	Req	M	Amount, in the currency of check. Value supplied in base unit of currency, with no decimal. E.g. $150.00 is 15000. If the optional AccountAmount field is supplied, then the Amount field must be zero. In this case, the Amount will be returned in the result file.
Beneficiary	UC	40	Req	M	The beneficiary’s name, exactly as it should appear on the check.
Currency	A	3	Req	M	The three-character ISO currency code (e.g. EUR, GBP) the check will be valued in.
Country	A	2	Req	M	The two-character ISO country code (e.g. DE, GB) used to determine the country of the account on which the check will be drawn.
AccountAmount	N	10	Req	O	Amount in the currency of the account associated with the payment routing number. The value of the check will be determined when the check is printed, based on the exchange rate in effect at that time. If this value is present and is NOT zero, then the amount field must be zero. Value is supplied in base unit of currency, with no decimal. E.g. $150.00 is 15000
Description	UC	60	Req	O	If present, this text may be displayed on the check. It will not affect processing. Use the shortest possible value.
Reference	UC	30	Req	O	Information the merchant may supply at their discretion identifying the payment or beneficiary. Will be echoed on reports. Will not be printed on the check. May be used to support the mail merge service. In the case of batch files this field is recommended but optional, in all other cases (i.e. RAPI, Virtual Terminal) this field is mandatory and must be unique in the file.
Reference2-10	UC	100	Req	O	9 additional reference fields, containing information the merchant may supply at their discretion identifying the payment or customer. Will be not echoed on reports. Will not be printed on check. May be used to support the mail merge service.
Table1-3	UC	-	Req	O	Three additional fields to provide tabular data in Wiki format for advanced letter mail merge.
Address Information		See Note on Addresses, below.
AddressLine1-4	UC	60 each	Req	O	Address lines of the beneficiary. Up to four may be supplied. If present, these will be printed on the mail merge letter in a location suitable for insertion into a window envelope. NOTE: At least one address line is mandatory for fulfillment.
City	UC	50	Req	O	City the check will be mailed to. NOTE: This field is mandatory for fulfillment.
ProvState	UC	50	Req	O	The Province, Department, Canton or State the check will be mailed to. NOTE: Where applicable, this field is mandatory for fulfillment.
PostalCode	UC	10	Req	O	The postal or zip code the check will be mailed to. NOTE: Where applicable, this field is mandatory for fulfillment.
CustomerCountry	A	2	Req	M	The two-character ISO country code (e.g. DE, GB) used to verify the country the check will be mailed to. NOTE: This field is mandatory for all checks issued.
ReturnAddressLine1-5	UC	60 each	Req	O	Your return address lines. Up to five may be supplied. If present, the return address is available to be printed on the mail merge letter. If there are return address fields available on the check, the return address will also be printed on the check. If not present, the return address defaults to the mailing address held on file for your company. NOTE: If the ReturnAddressLine1 is null, RAVEN assumes the rest of the return address lines are null and defaults to the mailing address held on file for your company. NOTE: Return addresses are subject to the rules of the post service of the country where the cheques are mailed from. Check with you customer service contact before making use of these fields.
ShipmentMethod	A	25	Req	O	If present, the check will be fulfilled using the method specified. The default fulfillment method is post. The possible choices are: courier post
Comment	UC	1000	Req	O	Information the merchant may supply at their discretion. Will be echoed on reports. Will not be printed on checks. Can be used as a merge field for mail merge letter template.
TemplateNumber	N	9	Req	O	The TemplateNumber must be the tracking number of a successful card payment. If provided, the Fields marked with an † (the account data) will be pulled from the template payment and must not be supplied. Template payments must have the same payment routing number as the one they are being applied to. It is an error to supply values that will be pulled from the template. For example, if Template Number is supplied it is an error to supply a account number.
Status	T	50	Rsp	M	One of the following status codes. InProgress – check issue request was received and will be processed. Shipped – check has been shipped to beneficiary. Voided – the check issue request has been voided and will not be processed. Invalid:<field> – a field in the request is invalid. Rejected:<reason> – the payment, while valid, has been rejected for another reason. ConfigError:<error> – due to a RAVEN configuration error, the payment could not be processed. Invalid:TestChannel – payment was submitted to a test channel and the test was successful. If the channel was live the payment would be InProgress.
TrackingNumber	N	9	Rsp	M	RAVEN will return a unique tracking number for each payment processed.
ChequeNumber	N	13	Rsp	C	If successfully printed, this will be the serial number of the check.
EffectiveDate	N	8	Rsp	C	If successfully printed, this will be the date printed on the check in DDMMYYYY format.
ShipmentTrackingNumber	AN	100	Rsp	C	If a check has been requested with a ShipmentMethod of courier, this field will contain the courier company’s tracking number; otherwise, it will be empty.
FormattedAmount	N	15	Rsp	M	Decimal formatted amount of item.
TicketExchangeRate	N	10	Rsp	M	Exchange rate for the account the funds will be drawn on.
FormattedTicketAmount	N	15	Rsp	M	Amount to be withdrawn.
TicketCurrency	A	3	Rsp	M	ISO currency code of account from which funds will be drawn.

Notes on Addresses

The correct CustomerCountry field is required for all checks issued, even if they will be shipped in bulk to your business address. The CustomerCounty is the country in which the check will ultimately be received by the beneficiary.

When providing address information for checks to be mailed or sent via courier, it is mandatory to supply one or two street address lines as well as the city, political division (state, province or county if applicable), postal code (if applicable) and the beneficiary’s country code. If differentiated address information is not available, it is possible to simply provide four lines of address information, though this may compromise delivery rates.

All addresses, whether supplied in block or using differentiated fields, require the CustomerCountry field to be completed.

Mail Merge

An optional service is available that will result in a customized letter to be printed and packaged with each check that is issued on your behalf. The letter can be on a separate page or as the top portion of a “letter check”. If you take advantage of this service you will be required to supply a Microsoft Word “mail merge template” prior to the checks being printed.

The merge fields available to you are exactly the same as values supplied in the Request and Response Fields (described above) with the following changes:

Merge Fields	Type	Max. Size	Remarks
PromotionName	AN	100	This additional field is the name of the originating company or ‘dba’ associated with the PaymentRoutingNumber in the check issue request.
CountryName	A	100	Name of the beneficiary’s country.
BeneficiaryAndAddress	A	100	Beneficiary’s name and address, across several lines

Mail Merge Table Formatting

Mail merge supports the inclusion of tables of any dimension and per-cell emphasis and alignment. If you wish to include a table in your form letter, you will need to supply the data in the optional fields Table1-3 following these rules:

Each table must start with {WIKIDATA-1.0}
Each cell must start with one of the following,
- || (center-aligned cell)
- |{ (left-aligned cell)
- |} (right-aligned cell)
Each row must end with ^
Each cell may have one or more of the following emphasis options at the very beginning,
- * (bold)
- / (italic)
- _ (underline)
- ~ (hide cell borders)
Newline characters must not be included (for example, CR, LF or CR+LF)

Below are some examples showing the data supplied and the resulting table.

Table Example 1

${WIKIDATA-1.0}||Description||Cost^||White Gloves||$20.00^||Black Gloves||$15.00$

{WIKIDATA-1.0}||Description||Cost^||White Gloves||$20.00^||Black Gloves||$15.00

Table Example 2

${WIKIDATA-1.0}||*Description||*Cost^|{White Gloves|}$20.00^|{Black Gloves|}$15.00$

{WIKIDATA-1.0}||*Description||*Cost^|{White Gloves|}$20.00^|{Black Gloves|}$15.00

Table Example 3

${WIKIDATA-1.0}||*Description||*Cost^|{White Gloves|}$20.00^|{Black Gloves|}$15.00^|}~*/Grand Total|}*$35.00$

{WIKIDATA-1.0}||*Description||*Cost^|{White Gloves|}$20.00^|{Black Gloves|}$15.00^|}~*/Grand Total|}*$35.00