Batch Processing Specifications¶
Version 2.0
April 21, 2021
Table of Contents
- Batch Processing Specifications
Section Revision History¶
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
Overview¶
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:
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
|
| 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-40 | ASCII Print-able | Amex
|
| 4 | Ship To Postal/Zip Code | Postal/ZIP code of the Ship To address Field previously named Postal Code |
10 | A/N + space | Visa
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
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:
|
| 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
|
| 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
|
| 21 | Customer GST/HST Registration Number | Customer’s GST or HST registration number. | 15 | ASCII Print-able | Visa & Amex
|
| 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
|
| 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
|
| 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
|
| 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
|
| 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
|
| 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
|
| 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
|
| 32 | Requester /Buyer Name | The name of the individual/buyer (not the company) requesting the goods or services. | 40 | ASCII Print-able | Visa
Recommended that a value be provided for all transactions. |
| 33 | Customer Reference | Cardholder’s reference data | 17 | ASCII Print-able | Amex
|
| 34 | Not Used | Previously used for Customer Number | |||
| 35 | Invoice Number | Original record of charge of invoice. | 22 | ASCII Print-able | Amex
|
| 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
|
| 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
|
| 40 | “Ship to:” Province Code/State | “Ship to:” province/state code | 2 | A | Amex
|
| 41 | “Ship to:” Postal Code/ZIP Code | “Ship to:” postal/ZIP code | 15 | A/N + space | Amex
|
| 42 | “Ship to:” Country Code | “Ship to:” country code | 3 | A/N | Visa
Visa & MasterCard
Amex
|
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
|
| 5 | Unit of Measure | Unit of measure indicating how the item is sold, e.g.: case, each, bucket, drum. | 12 | A/N | Amex:
|
| 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
MasterCard & Amex
|
| 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
|
| 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
|
| 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
|
| 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
|
| 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
|
| 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
|
| 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
|
| 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
|
| 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
|
| 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 |
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"
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…>
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:
Partial authorization reversal is used to replace the authorized amount with a lower value. Typical scenarios are as follows:
|