Batch Processing Specifications 

Version 2.1

July 15, 2025

PDF download

Table of Contents

Section Revision History 

July 15, 2025

AIR Travel Batch update - add Flight Number

April 21, 2021

Token Maintenance Batch fixes

March 8, 2018

Updated Level 2/Level 3 batch format

February 20, 2015

Token Maintenance Batch format updated to support Auto-Generated Token IDs

Batch-based processing can be easily implemented for applications and processes where real-time transaction responses are not essential or practical. Batches of transactions can be accumulated and submitted for processing based on a schedule established by the merchant.

Batch file formats supported by Payroc provide the ability to:

Obtain authorization prior to filling customer orders
Submit customer billing for goods and services when orders are filled or shipped
Provide business and corporate customers with Level 2, Level 3, and Air Travel Data details
Create and maintain tokens to be used in place of credit card information for security and PCI requirements (tokenization)

Batch-based processing can be handled very efficiently by automating the submission of batch files and retrieval of reports.

Data Definition Tables 

Data definition tables used in sections of this document explain the type of data used in file records and data fields. The general format of these tables is as follows:

#	Field Name	Length	Type	Req	Description
1	The Field Name	17	A/N	Y	This is typically where field or record descriptions appear.
2	Another Field Name	6	N	N	This is typically where field or record descriptions appear.

Some data definition table conventions regularly used in this document:

“#”, when used in the header of a table, refers to the field number. If field order is important, there will be a “#” column present.

“Length” is the length of the field in bytes, and represents a maximum length unless otherwise specified.

In the Type column, “A/N” refers to “AlphaNumeric”. Unless otherwise stated, these fields can contain the letters A-Z in uppercase, the digits 0-9, spaces, and the ASCII hyphen character “-“.

In the Type column, “N” refers to “Numeric”. Unless otherwise stated, these fields can contain only the digits 0-9.

In the Type column, “A” refers to “Alphabetic”. Unless otherwise stated, these fields can contain only letters A-Z, upper case.

“Req” in a table header means “Required”, and is used to improve spacing and readability in tables. A value of “Y” in this column means that the data is required, “N” means that you may omit the data, and “C” means that the data is conditional.

Tables may span multiple pages, and some table rows may span pages due to the amount of information present.

Table notes and exceptions are found after data definition tables.

File Delivery Method 

Payroc supports batch processing with file uploads and report retrievals via SFTP.

In order to have an SFTP account set up, you will need to provide Payroc with the IP address for connection and key to be used for authentication. Payroc will set up your account and provide you with a server name and user ID that are to be used to deliver files and retrieve reports.

Once you log in to Payroc’s SFTP server you will find two sub-directories: “in” and “out”. The “in” directory is used for uploading or dropping off batch files for processing. The “out” directory is used for downloading or retrieving report files.

Batch File Types 

Batch File Type	Description
Level 1 Batch	This batch file type is used to process financial transactions without commercial card extended data. Normally when a card is charged, the cardholder’s statement contains only a basic set of information referred to as “Level 1”. The statement provides the cardholder with the name of the merchant, the location or phone number, and the amount charged. This batch file type also supports the processing of recurring payment transactions.
Level 2/3 Batch	For business-to-business commercial card transactions, commercial card holders are requesting additional data with their financial transactions to aid with their reconciliations and tax reporting. Level 2 data fields provide additional information about the overall transaction such as tax, shipping, and duty amounts which would typically show as separate totals on an invoice. Level 3 data fields provide information about each invoice line item within the order including product description, quantity, and tax status.
Air Travel Data	Air Travel Data Reporting allows cardholders to receive tax and itinerary details for travel industry purchases. Level 2 (Tax Details) can be submitted with Air Travel Data to provide a breakdown of sales tax data including GST, PST, HST, and QST where applicable. Air Travel Data (travel itinerary details) provides information such as departure date, passenger name, origin, destination, stopovers, and carrier name.
Token Maintenance	Tokenization allows a merchant to set up a unique ID or token for each of their customer’s credit cards. Once the token has been set up on Payroc’s system, the merchant can replace the credit card information with the token when processing a transaction. The main benefit of tokenization is that the merchant no longer has to store credit card data on their systems. Payroc stores the credit card data in a secure encrypted database and retrieves the information for the merchant as required in order to process a transaction. Merchants can add new tokens, update existing tokens, and activate or de-activate tokens using this type of batch file.

File Specifications 

A comma separated values (CSV) file is used for all batch file types.

Each field must be present, even if empty. Fields within the CSV files can optionally be wrapped in double quotes (“). Padding of fields with zeros or spaces is not required.

Characters allowed for alphanumeric (A/N) fields are uppercase letters (A through Z), numbers (0 through 9), dash (-) and spaces unless otherwise specified in the field description.

File Extensions 

The type of batch file being delivered is identified by its filename extension. Filename extensions to be used for each batch type are as follows:

Batch Type	Extension
Level 1	.l1
Recurring Payments	.recurring
Level 2/Level 3	.l23
Air Travel Data	.air
Token Maintenance	.token
Recurring Payments	.recurring

Option is available to submit PGP encrypted files for processing. If the batch files are PGP encrypted then “.PGP” is to be added to the filename after the Batch Type extension.

Level 1 Batch Files 

Record Sequence 

Level 1 batch files include one record (line) for each transaction.

Level 1 Record 

#	Field Name	Length	Type	Req	Description
1	Terminal ID	8	A/N	Y	8 character ID assigned by Payroc. The terminal ID may be associated with a set of merchant accounts, location, or specific application. Allowed characters: 0-9 A-Z
2	Operator ID	3	A/N	Y	Fixed value of “001” unless otherwise arranged with Payroc. Operator ID can optionally be used to group transactions for balancing and reconciliation purposes. If multiple Operator IDs are required please co-ordinate with Payroc prior to implementation. Allowed characters: 0-9 A-Z
3	Transaction Type	1	A	Y	“S”: Sale “V”: Void “F”: Force Post “R”: Return “M”: Return Void “A”: Authorization Only “P”: Pre-Authorization “C”: Completion “W”: Authorization Reversal See the Transaction Types section for additional details.
4	Credit Card Number OR Token	36	A/N	Y	This field can contain: Full card number with a maximum length of 19 digits. Value of “0” can be used in place of card number for Completion, Void, and Return Void transactions Token with a prefix of “TOKEN:”, i.e.: A value of “TOKEN:123456” would specify that card information associated with token 123456 is to be used for transaction processing. Token can be a maximum of 30 characters. Allowed characters: 0-9 A-Z : @ \| - + / _
5	Expiry Date	4	N	Y	The expiry date of the credit card in the format MMYY. A value of “0” can be used for Completion, Void, Return Void, and token-based transactions
6	Amount	10	N	Y	The transaction amount with no currency sign or decimal point. Example: Value of “100” represents $1.00.
7	Reference Number	60	A/N	Y	Unique transaction reference number. Allowed characters: A-Z 0-9 - /
8	Authorization Number	6	A/N	N	Authorization number provided by the authorizing institution if the transaction has already been approved. Required for Force Post transactions. Allowed characters: 0-9 A-Z
9	Merchant Description	25	A/N	N	Custom description to be passed to the card issuer for display on the cardholder’s statement. Allowed characters: A-Z 0-9 - / and space

Level 1 Report File 

The Level 1 report file is a comma separated values (CSV) file. The first line is the file header and contains the following text for ease of field identification:

TERMID,REF_NUM,CC_NUM,EXP_DATE,RESPONSE,APPRV

The remaining lines in the file are transaction response records. This table details the fields and their meanings:

#	Field Name	Length	Type	Description
1	Terminal ID	8	A/N	Echoed back from the original transaction.
2	Reference Number	60	A/N	Echoed back from the original transaction.
3	Credit Card Number or Token	30	A/N	Contains either a masked version of the credit card number or the token, depending on the information included in the original transaction.
4	Expiry Date	4	N	Echoed back from the original transaction.
5	Response	30	A/N	Contains either the decline message, or authorization number and amount. May also contain a UID for commercial card transactions. The UID is used by Payroc to match Level 3 data to the Level 2 financial transaction. If you are only using Level 1 transactions (non-commercial-card) then you can ignore the UID field.
6	Approval Code	1	N	“1”: Approved “0” (zero): Decline or failure

Example 

Example of Level 1 Batch File:

TESTTEST,001,S,5191111111111111,0506,100,TESTNUMBER1
TESTTEST,001,F,TOKEN:TOKEN1,0,5000,TESTNUMBER2,654253
TESTTEST,001,V,5191111111111111,0506,100,TESTNUMBER1
TESTTEST,001,R,TOKEN:TOKEN2,0506,10000,TESTNUMBER3
TESTTEST,001,M,TOKEN:TOKEN2,0506,10000,TESTNUMBER3
TESTTEST,001,A,5550000000000003,0506,23559,TESTNUMBER4
TESTTEST,001,P,TOKEN:TOKEN4,0506,23559,TESTNUMBER5
TESTTEST,001,C,0,0,23559,TESTNUMBER5
TESTTEST,001,S,5191111111111111,0506,200,TESTNUMBER12,,CUSTOMDBA
TESTTEST,001,F,TOKEN:TOKEN123456,0,6000,TESTNUMBER22,654253,ABC COMPANY

Example of Level 1 Report File:

TERMID,REF_NUM,CC_NUM,EXP_DATE,RESPONSE,APPRV
TESTTEST,TESTNUMBER1,************1111,0506,T30490 $1.00,1
TESTTEST,TESTNUMBER2,TOKEN1,0 ,654253 $50.00,1
TESTTEST,TESTNUMBER1,************1111,0506,VOID OK,1
TESTTEST,TESTNUMBER3,TOKEN2,0506,RETURN $100.00,1
TESTTEST,TESTNUMBER3,TOKEN2,0506,MRVOID OK ,1
TESTTEST,TESTNUMBER4,************0003,0506,T30498 $235.59,1
TESTTEST,TESTNUMBER5,TOKEN4,0506,T30500 $235.59,1
TESTTEST,TESTNUMBER5,,0 ,T35817 $235.59 12082GP,1
TESTTEST,TESTNUMBER12,************1111,0506,T30504 $2.00,1
TESTTEST,TESTNUMBER22,TOKEN123456,0 ,654253 $60.00,1

Level 2/3 Batch Files 

Record Sequence 

Level 2/Level 3 batch files can include multiple batches of transactions. Each batch in the file must include a Batch Header record followed by an Invoice Header record and one or more Invoice Line Item records.

If you have been assigned more than one terminal ID, your batch file must contain a Batch Header record, followed by Invoice Header records and Invoice Line Item records for EACH terminal ID that is to be included in this batch.

Record Name	Notes
Batch Header Record	Each batch must include a Batch Header. There may be more than one batch within the batch file.
Invoice Header Records (Level 2)	Each transaction will include one Invoice Header Record (Level 2). There may be multiple transactions included in the batch. Each Invoice will include an Invoice Header and one or more Invoice Line Item records.
Invoice Line Item Records (Level 3)	For each Invoice Header Record (Level 2) there may be zero or more Invoice Line Item Records (Level 3).

Example of record sequence for Level 2/Level 3 Batch:

⇓ Batch Header Record (for terminal ID #1)

⇓ Invoice Header Record

⇓ Invoice Line Item Record

⇓ Invoice Line Item Record

⇓ Invoice Header Record (with no subsequent Level 3 details)

⇓ Invoice Header Record

⇓ Invoice Line Item Record

⇓ Invoice Header Record

⇓ Invoice Line Item Record

⇓ Invoice Line Item Record

⇓ Invoice Line Item Record

⇓ Batch Header Record (for terminal ID #2)

⇓ Invoice Header Record

⇓ Invoice Line Item Record

⇓ Invoice Header Record

⇓ Invoice Line Item Record

⇓ Invoice Line Item Record

Batch Header Record 

#	Field Name	Description	Length	Type	Notes
1	Batch Date	Batch Date in the format YYYYMMDD	8	N
2	Batch Number	Batch number for a given date	2	N	i.e., first batch of day = 01, second batch of day = 02
3	Header Count	Count of the number of Invoice Header (Level 2) records in the batch	1-8	N
4	Line Item Count	Count of the number of Invoice Line Item (Level 3) records within the batch	1-8	N
5	Not Used	Previously used for Tax Flag
6	Batch Value	The sum of the absolute value of all Gross Amount fields included in the Invoice Header records	1-10	N	Two implied decimal places, no currency sign of decimal point to be included (e.g. “100” is $100)
7	Terminal ID	The 8 character terminal id to be used for this batch	8	A/N
8	Version	Value of “08.01” indicating the version of Level 2/3 batch file format	5	A/N

Level 2 (Invoice Header) Record 

#	Field Name	Description	Length	Type	Notes
1	Invoice Number	External system transaction ID assigned by the merchant, typically an order or invoice number. Should be unique.	15	ASCII Print-able	Recommended that a value be provided for Visa & MasterCard. Amex Optional; value for field #34 Invoice Number will take precedence
2	Transaction Type	Type of transaction being processed for this order	1	A	“S” - Sale “R” - Return “C” - Completion No other transaction types are allowed
3	Customer Name	Name of the customer who placed the order	0-25	ASCII Print-able	Amex Used for cardholder’s name
4	Ship To Postal/Zip Code	Postal/ZIP code of the Ship To address Field previously named Postal Code	10	A/N + space	Visa Required if shipment of goods is involved Recommended that a value be provided for all card brands.
5	Ship To Province/State	Province/State of the Ship To address Field previously named Province/State	2	A	Recommended that a value be provided for all card brands.
6	Credit Card Number or Token	Previously used for Credit Card Number OR Token	Max 36	A/N	This field can contain: Full card number with maximum length of 19 digits. “0” (zero): Used in place of card number for Completion, Void, and Return Void transactions. Token with a prefix of “TOKEN:”. Token is 30 bytes maximum. e.g.: “TOKEN:123456” would specify that card information associated with token 123456 is to be used this transaction. Allowed characters: 0-9 A-Z : @ \| - + / _
7	Expiry Date	The expiry date of the credit card in format MMYY.	1 or 4	N	A value of “0” can be used for Completion, Void, Return Void, and token-based transactions.
8	Not Used	Previously used for Authorization Number
9	Invoice Total	Total amount of the order including all taxes, shipping & handling, and discount. Field previously named Gross Amount.	10	N	Recommended that a value be included in order to help troubleshoot any invoice balancing issues.
10	PST/QST Rate	Provincial Sales Tax (PST), Quebec Sales Tax (QST) or U.S. Local Tax Rate expressed as a percentage. Two implied decimal places, no decimal point to be included. Example: Value of “0700” represents 7%.	4	N	Required if PST/QST taxes apply
11	GST/HST Rate	The Goods and Services Tax (GST) or Harmonized Sales Tax (HST) Rate expressed as a percentage. Two implied decimal places, no decimal point to be included. Example: Value of “0700” represents 7%.	4	N	Value of “0” is to be used for tax exempt transactions.
12	PST/QST Amount	Total PST, QST, or U.S. Local Tax for the transaction. Two implied decimal places, no currency sign or decimal point to be included. Example: Value of “100” represents $1.00.	10	N	Required if PST/QST taxes apply
13	GST/HST Amount	Total GST or HST for the transaction. Two implied decimal places, no currency sign or decimal point to be included. Example: Value of “100” represents $1.00.	10	N	Value of “0” is to be used for tax exempt transactions.
14	Shipping & Handling	Total shipping & handling for the order. Two implied decimal places, no currency sign or decimal point to be included. Example: Value of “100” represents $1.00.	10	N	Value of “0” can be used. Visa If Shipping & Handling is being charged as a separate fee then the amount must be specified at invoice level or provided as an invoice line Visa recommends that Shipping & Handling be included as a line item.
15	Order Discount	Total order discount amount. Two implied decimal places, no currency sign or decimal point to be included. Example: Value of “100” represents $1.00.	10	N	Value of “0” can be used. Visa: Required if discount has been applied at invoice level Value must be zero (0) if the discount is applied at the Invoice Line Item Level.
16	Customer PO Number	Identifier provided by the customer such as purchase order number or job number	22	ASCII Print-able	Required if the customer has provided a PO Number or reference number
17	Order Date	Date when the order was placed in format YYYYMMDD. Field was named Transaction Date.	8	N	Visa Required if included on the invoice. Must be earlier or same date as the transaction date.
18	Line Item Count	Number of invoice line items included in the transaction (001 to 999). Number of line items supported by some card associations and financial institutions may be less than 999.	3	N	Recommended that a value be included in order to help troubleshoot any invoice balancing issues.
19	Merchant GST/HST Registration Number	Merchant’s GST or HST registration number.	30	ASCII Print-able	GST/HST registration number included in Payroc merchant setup will be used as a default if no value is provided for this field
20	Merchant PST/QST Registration Number	Merchant’s Provincial Sales Tax registration number.	30	ASCII Print-able	Visa & Amex Required if QST applies
21	Customer GST/HST Registration Number	Customer’s GST or HST registration number.	15	ASCII Print-able	Visa & Amex Required if the customer has provided a registration number
22	Duty Amount	Amount of duty to be paid for the invoice. Two implied decimal places, no currency sign or decimal point to be included. Example: Value of “100” represents $1.00.	10	N	Value of “0’ can be used. Visa Not supported for Canada or U.S. Duty Amount can be included as Invoice Line Item
23	Supplementary Data	For Amex transactions, the Supplementary Data field can be used to pass up to 4 lines of free form text (also known as 4x40). Maximum of 40 characters per text line can be included with each line separated by a semicolon. Example: Text line 1;Text line 2;Text line 3;Text line 4 Allowed characters: 0-9 A-Z a-z ; - spaces For MasterCard transactions, optional Merchant Reference Number can be included.	163	ASCII Print-able
24	Transaction Reference Number	Unique transaction reference number Allowed characters: 0-9 A-Z a-z ; - spaces	1-60	A/N
25	Custom Merchant Description	Custom description to be passed to the card issuer for display on the cardholder’s statement. Allowed characters: A-Z 0-9 - / and space	1-25	A/N
26	City Tax Rate	City tax rate expressed as a percentage Two implied decimal places, no decimal point to be included. Example: Value of “0700” represents 7%.	4	N	Amex Only used for U.S. merchant transactions
27	City Tax Amount	City tax amount Two implied decimal places, no currency sign or decimal point to be included. Example: Value of “100” represents $1.00.	8	N	Amex Only used for U.S. merchant transactions
28	County Tax Rate	County tax rate expressed as a percentage Two implied decimal places, no decimal point to be included. Example: Value of “0700” represents 7%.	4	N	Amex Only used for U.S. merchant transactions
29	County Tax Amount	County tax amount Two implied decimal places, no currency sign or decimal point to be included. Example: Value of “100” represents $1.00.	8	N	Amex Only used for U.S. merchant transactions
30	State Tax Rate	State tax rate expressed as a percentage. Two implied decimal places, no decimal point to be included. Example: Value of “0700” represents 7%.	4	N	Amex Only used for U.S. merchant transactions
31	State Tax Amount	State tax amount Two implied decimal places, no currency sign or decimal point to be included. Example: Value of “100” represents $1.00.	8	N	Amex Only used for U.S. merchant transactions
32	Requester /Buyer Name	The name of the individual/buyer (not the company) requesting the goods or services.	40	ASCII Print-able	Visa Required if invoice amount > $150.00 Recommended that a value be provided for all transactions.
33	Customer Reference	Cardholder’s reference data	17	ASCII Print-able	Amex Can include client specific accounting information
34	Not Used	Previously used for Customer Number
35	Invoice Number	Original record of charge of invoice.	22	ASCII Print-able	Amex Value for field #2 will be used if this field is left blank
36	“Ship to:” Name	“Ship to:” name	40	ASCII Print-able
37	“Ship to:” Address	“Ship to:” address line 1	40	ASCII Print-able	Amex Required if a value has been provided for field #35 Ship To Name
38	“Ship to:” Address	“Ship to:” address line 2	40	ASCII Print-able
39	“Ship to:” City	“Ship to:” city	30	ASCII Print-able	Amex Required if a value has been provided for field #35 Ship To Name
40	“Ship to:” Province Code/State	“Ship to:” province/state code	2	A	Amex Required if a value has been provided for field #35 Ship To Name
41	“Ship to:” Postal Code/ZIP Code	“Ship to:” postal/ZIP code	15	A/N + space	Amex Required if a value has been provided for field #35 Ship To Name
42	“Ship to:” Country Code	“Ship to:” country code	3	A/N	Visa Required for international shipments. Canada will be used as default country if no value is provided for this field. Visa & MasterCard 2 char ISO alpha country code is required Amex Only supports Ship To Country codes for Canada or U.S. Following country codes are supported for backwards compatibility: 124 or CAN for Canada 840 or USA for U.S.

Notes:

For Amex, minimum of one tax type is required:

GST/HST and/or PST/QST for Canadian merchant transactions
Either 1) Local Tax, or 2) City, County, and State taxes for U.S. merchant transactions

For Amex, Ship To fields 36 -41 are only supported if the country is Canada or U.S.

Level 3 (Invoice Line Item) Record 

#	Field Name	Description	Length	Type	Notes
1	Transaction Reference Number	Unique transaction ID assigned by the merchant. Previously named Invoice Number	15	A/N
2	Product Code	Merchant’s SKU number for the item being sold/returned. Field was previously named Item SKU	12	ASCII Print-able
3	Item Description	Merchant’s description of the item being sold/returned.	26	ASCII Print-able
4	Item Commodity Code	Item commodity code which identifies the type of purchase.	12	ASCII Print-able	Visa Value to be provided if required by the merchant’s business
5	Unit of Measure	Unit of measure indicating how the item is sold, e.g.: case, each, bucket, drum.	12	A/N	Amex: Unit of measure code must be expressed as 2 char code defined in ASC X12 (EDI) Standard. Examples of ASC X12 codes: EA=Each BX=Box PK=Pack PC=Piece E5=Inches Value of “EA” will be used if valid code is not provided
6	Unit Cost	Cost per unit of measure. Two implied decimal places, no currency sign or decimal point to be included. Example: Value of “100” represents $1.00.	10	N	Value of “0” can be used for zero cost line items
7	Quantity	Number of units sold or returned. Two implied decimal places, no decimal point to be included. Example: Value of “100” represents 1 unit.	10	N	Visa Value of “0” can be used for zero cost line items MasterCard & Amex Value of “0” cannot be used
8	Discount	Line item discount amount or zero if discount is applied at the invoice header level. Two implied decimal places, no currency sign or decimal point to be included. Example: Value of “100” represents $1.00.	10	N	Value of “0” can be used if the discount is applied at the Invoice Level. Visa Required if discount has been applied at Line Item level
9	Not Used	Previously used for PST Status
10	Not Used	Previously used for GST Status
11	PST/QST Rate	PST/QST or U.S. Local tax rate expressed as a percentage. Two implied decimal places, no decimal point to be included. Example: Value of “0700” represents 7%.	4	N	Value of “0” is to be used for tax exempt or zero cost line items
12	GST/HST Rate	GST/HST rate expressed as a percentage. Two implied decimal places, no decimal point to be included. Example: Value of “0700” represents 7%.	4	N	Value of “0” is to be used for tax exempt or zero cost line items Visa Required even if taxes are calculated at invoice level
13	PST/QST Amount	PST/QST or U.S. Local tax amount for the line item. Two implied decimal places, no currency sign or decimal point to be included. Example: Value of “100” represents $1.00.	10	N	Value of “0” can be used
14	GST/HST Amount	GST/HST amount for the line item. Two implied decimal places, no currency sign or decimal point to be included. Example: Value of “100” represents $1.00.	10	N	Value of “0” can be used Visa Required if taxes were calculated at Line Item level
15	Extended Item Amount	For Visa & MasterCard, Extended Item Amount is calculated as Unit Cost * Quantity - Line Item Discount. For Amex, Extended Item Amount is calculated as Unit Cost * Quantity. Two implied decimal places, no currency sign or decimal point to be included. Example: Value of “100” represents $1.00. Field was named Line Item Total and specified that taxes were included.	10	N	Value of “0” can be used for zero cost line items
16	City Tax Rate	City tax rate expressed as a percentage Two implied decimal places, no decimal point to be included. Example: Value of “0700” represents 7%.	4	N	Amex Only used for U.S. merchant transactions
17	City Tax Amount	City tax amount on the line item. Two implied decimal places, no currency sign or decimal point to be included. Example: Value of “100” represents $1.00.	8	N	Amex Only used for U.S. merchant transactions
18	County Tax Rate	County tax rate expressed as a percentage. Two implied decimal places, no decimal point to be included. Example: Value of “0700” represents 7%.	4	N	Amex Only used for U.S. merchant transactions
29	County Tax Amount	County tax amount on the line item. Two implied decimal places, no currency sign or decimal point to be included. Example: Value of “100” represents $1.00.	8	N	Amex Only used for U.S. merchant transactions
20	State Tax Rate	State tax rate expressed as a percentage. Two implied decimal places, no decimal point to be included. Example: Value of “0700” represents 7%.	4	N	Amex Only used for U.S. merchant transactions
21	State Tax Amount	State tax amount on the line item. Two implied decimal places, no currency sign or decimal point to be included. Example: Value of “100” represents $1.00.	8	N	Amex Only used for U.S. merchant transactions
22	Manufacturer SKU Number	Manufacturer’s stock number for item being sold/returned.	30	ASCII Print-able
23	Customer SKU Number	Customer’s stock number for item being sold/returned.	30	ASCII Print-able
24	Customer PO	Customer purchase order number for specific item.	22	ASCII Print-able
25	Supplementary Data/Order Number	This field may contain a free form product or service description for the line item.	40	ASCII Print-able
26	GL Account Number	This field may contain the general ledger account number for the item/service purchased.	40	ASCII Print-able
27	Division Number	This field may contain the division number of the card member who purchased the item or service.	40	ASCII Print-able
28	PO Line Number	This field may contain the PO line number.	5	N

Notes:

Amex requires at least one Level 3 record (Invoice Line Item) per transaction.

For Amex, minimum of one tax type is required:

GST/HST and/or PST/QST for Canadian merchant transactions

Either 1) Local Tax, or 2) City, County, and State taxes for U.S. merchant transactions

Level 2/3 Data Report File 

This report file is a comma separated values (CSV) file.

The first line is the file header, and is provided to make reading the file easier if required. The header contains this text:

TERMID,REF_NUM,CC_NUM,EXP_DATE,RESPONSE,APPRV

The remaining records in the report file contain the fields in the following table:

#	Field Name	Length	Type	Description
1	Terminal ID	8	A/N	Echoed back from the original transaction
2	Reference Number	60	A/N	Echoed back from the original transaction
3	Credit Card Number OR Token	30	A/N	Contains either the token or a masked version of the credit card number based on the information included in the original transaction.
4	Expiry Date	4	N	Echoed back from the original transaction
5	Response	30	A/N	Contains either the decline message or authorization number and amount followed by an optional UID.
6	Approval Code	1	N	“1”: Approved “0” (zero): Decline or failure

Example 

Example of Level 2/Level 3 Batch File:

20130905, 01, 1, 2, "N", 1000, " TESTTEST ", "08.00"

"INVOICENUMBER1", "C", "CUSTOMERNAME", "L5C1B7", "ON", TOKEN:TOKEN1, 0, "", 1000,
0800, 0600, 72, 54, 160, 200, "CUSTOMERPO", 20130318, 002, "MERCHANTGST",
"MERCHANTPST", "CUSTOMERGST", 79, "SUPPLEMENTARYDATA", "CCSREFERENCENUMBER",
"CUSTOM MERCHANT DESCRIPTI", 0, 0, 0, 0, 0, 0, "REQUESTERNAME", "CUSTOMERREFERENCE",
"CUSTOMERNUMBER", "INVOICENUMBER", "SHIP TO NAME", "SHIP TO ADDRESS", ,
"SHIP TO CITY", "ON", "K8K8K8", "CAN"

"INVOICENUMBER1", "ITEMSKU1", LINE ITEM DESCRIPTION 1", "COMMODITY1", "EACH",
200, 100, 0, "T", "T", 800, 600, 16, 12, 228, 0, 0, 0, 0, 0, 0, "SKUNUMBER",
"JFDJKALJKLL", "CUSTOMERPO", "SUPPLEMENTARYDATA", "GLACCOUNTNUMBER",
"DIVISIONNUMBER", 00002

"INVOICENUMBER1", "ITEMSKU1", LINE ITEM DESCRIPTION 1", "COMMODITY1", "EACH",
200, 100, 0, "T", "T", 800, 600, 16, 12, 228, 0, 0, 0, 0, 0, 0, "SKUNUMBER",
"JFDJKALJKLL", "CUSTOMERP2", "SUPPLEMENTARYDATA", "GLACCOUNTNUMB01",
"DIVISIONNUMB01", 00004

Note: Please be aware that the records in the file above are divided over multiple lines while there would normally only be one line per record. Also, the blank lines above are shown for clarity but do not exist in the actual batch file.

Example of Level 2/Level 3 Data Report File:

TERMID,REF_NUM,CC_NUM,EXP_DATE,RESPONSE,APPRV

TESTTEST,INVOICENUMBER3,TOKEN3,0 ,T31669 $10.00 12082HN,1

TESTTEST,INVOICENUMBER3,TOKEN3,0 ,DETAILS DELIVERED ,1

TESTTEST,INVOICENUMBER3,TOKEN3,0 ,DETAILS DELIVERED ,1

TESTTEST,INVOICENUMBER1,TOKEN1,0 ,T31659 $10.00,1

TESTTEST,INVOICENUMBER1,TOKEN1,0 ,,0

TESTTEST,INVOICENUMBER1,TOKEN1,0 ,,0

TESTTEST,INVOICENUMBER5,,0 ,T31675 $20.00 12082HT,1

TESTTEST,INVOICENUMBER5,,0 ,DETAILS DELIVERED ,1

TESTTEST,INVOICENUMBER5,,0 ,DETAILS DELIVERED ,1

TESTTEST,INVOICENUMBER2,TOKEN2,0 ,T31667 $10.00,1

TESTTEST,INVOICENUMBER2,TOKEN2,0 ,,0

TESTTEST,INVOICENUMBER2,TOKEN2,0 ,,0

TESTTEST,INVOICENUMBER4,TOKEN4,0 ,T31671 $10.00 12082HP,1

TESTTEST,INVOICENUMBER4,TOKEN4,0 ,DETAILS DELIVERED ,1

TESTTEST,INVOICENUMBER4,TOKEN4,0 ,DETAILS DELIVERED ,1

TESTTEST,INVOICENUMBER5,TOKEN5,0 ,T31675 $10.00 12082HQ,1

TESTTEST,INVOICENUMBER5,TOKEN5,0 ,DETAILS DELIVERED ,1

TESTTEST,INVOICENUMBER5,TOKEN5,0 ,DETAILS DELIVERED ,1

Air Travel Data Batch Files 

Record Sequence 

The format of the transaction data is broken down into record types within the transaction batch file. This batch file consists of Batch Header Records and Transaction Records.

A batch file can include multiple batches if transactions are being sent for more than one terminal ID. Each batch in the batch file must include a Batch Header, followed by one or more transaction records.

Record Name	Notes
Batch Header Record	One header record per batch.
Airline Transaction Record	There may be multiple Airline Transaction Records per batch.

Example of record sequence for Air Travel Data Batch:

⇓ Batch Header Record (for terminal ID 1)

⇓ Airline Transaction Record

⇓ Airline Transaction Record

⇓ Batch Header Record (for terminal ID 2)

⇓ Airline Transaction Record

⇓ Airline Transaction Record

⇓ Airline Transaction Record

⇓ Airline Transaction Record

⇓ Batch Header Record (for terminal ID 3)

⇓ Airline Transaction Record

Batch Header Record 

#	Field Name	Length	Type	Req	Description
1	Batch Date	8	N	Y	Batch date in the format YYYYMMDD
2	Batch Number	1-2	N	Y	Batch number for a given date. i.e.: first batch of day = 01, second batch = 02, etc.
3	Transaction Count	1-8	N	Y	Total number of transactions in the file
4	Batch Value	1-12	N	Y	Batch Value is the sum of the absolute value of the Gross Amount included in the Invoice Header records. Two implied decimal places, no currency sign or decimal point to be included.
5	Terminal ID	8	A/N	Y	This field contains the 8 character terminal ID as assigned by Payroc.
6	File Version	5	A/N	Y	Value of “A1.00” indicating the version of batch file format.

Transaction Record 

#	Field Name	Length	Type	Req	Description
1	Transaction Type	1	A	Y	Type of transaction being processed for this order: “S”: Sale “R”: Return “C”: Completion “F”: Force Post No other transaction types allowed.
2	Credit Card Number or Token	16-36	N	Y	This field can contain: Full card number with maximum length of 19 digits. “0” (zero): Used in place of card number for Completion, Void, and Return Void transactions. Token with a prefix of “TOKEN:”. Token is max 30 characters. e.g.: “TOKEN:123456” would specify that card information associated with token 123456 is to be used this transaction. Allowed characters: 0-9 A-Z : @ \| - + / _
3	Expiry Date	1 or 4	N	Y	The expiry date of the credit card in format MMYY, or value of “0” can be used for Completion transactions
4	Amount	1-10	N	Y	Total amount of this order including all taxes and shipping and handling. Two implied decimal places, no currency sign or decimal point to be included. Example: Value of “100” represents $1.00.
5	Reference Number	1-60	A/N	Y	Unique transaction reference number. Allowed characters: A-Z 0-9 - /
6	Authorization Code	0-6	A/N	N	Authorization number provided by the authorizing institution if the transaction has already been approved. Required for Force Post transactions.
7	Merchant Description	0-25	A/N	N	Custom description to be passed to the card issuer for display on the cardholder’s statement. Allowed characters: A-Z 0-9 - / and space
8	PST Rate	4	N	Y	Provincial Sales Tax (PST) rate expressed as a percentage. Two implied decimal places, no decimal point to be included. Example: Value of “0700” represents 7%.
9	GST/HST Rate	4	N	Y	The Goods and Services Tax (GST) or Harmonized Sales Tax (HST) rate expressed as a percentage. Two implied decimal places, no decimal point to be included. Example: Value of “0700” represents 7%.
10	PST Amount	1-10	N	Y	Total PST for the transaction. Two implied decimal places, no currency sign or decimal point to be included. Example: Value of “100” represents $1.00.
11	GST Amount	1-10	N	Y	Total GST or HST for the transaction. Two implied decimal places, no currency sign or decimal point to be included. Example: Value of “100” represents $1.00.
12	Merchant PST Registration Number	0-15	A/N + spaces	N	Merchant’s Provincial Sales Tax registration number.
13	Merchant GST/HST Registration Number	0-15	A/N + spaces	N	Merchant’s GST or HST registration number.
14	Cardholder GST/HST Registration Number	0-15	A/N + spaces	N	Customer’s GST or HST registration number.
15	Cardholder PO Number	0-17	A/N + spaces	N	Identifier provided by the customer, such as PO number or job number.
16	Passenger Name	1-20	A/N + space and slash	Y	Name of the passenger in the format of SURNAME/GIVEN NAME. e.g. SMITH/JOHN
17	PNR Locator	0-18	A/N	N	Passenger name record (PNR)
18	Ticket Identifier	0-14	A/N	N	Passenger’s ticket number
19	Routing	0-36	A/N	N	Routing information for a maximum of 9 segments can be passed to the cardholder. Each segment includes a stopover code followed by the 3 character city/airport code. Stopover code values: “X”: stopover not permitted, “O” (letter) or space: stopover permitted. Example: XYULOYYZXYTZ
20	Departure Date	0-8	N	N	Departure date in format YYYYMMDD
21	Carrier Code	0-18	A/N	N	2 character carrier code for each of up to 9 flight segments. Example: ACAADLCO
22	Carrier Name	0-20	A/N + space + period	N	Carrier/supplier name
23	Flight Number	0-45	A/N + space	N	5 character flight number for each of up to 9 flight segments. Individual Flight Numbers are to be left justified with trailing spaces. Example for 2 flight segments with Flight Numbers of 1234 & 5678;“1234 5678 “

Air Travel Data Report File 

The Air Travel Data Report File is a comma separated values (CSV) file.

The first line is the file header and is provided to improve readability of the file. The header looks like this:

TERMID,REF_NUM,CC_NUM,EXP_DATE,RESPONSE,APPRV

The remaining lines are transaction response records whose fields are detailed in this table:

#	Field Name	Length	Type	Description
1	Terminal ID	8	A/N	Echoed back from the original request
2	Reference Number	60	A/N	Echoed back from the original request
3	Credit Card Number or Token	19-36	A/N	Contains either the token or a masked version of the credit card number based on the information included in the original transaction.
4	Expiry date	4	N	Echoed from the original request
5	Response	30	A/N	Contains either the decline message or an authorization number and amount followed by an optional UID.
6	Approval Code	1	N	“1”: Approved “0” (zero): Decline or failure

Example 

Example of Air Travel Data Batch File:

20120127, 03, 2, 451, "TERMINAL", "A1.00"

"S", 5550000000000003, 0613, 225, "20120125", , , 0000, 1300, 0, 29, "", "", "",
"201013608", "SMITH/JOHN", "PNR123", 01426774075512, "XYULXYBCXYYZXYTZ", 20120127,
"ACAADLCO", "AIR CANADA"

"S", 4520700000000008, 0605, 226, "20120118", 147812, , 0800, 0500, 16, 10, "",
"", "", "201013609", "DOE/JANE", "PNR458", 01426774075215, "XYULXYBCXYYZXYTZ",
20120127, "ACAADLCO", "AIR CANADA","1234 5678 "

Note: Please be aware that records in the example above are divided over multiple lines and word wrapped. There would normally only be one line per record.

Example of Air Travel Data Report File:

REF_NUM,CC_NUM,RESPONSE,APPRV

20120125,************0003,T07322 $2.25 0408X9K,1

20120127,************0008, T07345 $2.26 0408X9J,1

Token Maintenance Batch 

The Token Maintenance batch type is used to perform bulk add, update, deactivate, and reactivate operations on secure tokens stored in the Payroc tokenization database. The file is in comma separated value (CSV) format.

Record Sequence 

Record Name	Notes
Batch Header Record	One header record per file.
Detail Records	There may be multiple detail records per file.

Batch Header Record 

#

Field Name

Length

Type

Req

Description

1

File Identifier

fixed

A/N

Y

Value of “TL1.1” for Token Load format 1.1.

2

Record Count

9

N

Y

Total number of detail records in the file.

Does not include header record.

Detail Record 

#	Field Name	Length	Type	Req	Description
1	Action	fixed	A/N	Y	This field is used to determine what action is to be performed for the token. Values: ADD UPDATE DEACTIVATE REACTIVATE ADD: Used to add/create the token UPDATE: Used to modify credit card number and/or expiry and/or reference data related to the token DEACTIVATE: Used to deactivate the token. Tokens which are deactivated will be deleted after 1 year. REACTIVATE: Used to reactivate the token
2	Terminal ID	8	A/N	Y	Unique identifier provided by Payroc for a merchant/location.
3	Token	30	A/N	Y	Unique ID used in place of a credit card for future payment processing. Submitting a token value containing of “?” for ADD actions specifies that the token value is to be generated by Payroc. The token will be generated by Payroc based on configuration parameters chosen by the merchant. 12 characters is the minimum length for auto-generated tokens. Characters supported: 0-9 A-Z : @ \| - + / _
4	Card Number	25	N	N	Credit card number. This field is required for the ADD action, and is optional for the UPDATE action. This field is not used for the DEACTIVATE and REACTIVATE actions.
5	Expiry Date	4	N	N	The expiry date of the credit card. This field is required for the ADD action, and is optional for the UPDATE action. This field is not used for the DEACTIVATE and REACTIVATE actions. Format: MMYY
6	Token Reference	30	A/N	N	Reference data associated with the token. This field is optional for the ADD and UPDATE actions. This field is not used for the DEACTIVATE and REACTIVATE actions. Characters supported: A-Z a-z 0-9 - /
7	Client ID	50	N	N	Client ID can be used as a key to identify a customer/account number. This field is optional for the ADD and UPDATE actions. This field is not used for the DEACTIVATE and REACTIVATE actions. Characters supported: A-Z 0-9 @ _ . - /
8	Start Date	8	N	N	The first day the token can be used. This field is optional for the ADD and UPDATE actions. This field is not used for the DEACTIVATE and REACTIVATE actions. Format: YYYYMMDD
9	End Date	8	N	N	The last day the token can be used. This field is optional for the ADD and UPDATE actions. This field is not used for the DEACTIVATE and REACTIVATE actions. Format: YYYYMMDD

Token Upload Report File 

The token upload report file will be named the same as the original batch file with the file name extension set to .response

A report file will be created for successful token load files. The report will contain a header plus detail records for each input record.

Header Record 

#

Field Name

Length

Type

Req

Description

1

File Identifier

fixed

A/N

Y

Value of “TLRPT1.1” for Token Load Report file format 1.1

2

Record Count

9

N

Y

Total number of detail records processed.

Does not include header record.

Detail Records 

#	Field Name	Length	Type	Req	Description
1	Action	fixed	A/N	Y	Token action attempted
2	Terminal ID	8	A/N	Y	Terminal ID which loaded the token
3	Token	30	A/N	Y	Token
4	Token Reference	30	A/N	N	Token reference number This field will be populated if a Token Reference value was provided with the transaction in the input file.
5	Result	256	A/N	Y	“OK” or “ERROR: Explanation”

Example 

Example of Token Upload File:

TL1.1,4,Y
ADD,TESTTEST,TOKEN123456,5191111111111111,0912,JOHN-SMITH-MC-TOKEN
UPDATE,TESTTEST,TOKEN567890,378570000000006,0216
DEACTIVATE,TESTTEST,TOKEN123456
REACTIVATE,TESTTEST,TOKEN123456

Example of Token Upload Report File:

TLRPT1.1,4
ADD,TESTTEST,TOKEN123456,JOHN-SMITH-MC-TOKEN,OK
UPDATE,TESTTEST,TOKEN567890,,ERROR: TOKEN NOT FOUND
DEACTIVATE,TESTTEST,TOKEN123456,,OK
REACTIVATE,TESTTEST,TOKEN123456,,OK

Batch Validation Error Report File 

A batch validation error report will be generated if a batch file fails validation rules and cannot be processed. A validation failure will result in the batch file being rejected and a validation error report file being delivered to the associated SFTP mailbox.

The validation error report file will be named the same as the original batch file with the file name extension set to .reject.

This file is not a CSV report. This file is created if there are any validation errors that have prevented the input file from being processed.

If the record count in the input file does not match, then the first line in the file will contain the following:

Header record count: nnn, does not match number of records in file: nnn

If the header record count matches the number of records in the file, then the file format will contain the following:

LINES REJECTED: N

Line n: <errors…>

Example of Validation Error Report with 3 rejected lines where line 3 has two errors:

LINES REJECTED: 3

Line 2: Invalid token ref format

Line 3: TOKEN789456: Invalid credit card number, Invalid token ref format

Line 5: 1238011458: Invalid credit card number

Transaction Types 

Transaction Type	Description
S	Sale Sale transactions will be authorized and included in settlement if approved.
V	Void Used to cancel/remove a previously authorized Sale, Completion, or Force Post transaction. A voided transaction will not appear on the cardholder’s statement. Void transaction must be processed before the original transaction has been settled. If the associated terminal ID has been set up for automatic settlement then a transaction must be voided prior to midnight Eastern Time. Most batch file terminal IDs are set up for automatic settlement. Void transactions are not to be processed for Authorization Only or Pre-Authorization transactions since those transaction types are not included in settlement.
F	Force Post Submit a transaction for settlement for which you have previously obtained an authorization code.
R	Return Used to issue a refund to the customer’s card if goods are returned. Return can also be used to correct a Sale, Completion, or Force Post transaction which has already been settled. The original transaction and the Return transaction will appear on the customer’s statement.
M	Return Void Cancel a previously submitted Return transaction. A voided Return transaction will not appear on the cardholder’s statement. Return Void transaction must be processed before the original Return transaction has been settled. If the associated terminal ID has been set up for automatic settlement then the Return transaction must be voided prior to midnight Eastern Time. Most batch file terminal IDs are set up for automatic settlement.
A	Authorization Only Used to request authorization only. Authorization Only transactions will not be included in settlement. If the transaction is approved then the card’s open-to-buy limit will be reduced, but the card will not be charged.
P	Pre-Authorization Pre-Authorization transactions are typically used to obtain approval when an order is placed. If the Pre-Authorization transaction is approved then a Completion transaction must be used to bill the customer once the order has been filled/shipped. Pre-Authorization are valid for 22 days on MasterCard, and 30 days on Visa, American Express, and Discover.
C	Completion Used to process a charge associated with a previously approved Pre-Authorization transaction. As long as unique transaction reference numbers are used then Completion transactions can be processed with card number set to “0”. This eliminates the need to store credit card information. Alternately, tokens can be used. Multiple Completion transactions can be processed for an order as long as the total amount does not exceed the original Pre-Authorization amount.
W	Authorization Reversal Authorization Reversal transactions are processed to cancel or adjust the hold on cardholder funds associated with a previously approved Pre-Authorization transaction. The merchant can process a full reversal, which cancels a previously approved Pre-Authorization transaction, by submitting an Authorization Reversal transaction with amount of “0“. A partial Authorization Reversal is processed by submitting a transaction with a replacement amount to reduce the funds being held on the cardholder account. Common scenarios where a full reversal is required: The order has been canceled by the cardholder The order cannot be filled by the merchant Partial authorization reversal is used to replace the authorized amount with a lower value. Typical scenarios are as follows: An incorrect amount was authorized by the merchant The merchant determines that some of the goods or services ordered are not available and the cardholder decides to cancel part of the order