Real-Time Transaction Processing Integration

Revision 18.3.1

March 19, 2018

Table of Contents

• Real-Time Transaction Processing Integration
  • Section Revision History
  • Introduction
  • Data Definition Tables
  • How Credit Card Processing Works
  • Processing Transactions
    • Transaction Delivery Methods
    • Transaction Requests
    • Transaction Responses
    • Transaction Types
    • Sample Transaction
  • Tokenization
    • What is Tokenization?
    • Benefits Of Using Tokenization
    • How Payroc’s Tokenization Solution Works
      • Associating Tokens With Cards
      • Charging Cards Using Tokens
      • Modifying Token Data
      • Example Of Tokenization Use
    • Auto-Generated Token IDs
    • Card Authentication
    • Payment Scheduling
  • Enhanced Data Submission
    • Transaction Flow
    • Transaction Flow for Air Travel Data
  • Address Verification Service (AVS)
    • AVS Examples
    • AVS Result Codes
    • AVS Testing
  • Card Security Code/CVV Authentication
    • Result Codes
    • CSC Testing
  • Real-Time Transaction Types
  • Real-Time Transaction Request Fields
  • Real-Time Transaction Response Fields
  • Real-Time Transaction Response Text and Return Codes
    • Successful Transaction
    • Unsuccessful Transaction
    • Response Codes
  • Real-Time Enhanced Data Processing
    • Level 2 Data Format
    • Level 3 Data Format
    • Level 2 Data Format (Airline)
    • Air Travel Data
  • Real-Time Magnetic Card Track Data Field Formats
    • Sending Track 1 Or Track 2 Data
      • Sending Track 1
      • Sending Track 2
  • Real-Time Testing Amounts and Return Codes
  • Real-Time Transaction Examples
    • Sale Transaction
    • Sale Transaction with Extended Response data
      • Approved Sale
      • Rejected Sale
    • Balance Request Transaction
    • Settlement Transaction
    • Authorization Only Transaction
      • A. Authorization Only Transaction For $10.00
      • B. Authorization Only Transaction Using The Resend Flag
      • C. Authorization Only Transaction Using An Expired Card
      • D. Authorization Only Transaction Using An Expired Card And Receiving Different Response
    • Force Post Transaction
    • Pre-Authorization Transaction
    • Completion Transaction
      • A. Completion Without Card
      • B. Completion Transaction For $50.00 That Has Already Been Completed
      • C. Multiple Completion Transactions
        • 1. Pre-Authorization for $100.00
        • 2. First Completion Transaction For $50.00 Without The Credit Card Number
        • 3. Second Completion Transaction For $50.00 Without The Credit Card Number
        • 4. Third Completion Transaction For $50.00 Without The Credit Card Number.
    • Void Transaction
      • A. Void Transaction For $50.00 Without The Credit Card Number
      • B. Second Attempt To Void Completion Transaction For $50.00 Without The Credit Card Number
    • Return Transaction
    • Return Void Transaction
      • A. Void A Return Transaction For $25.00 Without The Credit Card Number
      • B. Second Request To Void A Return Transaction For $25.00 Without The Credit Card Number
    • Contra Transaction
      • A. Add A Credit Card Number To The Contra List
      • B. Contra Decline
      • C. Contra Delete
    • Token Transactions
      • Creating A Token
      • Creating Auto-Generated Tokens
      • Token Update
      • Token Operation with Card Authentication
      • Token Deactivate
      • Token Reactivate
      • Creating a Token and Payment Schedule
      • Creating a Payment Schedule for an existing Token
      • Updating a Payment Schedule
      • Updating a Payment Schedule amount
      • Deactivating a Payment Schedule
      • Sale Transaction Using A Token
      • Pre-Authorization Transaction Using A Token
    • Full Authorization Reversal
      • A. Pre-Authorization Transaction For $100.00
      • B. Pre-Authorization Reversal
    • Partial Authorization Reversal
      • A. Pre-Authorization Transaction For $375.25
      • B. Replacing The Pre-Authorized Amount
    • Account Status Inquiry
      • Account Status Inquiry - Positive Card Status
      • Account Status Inquiry - Negative Card Status
    • Level 2/Level 3 Transaction
      • A. Sale With Level 2 Data
      • B. Level 3 Detail Submission Transaction (Line Item)
    • Air Travel Data Transaction
      • Sale With Level 2 And Air Travel Data

Section Revision History

May 8, 2018

• Level 2/3 Data fields updated
• List of expiry dates in the Testing Procedures section updated

April 17, 2015

• Tokenization
  • Payment Scheduling functionality added
• Real-Time Transaction Types
  • Payment Scheduling transaction type added
• Real-Time Request Fields
  • Payment Scheduling request fields added

February 20, 2015

• Tokenization
• Auto-Generated Token ID functionality added
• Card Security Code (CSC) & AVS authentication for Token operations added
• Address Verification Service (AVS) section updated
• Card Security Code (CSC) Authentication section added
• Real-Time Transaction Types
  • Account Status Inquiry added
• Real-Time Transaction Request & Response Fields
  • Cardholder name field added
  • Extended response option fields added

Introduction

Payroc’s financial transaction processing system is easily integrated with existing company financial systems and point-of-sale devices using simple messages over industry-standard SSL connections. The same technology used by your web browser to encrypt sensitive data is used to communicate with our real-time financial transaction processing system.

Integration of credit card processing with existing systems can be easily achieved using the SSL APIs and tools available for most modern programming languages. Transaction messages supported by Payroc’s interface consist of simple strings of “name=value” pairs, which can be sent using HTTP over SSL.

Payroc supports a wide range of transaction types as well as standard fraud prevention tools, such as card security codes and address verification.

All of Payroc’s transactions can be used with tokens in place of the card number and expiry date. This allows you to have all of your sensitive card data stored by Payroc, greatly improving your security and simplifying your PCI compliance. Please see our Tokenization section for more information.

Other features of our system include card and merchant transaction velocity, duplicate transaction checking, transaction response retransmission, and unwelcome card checking (contra checking).

Our web-based and email reporting systems allow you to easily reconcile the day’s transactions against your database or accounting records.

Data Definition Tables

Data definition tables used in sections of this document explain the type of data used in transaction request and response 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.

How Credit Card Processing Works

The credit card charging process consists of three stages: authorization, settlement, and deposit.

Authorization is where Payroc asks the card issuer to tell us if there is enough open-to-buy credit available on the card to make the purchase. A successful authorization lowers the card’s open-to-buy limit, but not the card’s available credit. This open-to-buy reduction will be restored if there is no subsequent deposit or reversal for that authorization. The time it takes for the open-to-buy to be automatically restored is usually around five days, but can be shorter or longer depending on the card issuer.

Settlement is the process where all of the transactions that will cause funds to move are gathered up for inclusion in the day’s deposit files. This is also known as a batch close. Depending on your setup, this can be time-based (automatic), or merchant-initiated.

Deposit is where we collect all of the transaction batches marked for deposit and send them in deposit files to the merchant’s bank. Once at the bank, the funds are placed into the merchant’s account. The charged credit cards’ available credit is affected at this point. Payroc will deposit all settled transactions daily.

Processing Transactions

Transaction Delivery Methods

Payroc supports real-time transactions over SSL. You can connect to our transaction-processing server using SSL and send the transaction without HTTP headers, or an HTTPS GET can be used in order to send the transaction and receive the response in an HTTP response format. The POST method is not supported.

The HTTPS GET method is useful if your software is capable of performing HTTPS page retrievals, and this is by far the most popular method for processing transactions with Payroc. Our servers use port 443 or port 1443 for all SSL-encrypted transaction traffic. You may send to either port. The host name used for all real-time transaction requests is “lt3a.caledoncard.com”.

In its simplest form, the HTTPS transaction may be accomplished with a regular web browser by entering the transaction in the URL field. The response is then delivered back to the browser as a document of MIME type “text/plain”, which will allow the response to be shown in the browser.

Using a browser is a good method of testing connectivity before you start building your interface. Note that regardless of whether you use the HTTPS GET method or the raw SSL method, the response will be the same, and will contain “Content-type:” and “Content-length:” MIME tags.

Transaction Requests

All transactions are delivered using field names and values. Transaction requests are built by concatenating a series of fields and their values, separated by ampersands (&).

If an ampersand is required for a field value then two ampersands (“&&”) must be sent in order to distinguish between field data and field separators.

Please see section Real-Time Transaction Request Fields for more information on transaction fields that can be sent with transactions.

Transaction Responses

Responses will consist of a string of field names and their associated values, separated by ampersands. HTTP headers will be received before the response message.

Please see section Real-Time Transaction Response Fields

Transaction Types

Payroc supports a complete suite of transaction types including the following: Sale, Void, Return, Return Void, Pre-Authorization, and Completion. Please note that in this documentation, transaction types used in a non-title context are italicized to improve clarity.

Please see section Real-Time Transaction Types

Sample Transaction

The sample below shows a transaction request and response for a real-time credit card Sale transaction.

Transaction Request:
https://lt3a.caledoncard.com/TERMID=TESTMERC&CARD=5123456789012345&EXP=0407&AMT=4350&REF=43&TYPE=S

Transaction Response:
HTTP/1.0 200 OK Content-type: text/plain Content-length: 47 TEXT=045560 $43.50&AUTH=045560&CODE=0000

Tokenization

What is Tokenization?

Tokenization is the process of exchanging credit card account data for a token which “stands in” for the credit card data for subsequent transactions sent to Payroc.

The main benefit of tokenization is that the merchant no longer has to store their own credit card data; they store a token instead. Payroc will retrieve the card data associated with the token in order to perform transactions against the card. The credit card account data never again needs to be sent by the merchant once a token is acquired. The card data is stored in Payroc’s secure credit card vault, which is an encrypted, protected database designed to be PCI compliant.

Benefits Of Using Tokenization

Tokenization offers many benefits for the merchant:

• In case of a merchant data security breach or information leak, no card numbers can be stolen.
• The merchant does not have to deal with encryption and key management, including periodic PCI-mandated key changes.
• Recurring payments are simplified due to the fact that account numbers can be used as tokens in place of credit card data.
• Payment applications can process transactions such as Completions and Returns without card numbers, greatly simplifying PA-DSS compliance.
• Third party developers can work on merchants’ e-commerce applications without the risk of them gaining access to sensitive customer credit card data.
• The risk to your company’s reputation is greatly diminished in the event of a merchant data security breach.
• The merchant will be able to make use of future developments in Payroc’s tokenization solutions, including tokenization of other sensitive data.
• PCI compliance is made much easier and less costly for the merchant using tokenization since the card storage zone is now in Payroc’s hands.

How Payroc’s Tokenization Solution Works

Associating Tokens With Cards

When a merchant has collected credit card information and wishes to convert it into a token, they will send a transaction to Payroc containing the credit card number and expiry date. The merchant can specify the token that they would like to use to refer to the credit card account or the token can be automatically generated by Payroc. The card information will be encrypted by Payroc and stored in our secure token vault. This token will now be available to the merchant for charging of the customer’s credit card. At Payroc, each token is associated with a particular company or merchant.

Charging Cards Using Tokens

Once a token is in Payroc’s secure credit card vault it can be used to charge the associated card. At this point, transactions being sent to Payroc’s authorization gateway no longer require a card number and expiry date; a token is sent in their place. The token can be used for all types of transactions, including Sales, Returns, Voids, Pre-Authorizations, and Completions.

Storage of the token at the merchant site is much safer than storing the real card data, since the token can only be used to initiate charges between Payroc’s merchant and the stored card number. A hacker or thief cannot directly profit from the tokenized card data. Even if the merchant’s financial system is compromised, any transactions performed by intruders using that system can be corrected upon detection by the merchant and Payroc. The cardholder’s data is always safe.

Modifying Token Data

From time to time, certain data associated with a token may need to be updated. A customer’s card may expire, or the merchant may want to change the card number on file. Payroc provides a transaction to make either of these modifications. The token name and the new credit card information are sent to Payroc and we update the information in our vault immediately. Tokens can also be deactivated and reactivated in the same manner.

Example Of Tokenization Use

Here is a very simple example of the use of tokenization for payment processing:

Imagine that you run a small telephone company. In order to keep things simple, your customer’s account number in your billing system is the same as their phone number. Bob Smith has the phone number 416-555-1212, so this is his account number in your company’s system.

When Bob signs up for service with your phone company and tells you he would like to pay by credit card, your billing system sends Payroc a transaction requesting that his credit card information be tokenized. The tokenization transaction to Payroc contains the credit card number and the expiry date, as well as Bob’s account number “416-555-1212”.

Payroc’s card processing system sends a reply back to your company’s billing system confirming that we now have the customer’s payment information. At this point, the phone company’s system can discard the credit card data. The token “416-555-1212” will now be sufficient information to charge Bob Smith’s card.

A few months later, Bob’s card is about to expire. Updating the expiry date on file at Payroc is as simple as sending the token with a new expiry date. The merchant does not need to collect the credit card number again.

Auto-Generated Token IDs

Merchants can specify the Token ID values to be associated with their customers’ card information or unique Token ID values can be automatically generated by Payroc.

A combination of Payroc auto-generated Token IDs and merchant assigned Token ID values can be used if there are multiple processes where Tokenization is being implemented.

If the merchant chooses to implement auto-generated Token IDs then they can select the maximum length and format of the Token IDs to be created. Length and format to be used for auto-generated Token IDs will be setup as parameters when Tokenization is enabled for the merchant.

Options available for the format of auto-generated token IDs are:

• Merchant can specify a prefix to be included in the Token ID value
• Card type can be included in the Token ID suffix
• Last 4 digits of the card number can be included in the Token ID suffix

Auto-generated Token IDs are created by including a “?” in the TOKEN field when submitting a Token Add request. See Token Transactions in the Real-Time Transaction Examples section for more details on the formatting of auto-generated Token IDs.

Card Authentication

Card Security Code (CSC) & AVS authentication can be performed by including additional fields when submitting a Token Add or Token Update request.

If the CSC and/or AVS fields are included in a request then the values will be sent to the card issuer for authentication prior to adding or updating a token. See the Address Verification Service (AVS) and Card Security Code (CSC) Authentication sections for additional details.

If either the CSC or AVS authentication fails then the token operation (Add or Update) will not be executed. If the authentication is successful then the requested token operation will be processed.

Both the CSC and AVS authentication result will be returned in the response message if the Extended Response option is being used. See EXT_RESP field in Real-Time Transaction Request Fields section for information on Extended Response option.

Payment Scheduling

A payment schedule can be created for a Token where the transactions will be automatically processed by Payroc based on the frequency specified by the merchant.

A payment schedule can be setup after a Token has been created or a single request can be used to create a Token and payment schedule at the same time.

See Real-Time Transaction Types Real-Time Transaction Request Fields, and Token Transactions in the Real-Time Transaction Examples section for more information regarding Payment Scheduling requests.

Enhanced Data Submission

In order to submit detail information for inclusion on commercial card statements, Level 2 data must be submitted at the same time as Level 1 data. Level 3 data is sent in separate transactions and linked with the Level 2 data by a Unique Identifier (UID). Payroc’s system will deliver the UID in the transaction response for commercial card authorizations. Only commercial card transactions will receive a UID in the authorization response.

Level 3 details are submitted using the Level 3 Detail Submission transaction (type L) with one line item being delivered per transaction. All of the line items for a particular Level 1 transaction must be sent with the UID assigned to that transaction. Up to 999 line items can be sent for each Level 1 transaction but only accept 99 items can be handled by some card brands. Please contact us for more details if you need to send large numbers of line items per transaction.

Transaction Flow

The sequence of transactions for commercial card detail delivery is as follows:

⇓ Send Level 1 and Level 2 information in the same transaction message

⇓ Receive authorization response and UID

⇓ Send Level 3 line item with UID

⇓ Receive confirmation response (“DETAILS DELIVERED”)

⇓ Send Level 3 line item with UID

⇓ Receive confirmation response (“DETAILS DELIVERED”)

⇓ Send Level 3 line item with UID

⇓ Receive confirmation response (“DETAILS DELIVERED”)

⇓ Send next Level 1 and 2 transaction

⇓ Receive authorization and UID

⇓ Send Level 3 line item with UID

⇓ Receive confirmation response (“DETAILS DELIVERED”)

⇓ Send Level 3 line item with UID

⇓ Receive confirmation response (“DETAILS DELIVERED”)

… etc.

The UID may accompany the transaction information all the way through to the card issuer’s billing system, where it is used to match the Level 1 data with the Level 2 and 3 data. The UID must be included in order for Level 3 details to be included with the transaction. Sequence numbers can be added to Level 3 transactions in order to specify the order of the invoice line item details to appear on the statement.

UIDs are unique in that they are never duplicated throughout the whole banking network. Since they are of a finite size, UIDs are only returned on transactions that can use them. You will receive a UID under the following circumstances:

• The transaction is a Sale, Force Post, Return, or Completion
• The terminal ID is set up for Level 2 and 3 processing
• The transaction was successful (approved)
• The card is a commercial Visa, MasterCard, American Express, Sears, or HBC card

If your terminal ID is set up for Level 2 delivery, UIDs are returned regardless of whether Level 2 data is sent.

Transaction Flow for Air Travel Data

Air Travel Data (field name “AIR”) is submitted in the same transaction message as the Level 1 and Level 2 data. No UID is required to send Air Travel Data. Air Travel Data can be sent on commercial cards as well as all American Express cards. Level 2 and Air Travel Data can be sent in the same transaction.

Address Verification Service (AVS)

Address Verification Service (AVS) allows cardholder address information to be included with a credit card transaction or token operation for comparison with the address that the card issuer has on file.

AVS is currently available for Visa, MasterCard, American Express, and Discover.

Address information is submitted for verification by including the “AVS” field in a request message.

The following rules apply:

• Maximum AVS data length of 29 characters including letters, numbers, and hyphen(-)
• Address information can include street address or PO box, and ZIP/postal code
• Street address can include street number and street name or only street number
• If the ZIP/postal code is included then it must be placed in the last 5-9 characters of the AVS field
• Numbered street names cannot be spelled out, e.g.: Third Street must be submitted as 3RDSTREET
• If a PO box is being submitted then a hyphen (-) must be placed between the PO box and the ZIP code/postal code, e.g.: POBOX1234-M9M9M9, POBOX1234-99999

AVS Examples

Using address of 27 Mill St East, Toronto, ON, J8Z 3N5:

AVS=27MILLJ8Z3N5

AVS=27J8Z3N5

AVS=J8Z3N5

AVS Result Codes

Result of the address verification will be returned in the “AVS” response field.

List of possible AVS result codes are provided in the tables below. Separate tables have been provided based on type of result.

AVS Result Codes - Match

All of the result codes listed below specify a case where the postal/zip code matched the issuer’s records.

Result Code	Description
D	Postal code match, street address match or not provided in the request
F	Postal code match, street address match or not provided in the request. Applies to U.K. issued cards.
M	Postal code match, street address match or not provided in the request
P	Postal code match, street address not provided in the request or not verified due to incompatible formats
W	Postal code match, street address not provided in the request or does not match
X	Postal code match, street address match or not provided in the request
Y	Postal code match, street address match or not provided in the request
Z	Postal code match, street address not provided in the request or does not match

AVS Result Codes - Address Match Only

Result codes listed below indicate that only the street address matched the issuer’s records. If only postal/zip code was included in the AVS request field then these result codes should be considered as no AVS match.

Result Code	Description
A	Street address match only
B	Street address match, postal code not verified due to incompatible formats

AVS Result Codes - No Match

Result codes listed below indicate that the both the street address and postal/zip code do not match the issuer’s records. Some issuers may return the same result code when only street address or postal/zip code was included in the AVS request field.

Result Code	Description
N	Street address and ZIP code/postal code do not match

AVS Result Codes - Not Processed

All of the result codes included in this table indicate that the issuer did not verify the address information.

Result Code	Description
C	Street address and postal code not verified due to incompatible formats
G	Address information not verified
I	Address information not verified by international issuer
R	Issuer/service not available
S	AVS service not supported by issuer
U	No AVS response received from issuer

AVS Testing

For AVS testing, the AVS result code returned will be based on the first character of the data included in the AVS request field.

The first character of the AVS field can be set to either a number or letter to perform testing for different formats of postal/zip codes - see the 1^st Digit and 1^st Letter columns included in the tables provided below.

AVS Result Codes - Match

1st Digit	1st Letter	Result Code	Description
1	A	D	Postal code match, street address match or not provided in the request
	B	F	Postal code match, street address match or not provided in the request. Applies to U.K. issued cards.
2	C	M	Postal code match, street address match or not provided in the request
3	D	P	Postal code match, street address not provided in the request or not verified due to incompatible formats
4	E	W	Postal code match, street address not provided in the request or does not match
5	F	X	Postal code match, street address match or not provided in the request
6	G	Y	Postal code match, street address match or not provided in the request
7	H	Z	Postal code match, street address not provided in the request or does not match

AVS Result Codes - Address Match Only

1st Digit	1st Letter	Result Code	Description
8	I	A	Street address match only
	J	B	Street address match, postal code not verified due to incompatible formats

AVS Result Codes - No Match

1st Digit	1st Letter	Result Code	Description
9	K	N	Street address and ZIP code/postal code do not match

AVS Result Codes - Not Processed

1st Digit	1st Letter	Result Code	Description
	L	C	Street address and postal code not verified due to incompatible formats
	M	G	Address information not verified
	N	I	Address information not verified by international issuer
	P	R	Issuer/service not available
0	Q	S	AVS service not supported by issuer
	R	U	No AVS response received from issuer

Card Security Code/CVV Authentication

Card Security Code (CSC) authentication allows the security code printed on a card to be included with a transaction for comparison with the value that the card issuer has on file.

Card Security Code is commonly referred to as CVV within the payment industry.

The card security code is submitted for verification by including the “CVV2” field in the request message for a credit card transaction or token operation.

CSC authentication is currently available for Visa, MasterCard, American Express, and Discover.

Result Codes

The results of the CSC authentication will be returned in the “CVV2” response field if the Extended Response option is being used.

The following table provides a list of possible result codes.

Result Code	Description
Y	Match (American Express cards)
M	Match (Visa, MasterCard and Discover cards)
N	No Match
P	Not Processed
S	Unexpected Issuer Response
U	Issuer does not participate in CSC service
X	Unexpected Issuer Response

CSC Testing

For CSC testing, the CSC result code will depend on the first digit of the submitted CSC data.

1st Digit	Result Code	Description
0		Reserved (No CSC result code will be returned)
1		Reserved (No CSC result code will be returned)
2		Reserved (No CSC result code will be returned)
3	Y	Match (American Express cards)
4	M	Match (Visa, MasterCard and Discover cards)
5	N	No Match
6	P	Not Processed
7	S	Unexpected Issuer Response
8	U	Issuer does not participate in CSC service
9	X	Unexpected Issuer Response

Test transactions are approved or declined based on the expiry date included in the request. See the Real-Time Testing Expiry Dates and Return Codes section for additional details.

Real-Time Transaction Types

This table includes the Transaction Type or TRANTYPE value used when submitting transactions to Payroc. Transaction types in this document are italicized for clarity.

Transaction Type	Description
J	Account Status Inquiry Account Status Inquiry allows the merchant to check the status of a card. CSC and AVS data provided by the cardholder can also be included for verification by the card issuer. Expiry date must be provided for an Account Status Inquiry transaction but will not be verified by the card issuer. Account Status Inquiry transactions are only currently supported by a limited set of authorization gateways. Please contact Payroc’s Merchant Services department for details on current availability.
W	Authorization Reversal Authorization Reversal allows the merchant to adjust the authorization amount after the transaction has taken place. The merchant can also process a full reversal, where the transaction is canceled by entering 0 as the replacement amount. 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
A	Authorize Only Used to request authorization only. Authorization Only transactions will not be included in settlement. This transaction should only be used in special cases. Please discuss this with Payroc’s Merchant Services department before using this transaction type. If the transaction is approved then the card’s open-to-buy limit will be reduced. If you use this transaction type, you can Force Post the transaction to cause draft capture.
B	Balance Request Request totals for a terminal ID and operator ID pair. Note that the format of the returned text varies depending on the final authorizing institution. Also note that auto-settled customers must use the operator ID for the day of the week they are querying. (Sunday is “001”, Monday is “002”, etc.)
K	Commercial Card Check This transaction checks to see if a particular card is a commercial card. This transaction returns a “0000” return code if the card is a commercial card or a “1080” return code if it is a non-commercial card.
C	Completion Used to process a charge associated with a previously approved Pre-Authorization transaction. There must be a corresponding Pre-Authorization transaction in the past 30 days (22 days for MasterCard) in order to use this transaction type. Unique transaction reference numbers must be used within the past 30 days. If you do not have the credit card number, then “0” (zero) can be sent in the credit card number field. The system will look up the corresponding Pre-Authorization and mark it for deposit. An expiry date must be supplied; “0000” may be used in place of the expiry date if you do not have one. Multiple Completion type transactions can be processed for an order as long as the total amount does not exceed the Pre-Authorization amount.
(plus sign)	Contra Add This transaction adds a card number to a list of cards that you do not want to accept. Once added, a card cannot be charged by the terminal ID that added it until it is deleted from the list. This allows you to mark certain cards as unwelcome. When you attempt to process a card that is present in your Contra table, it will be declined with the message “DECLINED (CONTRA)” (return code 1008).
(minus sign)	Contra Delete This transaction removes a card number from the list of cards that you do not want to accept. Once removed, the card will process normally again.
Q	Contra Query This transaction is used to check to see if a particular card number is present in the terminal ID’s Contra table. The transaction will return the message “PRESENT” (return code “0000”) if the card is present, and “NOT PRESENT” (return code “1012”) if it is not present.
F	Force Post Submits a transaction for settlement for which you have previously obtained an authorization code. This transaction type can be used to collect funds for a previous Authorization Only transaction. This transaction is no longer recommended. Please contact Payroc Merchant Services if you have reason to use this transaction type.
L	Level 3 Detail Submission This transaction submits Level 3 detail line items for a previously authorized transaction containing Level 2 data. You will need to send your terminal ID, the UID, the Level 3 data, and the sequence number in order to use this transaction. Please see the Enhanced Data Submission and Level 3 Data Format sections for additional information.
N	Payment Scheduling Payment Scheduling transactions are used to setup a schedule where Payroc will automatically process authorization requests for the amount due for recurring charges and payment plans. Based on the fields included with the request, a Payment Scheduling transaction can be used to perform one or more of the following actions: create a Token ID update an existing Token ID create a payment schedule update an existing payment schedule de-activate or re-activate a payment schedule Please see the Real-Time Transaction Request Fields section and Token Transactions in the Real-Time Transaction Examples section for additional details.
P	Pre-Authorization Pre-Authorization transactions are used to obtain approval when an order is placed. If the Pre-Authorization transaction is approved then a Completion transaction can be used to charge the cardholder once the order has been filled or shipped. Pre-Authorization transactions are valid for 22 days on MasterCard, and 30 days on Visa, American Express, and Discover.
R	Return This transaction is used to issue a refund to the customer’s card if goods are returned. A Return can also be used to correct a Sale, Completion, or Force Post transaction which has already been settled. The Return transaction will appear on the customer’s statement as a credit.
M	Return Void This transaction will cancel a previously submitted Return transaction. A voided Return transaction will not appear on the cardholder’s statement. A 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.
S	Sale The Sale transaction charges the specified amount to the credit card (if approved) and marks the transaction for deposit during the next settlement period. This is the most common transaction used to charge for goods and services.
D	Settlement This transaction type marks the batch for deposit and clears the totals for the terminal ID and operator ID pair. Auto-settled customers should never use this transaction type, since it will cause incorrect reporting and difficulty in reconciliation.
G	Token Operation This transaction type is used to manage tokens. A token is a unique ID which can be created and used in place of credit card information for future payment processing. The token name is chosen by the merchant or can be automatically generated by Payroc. Tokens are typically created in cases where a customer is opening an account with the merchant and intends to make future purchases, or where future returns or adjustments might be necessary without the card number. Future payments can be processed by specifying the token assigned to a customer account in place of the credit card number and expiry date.
V	Void Used to cancel or 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 the transaction must be voided prior to midnight Eastern Time. Void transactions are not to be processed for Authorization Only or Pre-Authorization transactions since those transaction types are not included in settlement. See the Authorization Reversal transaction type in order to remove Authorization Only and Pre-Authorization transactions.

Real-Time Transaction Request Fields

The table below details the fields that can be included in transaction request messages. Some fields are required for certain transaction types, and some fields are optional for some types of transactions. See the Data Definition column for specifics.

The Field Name is the Name portion of the “Name=Value” pair. Fields are separated by ampersands (“&”).

TERMID must always be the first field specified in the request message. All other fields can be included in any order.

Field Name	Data Definition	Description
TERMID	8 bytes alphanumeric Required for: All Optional for: None	TERMINAL ID Assigned by Payroc. This field must be at the beginning of the transaction string. The Terminal ID is 8 characters long, and is often alphanumeric (EBOOKSTR or PIZZA001). The terminal ID and your IP address are used to authenticate you for transaction processing. Your password is also used to authenticate you if this feature is activated. (see PASSWORD field below)
AIR	200 bytes alphanumeric + spaces + symbols Optional for: SFRC	AIR TRAVEL DATA Airline credit charge information with fields separated by pipe character (“|”). Air Travel Data is a description of the trip for inclusion on the credit card statement. Air Travel Data can be submitted for American Express, Diners, commercial Visa cards, and commercial MasterCards. Please see the section entitled `Air Travel Data for the format and data included in this field.
AMT	10 bytes numeric Value must not be “0” except for tran type W. Required for: SVFRMAPC Optional for: WN	AMOUNT The transaction amount for the transaction with no currency signs or decimal. (Example: “100” would be one dollar on a Canadian funds account, and would be 1 Euro on a Euro account.)
AUTH	6 bytes max, alphanumeric Required for: F	AUTHORIZATION NUMBER This field is used for Force Post transactions only. When you already have an authorization number for a particular transaction, there is no need to obtain another. A Force Post transaction will allow you to deposit transaction charges for which you already have an authorization number. In order to do this, you will need to provide the original authorization number in this field. The authorization number can be from 2 to 6 characters long, alphanumeric.
AVS	29 bytes max, alphanumeric + spaces Optional for: GJSAP	ADDRESS VERFICATION SERVICE DATA Address information is submitted for verification by including the AVS field in a credit card request message or token operation. See the Address Verification Service section of this document for format and rules.
CARD	25 bytes max, numeric CARD field is required for: JSFRMAPVCW+-QK CARD field can be omitted if a Token is being used to process a payment transaction. See Description for Token Operation requirements	CREDIT CARD NUMBER The credit card number or PAN to be charged. No spaces, dashes, hyphens or any other punctuation are allowed. For Completion, Void and Authorization Reversal transactions without card numbers or token data, CARD with value “0” (zero) must be included in the request. For Token Operation transactions: CARD field is required if TOKEN_ACTION value is “ADD” CARD field is optional if TOKEN_ACTION value is “UPDATE”
CHNAME	40 bytes max, alphanumeric plus some symbols Optional for: SFRAPC	CARDHOLDER NAME Characters supported for cardholder name include: A-Z 0-9 . ‘ - _ / \ and space The cardholder name should be submitted as embossed on the face of the card.
CVV2	4 bytes max, numeric Optional for: GJSAP	CARD SECURITY CODE This 3 or 4 digit number is used to ensure the physical presence of a card in an environment where the cardholder is not in front of the merchant at the time of the purchase, such as during an Internet or phone transaction. This value appears as additional numbers following the credit card number which is printed within the signature panel on the back of the card. For some card types, the security code is on the front of the card near the card number. This field is used for VISA CVV2, MasterCard CVC2, American Express Card CID, and Discover CID.
DESC	25 bytes max, alphanumeric + spaces Optional for: SFRC	DYNAMIC MERCHANT DESCRIPTION This field contains a custom merchant description that will appear on the cardholder’s statement. This will override your default merchant description. You must be set up ahead of time in order to use this feature. Limits on length vary by card type: Visa: 25 characters MasterCard: 22 characters American Express: 20 characters This feature may not be available on all merchant setups.
ECHO	60 bytes max, alphanumeric Optional for: All	ECHO DATA Data that is submitted in this field is returned in the reply. This can be useful for transaction tracking in single-process or batch applications. This field’s submitted data is returned in the ECHO field of the transaction reply.
EXP	4 bytes numeric EXP field is required for: JSFRMAPVCW EXP field can be omitted if a Token is being used to process a payment transaction. See Description for Token Operation requirements	EXPIRY DATE The expiry date on the card. The expiry date must be specified in the form MMYY, and must not contain any characters other than the digits 0-9. For Completion, Void and Authorization Reversal transactions without card numbers or token data, EXP with value “0000” (zero) must be included in the request. For Token Operation transactions: EXP field is required if TOKEN_ACTION value is “ADD” EXP field is optional if TOKEN_ACTION value is “UPDATE”
EXT_RESP	1 byte, “Y” Optional for: GJSFRAPC	Extended Response Extended Response field can be included in a request to specify that additional fields should be returned in the transaction reply. Additional response fields returned in the transaction reply may include: CTYPE - Card Type CPROD - Card Product CCO - Card Country of Origin CVV2 - CSC Result Code RESP_TYPE - Response Type LAST4 - Last four digits of card number See Real-Time Transaction Response Fields section for details regarding the response fields listed above.
INITIATOR	1 byte Optional for: SFAP	Payment Initiator This field is required for PreAuthorization and Sale transactions processed using a Stored Credential/Token. This field is used to indicate whether a transaction using a stored credential/token is a cardholder-initiated transaction or a merchant-initiated transaction. A cardholder-initiated transaction is any transaction where the cardholder is actively participating in the transaction. A merchant-initiated transaction is any transaction where the cardholder is not actively participating in the transaction. Values: C M ‘C’ - cardholder-initiated transaction ‘M’ - merchant-initiated transaction Default: C If this field is omitted then default value of ‘C’ will be used if a Stored Credential/Token is being used for transaction processing.
L2	600 bytes max, alphanumeric + spaces + symbols Optional for: SFRC	Level 2 DATA Level 2 credit charge information. Level 2 data fields separated by the pipe character (“|”). Level 2 data contains more information about the purchase being made. Please see the layout in the Enhanced Data Submission section for a breakdown of the format. Level 2 data is submitted in the same transaction as the credit card charge information. This may be a Sale, a Force Post, a Return, or a Completion transaction.
L3	600 bytes max, alphanumeric + spaces + symbols Required for: L	LEVEL 3 DATA Level 3 line item detail submission transaction. Level 3 data contains detailed information about the transaction’s individual invoice line items. Each Level 3 transaction contains one detail line item associated with a previous Level 2 data bearing transaction. There can be up to 999 Level 3 line items for each Level 2 data bearing transaction. Each line item is sent as a separate transaction and is matched to the appropriate Level 2 data at deposit time. Level 3 data is submitted after a successful authorization. The terminal ID, unique identifier (UID) and reference number must match the original transaction or the Level 3 data will not be accepted. See the section Level 3 Data Format for field format and rules.
OPERID	3 bytes, alphanumeric Optional for: All	OPERATOR ID The operator ID is a container within the terminal ID. Usually “001” or unspecified (empty). Defaults to “001” if unspecified. The operator ID is 3 characters, alphanumeric. An operator ID is created by its first use. Sending a transaction with operator “01A” will cause that operator to be created. If the operator ID is omitted, the default is “001”. For terminal IDs which Payroc automatically settles nightly, operator rotation is performed. Operator rotation is where Payroc automatically switches the operator ID for each day of the week. For Sunday, operator “001” is used, Monday is “002”, and so on. Using this system, transaction processing days can be isolated for reporting and corrections. Since operator “003” is only used for Wednesday, problems with Wednesday’s transactions will not interfere with Thursday’s processing, which will automatically occur on operator “004”. For most Payroc merchants, this field is not sent with the transaction.
PASS	16 bytes max, alphanumeric Optional for: All	PASSWORD For added security, your terminal ID can be set up with a password. This password, if enabled, is required for all transactions to this terminal ID. PASSWORD should not be provided if this feature is not enabled on your terminal ID. If this feature is enabled, you must provide your password for every transaction. All terminal IDs must either come from a fixed IP address or use a password.
PAY_TYPE	1 byte Optional for: SFAP	Detailed Payment Type This field is required for PreAuthorization and Sale transactions processed using a Stored Credential/Token. This field is used to indicate whether a transaction using a stored credential/token is a recurring payment, an unscheduled/ad hoc transaction, a partial shipment, or a resubmission. Partial Shipment: when an agreed amount of goods is ordered and authorized using multiple transactions then the requests need to be flagged as a partial shipment. Example: Merchant checks availability after receiving an order for 5 items and only 3 items are currently available. Merchant submits an authorization request for the 3 available items with detailed_payment_type = P (Partial Shipment). Authorization request is submitted with detailed_payment_type = P when the remaining items become available. Resubmission: A previous attempt to obtain authorization for a transaction has been declined but the issuer’s response does not prohibit the merchant from trying again later. Example: Insufficient Funds response is received for a transaction where authorization retry is allowed. Merchant retries the authorization request with detailed_payment_type = X (Resubmission). Values: R P U X ‘R’ - recurring payment transaction ‘P’ - partial shipment ‘U’ - unscheduled/ad hoc transaction ‘X’ - resubmission Default: U If this field is omitted then default value of ‘U’ will be used if a Stored Credential/Token is being used for transaction processing.
REF	60 bytes max alphanumeric + hyphens and forward slashes (“/”) Required for: SVFRMAPCLW	REFERENCE NUMBER This is a reference ID associated with a transaction. The reference number should be unique in order to facilitate transaction tracking, Voids, and searches. This value MUST be unique if you are sending any Level 3 data. The reference number can be up to 60 characters (alphanumeric with certain other characters allowed) and may not contain spaces. The reference number may contain hyphens (“-“) and slashes (“/”). Certain restrictions may be placed on the reference number depending on your individual situation. Important: If you are going to be processing Completion transactions without supplying the credit card number or a token, the reference number MUST be unique within the past 30 days. Besides card number or token, reference number is the only key with which Payroc can match a Completion back to its corresponding Pre-Authorization. Note: this is not the reference number which appears on the cardholder’s statement. Payroc has no control over the statement reference number.
RESEND	1 byte, “Y” or “N” Optional for: SVFRMAPC+-LW	RESEND FLAG This field indicates whether a transaction has been previously sent, and is used to retrieve the original response. You can set this field to “Y” (uppercase) in order to receive the response to an already submitted transaction within the past 48 hours. If operator rotation is in use you can only receive responses for transactions submitted since midnight on the current day. If Payroc did not receive the original transaction, it will be processed as a new transaction. You may resubmit the transaction as many times as necessary in order to receive your response. Please note that if you have to do this often you may have network problems. Submitting this field with the flag set to “N” will have the same effect as not submitting a “RESEND” field at all. (The default is “N”.) Please note that if the original transaction is not yet finished, the RESEND operation will not work since transactions are only available for the RESEND operation after the response has been sent. This means that you cannot use this to prevent customers from being charged twice when they double-click the SUBMIT button on an e-commerce site.
SCHEDULE_ACTION	10 bytes max, alphanumeric Optional for: N Required if a payment schedule is to be created or updated	SCHEDULE ACTION Valid values are: “ADD” - create/add a payment schedule “UPDATE” - update a payment schedule “DEACTIVATE”-deactivate a payment schedule “REACTIVATE”- reactivate a payment schedule
SCHEDULE_FREQUENCY	2 bytes max, numeric Optional for: N	SCHEDULE FREQUENCY Valid values are 1-12. Default value is “1” if this field is not included in a request. The frequency for the processing of the card payment transactions is set based on the SCHEDULE_TYPE and the value provided for this field. Example: If the request includes “SCHEDULE_TYPE=WEEKLY” and “SCHEDULE_FREQUENCY=2” then payment transactions will be processed every 2 weeks.
SCHEDULE_NUM_PAYMENTS	3 bytes max, numeric Optional for: N Required if a payment schedule is to be created	NUMBER OF PAYMENTS Specifies the number of card payment transactions to be processed. This field is Required If “SCHEDULE_ACTION=UPDATE” and SCHEDULE_START_DATE or SCHEDULE_TYPE are being modified.
SCHEDULE_START_DATE	8 bytes max, numeric Optional for: N Required if a payment schedule is to be created	SCHEDULE START DATE Specifies the date in format YYYYMMDD when the first card payment transaction is to be processed. The schedule start date must be a future date, i.e., payments cannot be scheduled to start on the day when the request is submitted. This field is Required if “SCHEDULE_ACTION=UPDATE” and SCHEDULE_NUM_PAYMENTS or SCHEDULE_TYPE are being modified.
SCHEDULE_TYPE	10 bytes max, alphanumeric Optional for: N Required if a payment schedule is to be created	SCHEDULE TYPE Specifies the interval for the processing of the card payment transactions. Valid values are: “WEEKLY” “MONTHLY” This field is Required if “SCHEDULE_ACTION=UPDATE” and SCHEDULE_START_DATE or SCHEDULE_NUM_PAYMENTS are being modified.
SEQ	3 bytes max, numeric Optional for: L	LEVEL 3 SEQUENCE NUMBER This sequence number is used to preserve the correct ordering of Level 3 invoice line item details. Each Level 2 item can have up to 999 detail (Level 3) entries. Some deposit institutions limit this to 99 entries; please check with Payroc Merchant Services if you are unsure. Typically, this sequence number would start at “001”. If the sequence number is not specified, Level 3 data could appear in an incorrect order on the customer’s statement.
SHOWDUP	1 byte, “Y” or “N” Optional for: SVFRMAPC+-L	SHOW DUPLICATE STATUS This is the show duplicate status flag. If you submit “SHOWDUP=Y”, your transaction response will contain a flag indicating whether this transaction is a duplicate or not. This must be used in conjunction with “RESEND=Y” flag above. The field name returned is called “DUP”. The returned response will contain “DUP=Y” if the transaction was a duplicate, or “DUP=N” if not. “DUP=Y” means that you are being shown a previous transaction response. The transaction is not processed for a second time in either case.
TOKEN	30 bytes max, alphanumeric + some symbols Required for: GN Optional for: JSVFRMAPC+-W 12 bytes is the minimum length for auto-generated Token IDs	TOKEN A unique ID that can be created and used in place of a credit card for future payment processing. For Token Operations (TYPE=G), the token ID value can be specified by the merchant and/or automatically generated by Payroc. A token ID value must be specified for Payment Scheduling transactions (TYPE=N). Characters supported for merchant specified token IDs: 0-9 A-Z : @ | - + / _ , Submitting a TOKEN value containing a “?” specifies that the token ID value is to be generated by Payroc. Token IDs will be generated by Payroc based on configuration parameters chosen by the merchant. See Tokenization section for more information.
TOKEN_ACTION	10 bytes max, alphabetic Required for: G Optional for: N	TOKEN ACTION This field specifies the action that is to be performed for on the token in this transaction for transaction type G. Valid values are “ADD”, “UPDATE”, “DEACTIVATE”, “REACTIVATE”. (no quotation marks are sent) ADD: Used to add/create the token UPDATE: Used to modify credit card number, expiry, reference data, or dates associated with a token DEACTIVATE: Used to deactivate the token. Tokens which are deactivated will be deleted after 1 year REACTIVATE: Used to reactivate the token See Token Transactions in Real-Time Transaction Examples section for a walk-through of token use.
TOKEN_CLIENT_ID	30 bytes max, alphanumeric + some symbols. Optional for: G	TOKEN CLIENT ID This field can be used to include additional reference data with a token such as a client identifier. Allowed characters: A-Z a-z 0-9 - _ . @ /
TOKEN_START	Optional for: G	TOKEN START DATE The effective start date for the token. This token will not be accepted for payments before this date. This date is specified in the format YYYYMMDD. Example: “20140926”
TOKEN_END	Optional for: G	TOKEN END DATE The effective end date for the token. This token will not be accepted for payments after this date. This date is specified in the format YYYYMMDD. Example: “20161215”
TOKEN_REF	30 bytes max, alphanumeric + symbols Optional for: G	TOKEN REFERENCE DATA Reference data to associate with a token. Allowed characters: A-Z a-z 0-9 - / \
TRACK	79 bytes max, alphanumeric + symbols Optional for: SVFRMAPC	TRACK 1 OR 2 DATA If you are not sure which magnetic track you are reading from the card, you may send it in this field. Our system will identify the correct track type and use it. See section Real-Time Magnetic Card Track Data Field Formats for additional details.
TRACK1	79 bytes max, alphanumeric + symbols Optional for: SVFRMAPC	TRACK 1 DATA Unaltered track 1 data from the card magnetic stripe. CARD and EXP fields should be omitted if TRACK1 is sent. See section Real-Time Magnetic Card Track Data Field Formats for additional details.
TRACK2	37 bytes max, alphanumeric + symbols Optional for: SVFRMAPC	TRACK 2 DATA Unaltered track 2 data from the card magnetic stripe. CARD and EXP fields should be omitted if TRACK2 is sent. See section Real-Time Magnetic Card Track Data Field Formats for additional details.
TYPE	1 byte, alphabetic Required for: All	TRANSACTION TYPE This is the kind of transaction you are performing. See the Real-Time Transaction Types section for values.
UID	7 bytes, alphanumeric Required for: L	Level 2/Level 3 UNIQUE IDENTIFIER This is a unique identifier returned in the response when you submit a Level 2 enhanced data transaction with a commercial card. You must include this field when submitting details (Level 3 Detail Submission or Type L transaction). This field is used to match the Level 2 and Level 3 data at the credit card issuing institution.

Real-Time Transaction Response Fields

All transactions return a TEXT and a CODE field. Other response fields may be returned depending on the type of transaction submitted. The CODE response field contains a 4-digit result code of “0000” for successful transactions, and non-“0000” for transactions that were not successful. Some non-card-charging transactions return non-“0000” return codes for various types of replies that do not necessarily indicate failure.

See section Real-Time Transaction Response Text and Return Codes for a list of CODE values generated by Payroc.

Response Field	Description
TEXT	RETURN TEXT This is the response text of the message. Historically this is what would appear on the screen or printout of a credit card terminal. The authorization number and amount are displayed here on an approval-type transaction. For errors and decline responses this field contains the error message or decline message. All transaction responses contain a TEXT field. The message may include a two character response code. See section Card Payment Response Codes for a list of values returned from MasterCard or Visa
CODE	RESPONSE CODE This is the 4-digit response code from the transaction. “0000” constitutes a successful transaction, and any other 4-digit code constitutes a failure. (see the note above this table for additional information) This code should be used to check for authorization successes (“0000”), decline conditions (“0001”-“1299”), and error conditions (“8000”-“9999”). All transaction responses contain a CODE field.
AUTH	AUTHORIZATION NUMBER This field provides the authorization number for transaction types such as Sale, Pre-Authorization, Completion, Force Post, Authorization Only.
UID	COMMERCIAL CARD TRANSACTION UNIQUE IDENTIFIER When a financial transaction with Level 2 data is sent and the card presented is a commercial card, a unique identifier will be returned in this field. You must include this UID in any subsequent details (Level 3 Detail Submission, transaction type L) to be delivered for this transaction.
AVS	ADDRESS VERIFICATION RESULT CODE For transactions where AVS is used, this field returns the AVS result code. This code is a 1-character response indicating the closeness of the address match. See the AVS Result Codes section for values.
ECHO	ECHO DATA If you submitted a transaction with the ECHO field, this field will be present in the reply and will contain the exact data you placed in the ECHO field of the transaction.
DUP	DUPLICATE TRANSACTION INDICATOR If you submitted a transaction with “SHOWDUP=Y”, you will receive this field in your response. If you submitted “RESEND=Y” with the transaction and it was a duplicate, you will receive “DUP=Y”. This means that the transaction response from a previous transaction is being sent to you. The transaction is not processed twice; you are re-receiving your original transaction response. “DUP=N” in the reply means that this is the first time Payroc has seen your transaction.
TOKEN	TOKEN If a Token is generated by Payroc then the Token ID value will be returned in this field.
CTYPE	CARD TYPE If “EXT_RESP=Y” was submitted with the transaction request then the card type will be returned in this field. Card type values are: INVL - Invalid AMEX - American Express DISC - Discover JCB MCRD - MasterCard VISA
CPROD	CARD PRODUCT If “EXT_RESP=Y” was submitted with the transaction request then the card product will be returned in this field for Visa and MasterCard card types. Card product values are: VC - Visa Credit VD - Visa Debit VB - Visa Business/Commercial MC - MasterCard Credit MD - MasterCard Debit MB - MasterCard Business/Commercial
CCO	CARD COUNTRY OF ORIGIN If “EXT_RESP=Y” was submitted with the transaction request then the card country of origin may be returned in this field. Numeric country code will be returned as defined in ISO 3166-1 indicating the country where the card was issued.
CVV2	CARD SECURITY CODE (CSC) RESULT For transactions where CVV2 and EXT_RESP request fields were included, this field returns the CSC result code. This code is a 1-letter response indicating the result of the CSC authentication request. See the Result Codes section in Card Security Code (CSC) Authentication section for values.
RESP_TYPE	RESPONSE TYPE If “EXT_RESP=Y” was submitted with the transaction request then one of the following response type values may be returned: D - Decline N - Network Failure E - Error/Reject Response Type will not be returned if the transaction is approved.
LAST4	LAST 4 DIGITS OF CARD NUMBER If “EXT_RESP=Y” was submitted with the transaction request then the last 4 digits of the card number may be returned in the response.

Real-Time Transaction Response Text and Return Codes

Successful Transaction

A code of “0000” indicates a successful transaction.

Depending on the transaction type the return text may vary. See table below:

Transaction Type	Response Text and Explanation
Account Status Inquiry	The TEXT field contains spaces followed by an amount of 0.00 as no authorization code is returned for Account Status Inquiry transactions. Example: $0.00
Sale, Force Post, Pre-Authorization, Completion, Authorization Only	The TEXT field contains the authorization number followed by the value of the transaction. The Completion authorization number will be the one obtained during the corresponding Pre-Authorization Example: R02564 $8.99
Return	The TEXT contains the word “RETURN” followed by the value of the transaction. Example: RETURN $8.99
Void	The TEXT field contains the text “VOID OK”
Return Void	The TEXT field contains the text “MRVOID OK”
Balance Request	The TEXT field contains the total batch amount, individual card total amounts, and total number of depositable transactions for each card type. Pre-Authorization and Authorization Only transactions are not included in the totals since they are not depositable. The amounts shown are the amounts that would be settled for deposit if you were to perform a Settlement transaction at that instant on that operator ID. Please note that the card types are listed in alphabetical order. Also note that only 3 digits are available for the transaction counts, so if more than 999 transactions are sent you will only see the least significant 3 digits of the count. Similarly, amounts over 99,999.99 may lose leading digits. Totals are unaffected, and the system does not lose any transactions. The reason for this is that the Balance Request results historically needed to fit onto a small display, and some legacy devices may remain. The response message looks like this: “TOTL <total_all>, <type1> <count> <$amount>, <type2> <count> <$amount> ..” Example: TOTL $4.20 ,AMEX 0 $0.00 ,MCRD 1 $2.00 ,VISA 1 $2.20
Settlement	Settlements return a TEXT field containing the text “SETTLED” followed by the value of the settlement. Example: SETTLED $1643.21
Contra Add	The TEXT field contains the text “CARD ADDED” if the card was added, or “ALREADY PRESENT” if the card was already present in the Contra table.
Contra Delete	TEXT field contains the text “CARD DELETED”. The card is removed from Payroc’s Contra table for this merchant.
Contra Query	TEXT field contains the text “PRESENT” if the card was found in the Contra table, and “NOT PRESENT” if the card was not found.
Level 3 Detail Submission	TEXT field contains the text “DETAILS DELIVERED”. The Level 3 data will be included in the deposit information for this transaction.
Token Action	TEXT field contains the text “TOKEN ADDED”, “TOKEN MODIFIED”, “TOKEN DEACTIVATED” OR “TOKEN REACTIVATED” depending on the operation specified. TEXT may also contain error messages if fields are not correctly specified.
Payment Scheduling	TEXT field contains the text “SCHEDULE ADDED”, “SCHEDULE UPDATED”, “SCHEDULE DEACTIVATED”, or “SCHEDULE REACTIVATED” depending on the action specified.

Unsuccessful Transaction

These are the codes and response text for non-successful or negative-type responses to transaction requests.

Code	Response Text and Explanation
0001-1299	Decline messages from various financial institutions. Text may not be constant for a particular return code. Hard-coding of actions based on any of these values is strongly discouraged.
1000	MALFORMED TRANS Some data in the transaction was missing or invalid, or the reference number was too long.
1001	ACCESS DENIED or TOTL DENIED Your terminal ID is not activated or you do not have permission to use it from this IP address.
1002	UNSUPPORTED TRANS The transaction type you submitted is not supported, or is not supported for your merchant setup.
1003	DECLINED (CV) Transaction declined by Payroc card velocity tracking system. This card has been used more than the preset limit for this terminal ID allows.
1004	DECLINED (MV) Transaction declined by Payroc merchant velocity system. This merchant has exceeded their preset transaction volume limits.
1005	DECLINED (CL) Transaction declined by Payroc card limiting system. The amount of money charged to this card has exceeded preset limits.
1006	DECLINED (ML) Transaction declined by Payroc merchant limiting system. The amount of money charged on this terminal ID has exceeded preset limits.
1007	DECLINED (DUP) This terminal ID is using Payroc’s duplicate elimination system and the transaction has already been processed within the preset time.
1008	DECLINED (CONTRA) This terminal ID is using the Payroc contra checking system and the card is in the Contra table. (unwelcome)
1010	ILLEGAL CHAR The transaction request message contained one or more illegal characters. Please make sure you are following the specifications.
1011	ILLEGAL AMOUNT The amount you entered is not valid.
1012	NOT PRESENT The card you are querying is not in the Contra table. (Contra Query transaction only)
1013	CARD VERIFY FAIL CSC and/or AVS authentication failed. The token operation (Token Add or Update) was not executed due to the authentication failure.
1014	NOT FOUND The card you are attempting to delete from the Contra table is not present in the table. (Contra Query transaction only)
1015	MRV NO MATCH There is no matching Return for the Return Void you are attempting.
1016	COMPLETION NO MATCH There is no matching Pre-Authorization for the Completion you are attempting.
1017	NO MATCH There is no matching Sale, Completion, or Force Post for the Void you are attempting.
1018	CARD TYPE INVALID You are trying to process a card type which you are not set up for, or the card you are trying to process is not a valid type.
1019	TRAN TYPE INVALID You are trying to use a transaction type which you are not set up for, or you are trying to use a transaction type which does not exist.
1020	CARD NUMBER INVALID The card number did not pass check-digit test for that card type.
1021	EOT RECEIVED An upstream processor has disconnected. Retrying the transaction is recommended.
1022	LEVEL 2 LENGTH ERR You have sent too much Level 2 data. Resend your transaction with less than 600 characters of Level 2 data.
1023 1024 1025	NETWORK FAILURE These error codes indicate a communications failure in the authorization network. The transaction was neither approved nor declined.
1026	AVS DATA INVALID The AVS data you entered contained invalid or unrecognized data.
1028	OPERATOR INVALID The Operator ID you submitted contained something other than letters and numbers. (Operator IDs are 3 digits, alphanumeric)
1029	AUTH NUMBER MISSING You have submitted a Force Post transaction without an authorization number.
1030	CARD LENGTH ERR The card number you submitted did not contain the correct number of digits for that card type.
1031	VISA DEBIT FORBIDDEN Visa Debit is not permitted on this Terminal ID.
1032	INVALID TOKEN EXPIRY The expiry date has either expired or is not in the correct format (MMYY).
1050	UID MISSING No Unique Identifier (UID) was sent with a Level 3 Detail Submission (type L) transaction. Details not captured.
1051	NO MATCH Unique Identifier (UID) was not found in UID database. The Level 2 transaction must be sent first, and UID must be included with a Level 3 Detail Submission (type L) transaction.
1052	LEVEL 2 FORBIDDEN This terminal ID is not set up to handle Level 2 enhanced data transactions. Please contact our Merchant Services department for assistance.
1053	LEVEL 2 FORMAT ERR or L2 ERR FLDS: *x,y,z* You have sent a Level 2 transaction with an incorrect number of fields (FORMAT ERR) or incorrect field data (L2 ERR FLDS). Only version PC2.20 or higher Level 2 data is checked for field contents. Earlier levels are checked for number of fields only. If you are using PC2.20 or higher, x,y, and z in the above message are replaced with field numbers where errors have been detected. Up to 3 errors per Level 2 data submission will be returned at a time. Your transaction’s regular financial authorization will not be performed if you send invalid Level 2 data.
1054	LEVEL 3 FORMAT ERR You have sent a Level 3 Detail Submission (type L) transaction with an incorrect number of fields.
1055	MAX AMOUNT EXCEEDED Your terminal ID has a maximum amount per transaction limit set, and this transaction exceeds that amount.
1056	LEVEL 3 MISSING You are attempting to send a type “L” (Level 3 Detail Submission) transaction without any Level 3 field data.
1057	AIR FORMAT ERROR or AIR ERR FLDS: *x,y,z* “AIR FORMAT ERROR” means that you have sent Air Travel Data with an incorrect number of fields. “AIR ERR FLDS: x,y,x” indicates that you have errors in your field data. x,y, and z are replaced with the field numbers which are incorrect. (e.g. “AIR ERR FLDS: 3,5,6”) Please correct the errors and resubmit. Your transaction’s regular financial authorization will not be performed if you send invalid AIR data.
1066	DECLINE - ACQUIRER Acquirer rules forbid us from capturing this transaction.
1080	NON-COMMERCIAL The card number submitted is NOT a commercial card (transaction type “K” only)
1088	TRANS ABORTED The authorization network has disconnected.
1099	NETWORK FAILURE A network failure has occurred while communicating with the card issuer.
1100	INVALID TOKEN ACTION An invalid token action was specified.
1101	TOKEN NOT FOUND The token sent with the transaction was not found in our token vault.
1102	TOKEN ALREADY EXISTS The token sent is already in use.
1103	TOKEN NOT ACTIVE The token is in the token vault, but is marked as inactive.
1104	TOKEN SUSPENDED The token is in the token vault, but it is marked as suspended.
1105	TOKEN SETUP ERROR There is a problem with your terminal ID’s tokenization setup. Please contact Payroc Merchant Services.
1106	BAD END DATE A token was sent with an end date that was not in the correct format, or was invalid.
1107	BAD START DATE A token was sent with a start date that was not in the correct format, or was invalid.
1108	END DATE PAST A token was sent with an end date that has already passed.
1109	DATE SEQ ERROR A token was sent with an end date that occurs before the start date.
1110	PAN UPDATE FORBIDDEN Card number cannot be updated for auto-generated Token IDs that include the card type and/or last four digits of the card number.
1111	TOKEN SETUP ERR Terminal ID is not setup to use tokens or the setup is incomplete. Please contact Payroc Merchant Services department for assistance.
1112	TOKEN NO CONFIG Tokenization services are currently not available. Please contact Payroc Merchant Services department if this condition persists.
1113	TOKEN CONFIG ERROR Tokenization services are currently not available. Please contact Payroc Merchant Services department if this condition persists.
1114	AUTO TOKEN FMT ERR Auto-generated Token ID creation failed as the length is invalid.
1115	AUTO TOKEN FORBIDDEN Merchant and associated Terminal IDs are not configured to allow the use of auto-generated Token IDs. Please contact Payroc Merchant Services department for assistance.
1116	TOKEN NETWORK ERROR Tokenization services are currently not available. Please contact Payroc Merchant Services department if this condition persists.
1118	TOKEN PENDING The Token is not yet available for use as the start date is setup with a future date.
1119	TOKEN EXPIRED The Token is no longer available for use as the end date has been passed.

Response Codes

These are the response code values returned from MasterCard or Visa for non-successful or negative-type transaction requests.

MasterCard

Response Code	Description
01	Refer to card issuer
03	Invalid merchant
04	Capture card
05	Do not honor
08	Honor with ID
10	Partial Approval
12	Invalid transaction
13	Invalid amount
14	Invalid card number
15	Invalid issuer
30	Format error
41	Lost card
43	Stolen card
51	Insufficient funds/overcredit limit
54	Expired card
55	Invalid PIN
57	Transaction not permitted to issuer/cardholder
58	Transaction not permitted to acquirer/terminal
61	Exceeds withdrawal amount limit
62	Restricted card
63	Security violation
65	Exceeds withdrawal count limit OR Identity CheckSoft-Decline of EMV 3DS Authentication (merchantshould resubmit authentication with3DSv1)
70	Contact Card Issuer
71	PIN Not Changed
75	Allowable number of PIN tries exceeded
76	Invalid/nonexistent “ToAccount” specified
77	Invalid/nonexistent “FromAccount” specified
78	Invalid/nonexistent account specified (general)
81	Domestic Debit Transaction Not Allowed (Regional use only)
84	Invalid Authorization Life Cycle
85	Not declined valid for all zero amount transactions
86	PIN Validation not possible
87	Purchase Amount Only, No Cash Back Allowed
88	Cryptographic failure
89	Unacceptable PIN—Transaction Declined—Retry
91	Authorization System or issuer system inoperative
92	Unable to route transaction
94	Duplicate transmission detected
96	System error

Visa

Category 1 (Issuer will not approve)

Response Code	Description
03	Invalid merchant or service provider
04	Pick up card
07	Pickup card, special condition (other than lost/stolen card)
12	Invalid transaction
15	No such issuer
41	Lost card, pick up (fraud account)
43	Stolen card, pick up (fraud account)
46	Closed account
57	Transaction not permitted to cardholder
62	Restricted card (for instance, in Country Exclusion table)
93	Transaction cannot bec ompleted; violation of law
R0	Stop payment order
R1	Revocation of authorization order
R3	Revocation of all authorizations order

Category 2 (Issuer cannot approve at this time)

Response Code	Description
19	Re-enter transaction
51	Insufficient funds
59	Suspected fraud
61	Exceeds approval amount limits
65	Exceeds withdrawal frequency limit
75	Allowable number of PIN-entry tries exceeded
78	Blocked, first used or special condition -new cardholder not activated or card is temprarily blocked
86	Cannot verify PIN
91	Issuer unavailable or switch inoperative (STIP notapplicable or available for this transaction) Issuers can respond with this code, which V.I.P. passes to the acquirer without invoking stand-in processing(STIP). Issuer processors use the code to indicate they cannot perform authorization on issuers’ behalf. Code causes decline at POS.
96	System malfunction
N3	Cash service not available
N4	Cashback request exceeds issuer limit

Category 3 (Data quality issues)

Response Code	Description
14	Invalid account number (no such number)
1A	Additional customer authentication required (In the Europe Region)
54	Expired card
55	Incorrect PIN
6P	Verification data failed
70	PIN data required (In the Europe Region)
82	Negative online CAM, dCVV, iCVV, CVV, or CAVV results Or Offline PIN authentication interrupted
N7	Decline for CVV2 failure

Category 4 (Generic response codes)

Response Code	Description
01	Refer to card issuer
02	Refer to card issuer, special condition
05	Do not honor
06	Error
10	Partial approval
11	V.I.P. approval
13	Invalid amount (currency conversion field overflow) or amount exceeds maximum for card program
39	No credit account
52	No checking account
53	No savings account, Transaction not allowed at terminal
77	Previous message located for a repeat or reversal but repeat or reversal data inconsistent with original message
80	Visa transactions: credit issuer unavailable. Private label: invalid date
85	No reason to decline request for account number verification, address verification, CVV2 verification, or credit voucher or merchandise return
1A	Additional customer authentication required
N0	Force STIP
P2	Invalid biller information
P5	PIN change/unblock request declined
P6	Unsafe PIN
Z1	Offline-declined
Z3	Unable to go online; offline-declined

Real-Time Enhanced Data Processing

Tables are included below which provide field level details for the current version of Level 2 (Invoice Header) and Level 3 (Invoice Line Item) data.

Level 2 & 3 data fields are pipe-delimited and do not include the field names. Optional fields may be left empty but the field delimiter (“|”) must still be present.

Padding is not required, as variable length data is supported. Field sizes are maximum lengths unless otherwise specified.

Fields cannot contain all spaces or all zeroes unless specified in the Notes column. If an ampersand needs to be passed for a field then two ampersands (“&&”) must be included. Pipe (“|”) character cannot be included in any field values since it is used as a field delimiter.

Level 2 Data Format

#	Field Name	Description	Length	Type	Notes
1	Version Number	Indicates format of Level 2 data	6	A/N	Value of “PC3.02” must be used to specify the version of Level 2 data described in this table.
2	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
3	Not Used	Previously used for Transaction Type
4	Customer Name	Name of the customer who placed the order	0-40	ASCII Print-able	Amex Used for cardholder’s name
5	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.
6	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.
7	Not Used	Previously used for Credit Card Number OR Token
8	Not Used	Previously used for Expiry Date
9	Not Used	Previously used for Authorization Number
10	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.
11	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
12	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.
13	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
14	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.
15	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.
16	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.
17	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
18	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.
19	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.
20	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
21	Merchant PST/QST Registration Number	Merchant’s Provincial Sales Tax registration number.	30	ASCII Print-able	Visa & Amex Required if QST applies
22	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
23	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
24	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
25	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
26	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
27	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
28	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
29	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
30	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
31	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.
32	Customer Reference	Cardholder’s reference data	17	ASCII Print-able	Amex Can include client specific accounting information
33	Not Used	Previously used for Customer Number
34	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
35	“Ship to:” Name	“Ship to:” name	40	ASCII Print-able
36	“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
37	“Ship to:” Address	“Ship to:” address line 2	40	ASCII Print-able
38	“Ship to:” City	“Ship to:” city	30	ASCII Print-able	Amex Required if a value has been provided for field #35 Ship To Name
39	“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
40	“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
41	“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 35 -41 are only supported if the country is Canada or U.S.

Level 3 Data Format

#	Field Name	Description	Length	Type	Notes
1	Version Number	Indicates format of Level 3 data	6	A/N	Value of “PC3.03” must be used to specify the version of Level 3 data described in this table.
2	Transaction Reference Number	Unique transaction ID assigned by the merchant. Previously named Invoice Number	15	A/N
3	Product Code	Merchant’s SKU number for the item being sold/returned. Field was previously named Item SKU	12	ASCII Print-able
4	Item Description	Merchant’s description of the item being sold/returned.	26	ASCII Print-able
5	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
6	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
7	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
8	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
9	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
10	Not Used	Previously used for PST Status
11	Not Used	Previously used for GST Status
12	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
13	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
14	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
15	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
16	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
17	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
18	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
19	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
20	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
21	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
22	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
23	Manufacturer SKU Number	Manufacturer’s stock number for item being sold/returned.	30	ASCII Print-able
24	Customer SKU Number	Customer’s stock number for item being sold/returned.	30	ASCII Print-able
25	Customer PO	Customer purchase order number for specific item.	22	ASCII Print-able
26	Supplementary Data/Order Number	This field may contain a free form product or service description for the line item.	40	ASCII Print-able
27	GL Account Number	This field may contain the general ledger account number for the item/service purchased.	40	ASCII Print-able
28	Division Number	This field may contain the division number of the card member who purchased the item or service.	40	ASCII Print-able
29	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 Data Format (Airline)

This is the Level 2 component of a transaction with Air Travel Data. This is sent in the L2 field. Air Travel Data is sent in the separate AIR field.

#	Field Name	Length	Type	Req	Description
1	Version Number	6	A/N	Y	Indicates format of data following. Use “PC2.20” for the version of Level 2 Air Travel Data described in this document.
2	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%.
3	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%.
4	PST Amount	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.
5	GST Amount	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.
6	Merchant PST Registration Number	15	A/N	N	Merchant’s Provincial Sales Tax registration number.
7	Merchant GST/HST Registration Number	15	A/N	N	Merchant’s GST or HST registration number.
8	Cardholder GST/HST Registration Number	15	A/N	N	Customer’s GST or HST registration number.
9	Cardholder PO Number	17	A/N	N	Identifier provided by the customer such as purchase order number or job number.

Air Travel Data

This is airline transaction specific enhanced data. It allows air travel-related details to be passed for inclusion on commercial card statements. This data is passed in the AIR field, and may accompany Level 2 airline data which is passed in the L2 field.

#	Field Name	Length	Type	Req	Description
1	Version Number	6	A/N	Y	Indicates format of data following. Use “AIR-01” for the version of Air Travel Data described in this document.
2	Passenger Name	20	A/N	Y	Name of the passenger in the format SURNAME/GIVEN NAME. e.g. SMITH/JOHN
3	PNR Locator	18	A/N	N	Passenger name record (PNR)
4	Ticket Identifier	14	N	N	Passenger’s ticket number
5	Routing	36	A/N	N	Routing information for a maximum of 9 segments can be included on the cardholder’s statement. 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
6	Departure Date	8	N	N	Departure date in format YYYYMMDD
7	Carrier Code	18	A/N	N	2 character carrier code for each of up to 9 flight segments. Example: ACAADLCO
8	Carrier Name	20	A/N	N	Carrier/supplier name

• All Air Travel and Level 2 data fields must be separated by a pipe character: | (hex 7C)
• For US merchants, state, country, and civic taxes are combined into a “local tax”.
• Padding is not required, as variable length data is supported. Field sizes are maximum lengths unless otherwise specified.
• If is necessary to include an ampersand in a field, you must send two ampersands (“&&”). All characters entered must be ASCII 7-bit. No characters with ASCII values less than 32 decimal (space) or greater than 126 decimal are allowed.

Real-Time Magnetic Card Track Data Field Formats

Sending Track 1 Or Track 2 Data

When processing transactions where the card information is read by a magnetic swipe reader, there is no need to submit the “CARD” and “EXP” fields, since these are embedded in the card swipe data.

Credit cards typically contain two magnetic “tracks” of data: track 1 and track 2. It is possible to submit either track 1 or track 2 data for authorizations. Only one track should be submitted per transaction.

Sending Track 1

Track 1 data is variable length, with a maximum length of 79 characters. In order to submit this track, you must first remove the framing characters (start/end sentinels and LRC character).

The separators should be converted to “^” (hex 5E) or the ASCII Unit Separator character (hex 1F) prior to sending, but most card readers will do this automatically.

To send track 1 data, you must include a “TRACK1” tag in your transaction.

Track 1 Data Example
TRACK1=B400000000000*********7659^PRESLEY/GREGORY^0308101000000001000100640000000

Sending Track 2

Track 2 data is variable length, with a maximum of 37 characters. In order to submit this track, you must first remove the framing characters (start/end sentinels and LRC character). The separators must be converted to “=” (hex 3D) or “D” (hex 44) prior to sending, but most card readers will do this automatically.

To send track 2 data, you must include a “TRACK2” field in your transaction.

Track 2 Data Example
TRACK2=4000000000007659=03081010000064010001

Since card readers often send one track without the other for various reasons, it is also possible to send track 1 or track 2 without knowing which one you’re sending. Simply specify “TRACK” as the data field, as opposed to “TRACK1” or “TRACK2”. Our system will automatically determine which track was sent.

Unknown Track Type Example 1
TRACK=B4000000000007659^PRESLEY/GREGORY^0308101000000001000100640000000

Unknown Track Type Example 2
TRACK=4000000000007659=03081010000064010001

Real-Time Testing Amounts and Return Codes

If you are using a test terminal ID, varying the amount in the transaction will cause various responses and behaviours. The table below details each test expiry date.

Amount	Return Code	Response Text
0909	None	None. Connection will be dropped immediately to simulate a network problem.
1010	0000	Response will be a transaction approval, but the transaction response will be delayed by 20 seconds. This is useful for testing some types of timeout conditions.
2101	1285	CARD OK
2102	1201	CALL
2103	1202	CALL
2104	1228	NO REPLY
2105	1291	NO REPLY
2106	1204	PICK UP CARD
2107	1207	HOLD-CALL
2108	1241	PICK UP CARD
2109	1243	HOLD-CALL
2110	1299	ACCT LENGTH ERR
2111	1213	AMOUNT INVLD
2112	1214	CARD NO. INVLD
2201	1299	CHECK DIGIT ERR
2202	1299	CID FORMAT INVLD
2203	1280	DATE INVLD
2204	1205	DECLINE
2205	1251	DECLINE
2206	1299	DECLINE
2207	1261	DECLINE
2208	1262	DECLINE
2209	1265	DECLINE
2210	1293	DECLINE
2211	1254	EXPIRED CARD
2212	1292	INVALID ROUTING
2301	1212	INVALID TRANS
2302	1278	NO ACCOUNT
2303	1221	NO ACTION TAKEN
2304	1215	NO SUCH ISSUER
2305	1219	RE ENTER
2306	1263	SEC VIOLATION
2307	1257	SERV NOT ALLOWED
2308	1299	CVV2 MISMATCH
2310	0050	DECLINE
2311	0051	PHONE HELP 901
2312	0052	TEL ### ####
2401	0053	PHONE HELP 200
2402	0054	PHONE HELP 097
2403	0055	PHONE HELP 150
2404	0056	PICK UP CARD
2405	0057	HOLD CARD CALL
2406	0058	ERROR ACCOUNT
2407	0059	EXPIRY ERROR
2408	0060	PHONE HELP 055
2409	0061	PHONE HELP 801
2411	0201	TRANSMIT ERROR
2412	0202	INVALID MERCH ID
2501	0204	CALL 05
2502	0205	INV EXPIRY DATE
2503	0206	CARD EXPIRED
2504	0207	INVALID MERCH ID
2505	0208	INVALID AUTH CODE
2506	0210	LOST/STOLEN
2507	0216	CALL AUTH CENTRE
2508	0218	CALL AUTH CENTRE
2509	0219	CALL AUTH CENTRE
2510	0220	INV MSG TYPE
2511	0221	CALL AUTH CENTRE
2512	0222	CALL AUTH CENTRE
2601	0224	CALL AUTH CENTRE
2602	0225	CALL AUTH CENTRE
2603	0226	CALL CENTRE ####
2604	0227	CALL AMEX
2605	0228	CALL VOICE CENTRE
2606	0229	INV CARD TYPE
2607	0230	CALL AUTH CENTRE
2608	0231	TELEPHONE
2609	0232	CALL AUTH CENTRE
2610	0233	CALL 03
2611	0234	CALL 04
2701	0290	ERROR UNKNOWN
2702	0291	ERROR 10: FORMAT
2703	0292	ERROR 11: MAPP
2704	0293	ERROR 13: ACCT #
2705	0294	ERROR 15: MERCH
2706	0295	PLEASE RETRY
2708	0351	INVALID TERM ID
2709	0352	INVALID MERCH ID
2710	0354	INVALID OPERATOR
2711	0356	INVALID TRAN NUM
2801	0360	CALL AUTH CENTRE
2802	0362	INVALID TRAN CODE
2803	0363	INVALID ACCOUNT
2804	0364	INVALID TRANS
2805	0365	HOLD/CALL CENTRE
2806	0366	DECLINE
2807	0370	INSTIT NOT FOUND
2808	0373	ERROR - NO MATCH
2809	0374	DECL - HOLD CARD
2810	0375	HOLD/CALL CENTRE
2811	0376	HOLD/CALL CENTRE
2812	0377	HOLD/CALL CENTRE
3601	0378	CARD EXPIRED
3602	0379	DECLINED EXPIRED
3603	0410	INVALID LICENCE
3604	0420	ACCOUNT FROZEN
3605	0440	LIMIT EXCEEDED
3606	0443	DECLINE/CALL CS
3607	0451	EXCESS ACTIVITY
3608	0452	DO NOT ACCEPT
3610	0605	INVALID AMOUNT
3612	8001	EXPIRY INVALID
3710	1210	PARTIAL APPROVAL

Real-Time Transaction Examples

The following are some examples of various transaction scenarios. Terminal ID “EXAMPLE1” was used for these transactions.

Sale Transaction

In this example we will process a Sale for $49.95, which will authorize and capture the details for settlement. We will also add a unique custom description to appear on the cardholder’s statement. The Sale transaction is the most commonly used transaction for charging credit cards.

Field Name	Value
TERMID	EXAMPLE1
TYPE	S
CARD	5191111111111111
EXP	1214
AMT	4995
REF	SALE01
DESC	ABC CO 659857458856

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=S&CARD=5191111111111111&EXP=1214&AMT=4995&REF=SALE01&DESC=ABC CO 659857458856

Response:
TEXT=T84457 $49.95&AUTH=T84457&CODE=0000

Sale Transaction with Extended Response data

In these examples we will process Sale transactions for $39.95 with the Extended Response data option turned on. Examples are provided for approved and rejected transactions as the response fields returned would vary based on the validation/authorization results.

Approved Sale

Field Name	Value
TERMID	EXAMPLE1
TYPE	S
CARD	5550000000000003
EXP	1214
AMT	3995
REF	SALE01
EXT_RESP	Y

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=S&CARD=5550000000000003&EXP=1214&AMT=3995&REF=SALE01&EXT_RESP=Y

Response:
TEXT=T84457 $39.95&AUTH=T84457&CODE=0000&CTYPE=MCRD&CPROD=MC&CCO=124

Rejected Sale

Field Name	Value
TERMID	EXAMPLE1
TYPE	S
CARD	819111111111111
EXP	1214
AMT	3995
REF	SALE01
EXT_RESP	Y

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=S&CARD=819111111111111&EXP=1214&AMT=3995&REF=SALE01&EXT_RESP=Y

Response:
TEXT=CARD NUMBER INVALID&CODE=1020&CTYPE=INVL&RESP_TYPE=E

Balance Request Transaction

In this example we will perform a Balance Request, which will request totals prior to settling the batch.

Field Name	Value
TERMID	EXAMPLE1
TYPE	B

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=B

Response:
TEXT=TOTL $149.95 ,AMEX 0 $0.00 ,MCRD 1 $49.95 ,VISA 1 $100.00 &CODE=0000

The totals indicate that there is one Visa transaction for $100.00, and one MasterCard transaction for $49.95, for a total of $149.95.

Settlement Transaction

In this example we will perform a Settlement transaction, to close this batch and let Payroc know that we would like to deposit the money into our merchant account.

Field Name	Value
TERMID	EXAMPLE1
TYPE	D

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=D

Response:
TEXT=SETTLED $149.95&CODE=0000

The settlement results indicate that $149.95 will be deposited into the merchant’s account for this batch.

Authorization Only Transaction

A. Authorization Only Transaction For $10.00

Field Name	Value
TERMID	EXAMPLE1
TYPE	A
CARD	5191111111111111
EXP	1214
AMT	1000
REF	1234

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=A&CARD=5191111111111111&EXP=1214&AMT=1000&REF=1234

Response:
TEXT=054935 $10.00&AUTH=054935&CODE=0000

B. Authorization Only Transaction Using The Resend Flag

For this example, suppose that the response was not received for above transaction, and we would like to see the transaction results. This is where the RESEND flag is used. The original transaction results will be re-sent if the transaction has already been processed at Payroc. If the transaction has not been processed, it will now be processed. (note “RESEND” flag)

Field Name	Value
TERMID	EXAMPLE1
TYPE	A
CARD	5191111111111111
EXP	1214
AMT	1000
REF	1234
RESEND	Y

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=A&CARD=5191111111111111&EXP=1214&AMT=1000&REF=1234&RESEND=Y

Response:
TEXT=054935 $10.00&AUTH=054935&CODE=0000

C. Authorization Only Transaction Using An Expired Card

For this example, an authorization attempt is going to be processed on an expired card. Note the decline response.

Field Name	Value
TERMID	EXAMPLE1
TYPE	A
CARD	5191111111111111
EXP	0404
AMT	1000
REF	1234

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=A&CARD=5191111111111111&EXP=0404&AMT=1000&REF=1234

Response:
TEXT=05 DECLINE&CODE=1205

D. Authorization Only Transaction Using An Expired Card And Receiving Different Response

The reason returned in the text field is not always specific. To demonstrate, an expired card from a different bank will be processed and a difference return code will be received.

Field Name	Value
TERMID	EXAMPLE1
TYPE	A
CARD	4506111111111111
EXP	0404
AMT	1000
REF	1234

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=A&CARD=4506111111111111&EXP=0404&AMT=1000&REF=1234

Response:
TEXT=54 EXPIRED CARD &CODE=1254

Force Post Transaction

In this example we will Force Post $10.00 using the authorization number received from the Authorization Only transaction.

Field Name	Value
TERMID	EXAMPLE1
TYPE	F
CARD	5191111111111111
EXP	1214
AMT	1000
REF	FORCEPOSTDEMO
AUTH	054935

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=F&CARD=5191111111111111&EXP=1214&AMT=1000&REF=FORCEPOSTDEMO&AUTH=054935

Response:
TEXT=054935 $10.00&AUTH=054935&CODE=0000

Pre-Authorization Transaction

In this example, we will pre-authorize a charge of $50.00.

Field Name	Value
TERMID	EXAMPLE1
TYPE	P
CARD	5191111111111111
EXP	1214
AMT	5000
REF	PREAUTH1

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=P&CARD=5191111111111111&EXP=1214&AMT=5000&REF=PREAUTH1

Response:
TEXT=T56428 $50.00&AUTH=T56428&CODE=0000

Completion Transaction

A. Completion Without Card

We will now perform a Completion transaction for the Pre-Authorization from the preceding example.

Field Name	Value
TERMID	EXAMPLE1
TYPE	C
CARD	0
EXP	0000
AMT	5000
REF	PREAUTH1

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=C&CARD=0&EXP=0000&AMT=5000&REF=PREAUTH1

Response:
TEXT=T56428 $50.00&AUTH=T56428&CODE=0000

In order to pass validation checks if tokens are not used, a credit card number and expiry date field must be sent. “0” (zero) can be sent for the credit card number field, and “0000” (four zeroes) for the expiry date field. Alternately, you can send the real credit card number and expiry date.

Also note that the authorization number in the Completion transaction was the same as the Pre-Authorization. Payroc maintains your Pre-Authorization information until you complete the transaction, or until the card authorization lifetime expires (22 days for Mastercard, 30 days for Visa, American Express, and others).

B. Completion Transaction For $50.00 That Has Already Been Completed

A subsequent Completion sent for the previous Pre-Authorization will be rejected.

Field Name	Value
TERMID	EXAMPLE1
TYPE	C
CARD	0
EXP	0000
AMT	5000
REF	PREAUTH1

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=C&CARD=0&EXP=0000&AMT=5000&REF=PREAUTH1

Response:
TEXT=COMPLETION NO MATCH &CODE=1016

C. Multiple Completion Transactions

Multiple Completions can be processed for the same Pre-Authorization transaction as long as the dollar amount of the original Pre-Authorization is not exceeded.

1. Pre-Authorization for $100.00

Field Name	Value
TERMID	EXAMPLE1
TYPE	P
CARD	5191111111111111
EXP	1214
AMT	10000
REF	PREAUTH2

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=P&CARD=5191111111111111&EXP=1214&AMT=10000&REF=PREAUTH2

Response:
TEXT=T55094 $100.00&AUTH=T55094&CODE=0000

2. First Completion Transaction For $50.00 Without The Credit Card Number

Continuing example “C. Multiple Completion transactions”…

Field Name	Value
TERMID	EXAMPLE1
TYPE	C
CARD	0
EXP	0000
AMT	5000
REF	PREAUTH2

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=C&CARD=0&EXP=0000&AMT=5000&REF=PREAUTH2

Response:
TEXT=T55094 $50.00&AUTH=T55094&CODE=0000

3. Second Completion Transaction For $50.00 Without The Credit Card Number

Continuing example “C. Multiple Completion transactions”…

Field Name	Value
TERMID	EXAMPLE1
TYPE	C
CARD	0
EXP	0000
AMT	5000
REF	PREAUTH2

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=C&CARD=0&EXP=0000&AMT=5000&REF=PREAUTH2

Response:
TEXT=T55094 $50.00&AUTH=T55094&CODE=0000

4. Third Completion Transaction For $50.00 Without The Credit Card Number.

Continuing example “C. Multiple Completion transactions”…

Any additional Completion attempts using the same reference number will fail because the total Completion amount cannot exceed the original Pre-Authorization amount.

Field Name	Value
TERMID	EXAMPLE1
TYPE	C
CARD	0
EXP	0000
AMT	5000
REF	PREAUTH2

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=C&CARD=0&EXP=0000&AMT=5000&REF=PREAUTH2

Response:
TEXT=COMPLETION NO MATCH &CODE=1016

No currently valid matching Pre-Authorization could be found.

Void Transaction

A. Void Transaction For $50.00 Without The Credit Card Number

In this example we will Void the second Completion transaction for $50.00 from the preceding example. We will not use the credit card number, since it is not required.

Field Name	Value
TERMID	EXAMPLE1
TYPE	V
CARD	0
EXP	0000
AMT	5000
REF	PREAUTH2

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=V&CARD=0&EXP=0000&AMT=5000& REF=PREAUTH2

Response:
TEXT=VOID OK &CODE=0000

B. Second Attempt To Void Completion Transaction For $50.00 Without The Credit Card Number

In this example we will attempt to Void the second Completion transaction for $50.00 from the preceding example without the credit card number. Since we have already voided this transaction, the attempt will fail.

Field Name	Value
TERMID	EXAMPLE1
TYPE	V
CARD	0
EXP	0000
AMT	5000
REF	PREAUTH2

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=V&CARD=0&EXP=0000&AMT=5000& REF=PREAUTH2

Response:
TEXT=NO MATCH &CODE=1017

No current matching voidable transaction was found.

Return Transaction

In this example we will process a refund of $25.00 to the credit card.

Field Name	Value
TERMID	EXAMPLE1
TYPE	R
CARD	5191111111111111
EXP	1214
AMT	2500
REF	RETURNDEMO

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=R&CARD=5191111111111111&EXP=1214&AMT=2500&REF=RETURNDEMO

Response:
TEXT=RETURN $25.00&CODE=0000

Return Void Transaction

A. Void A Return Transaction For $25.00 Without The Credit Card Number

In this example, we will perform a Return Void on the Return transaction from the preceding example. The card number is not required, since the reference number and amount are used for the matching.

Field Name	Value
TERMID	EXAMPLE1
TYPE	M
CARD	0
EXP	0000
AMT	2500
REF	RETURNDEMO

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=M&CARD=0&EXP=0000&AMT=2500&REF=RETURNDEMO

Response:
TEXT=MRVOID OK &CODE=0000

B. Second Request To Void A Return Transaction For $25.00 Without The Credit Card Number

In this example, we will attempt to perform a Return Void on the previous Return transaction which has already has a Return Void performed on it. The attempt will fail.

Field Name	Value
TERMID	EXAMPLE1
TYPE	M
CARD	0
EXP	0000
AMT	2500
REF	RETURNDEMO

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=M&CARD=0&EXP=0000&AMT=2500&REF=RETURNDEMO

Response:
TEXT=MRV NO MATCH &CODE=1015

No current matching transaction eligible for Return Void was found.

Contra Transaction

In this set of examples, we will show how Contra checking is used.

A. Add A Credit Card Number To The Contra List

Adding a card number to the Contra list will block its acceptance on the associated terminal ID.

Field Name	Value
TERMID	EXAMPLE1
TYPE	+
CARD	5191111111111111

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=+&CARD=5191111111111111

Response:
TEXT=CARD ADDED &CODE=0000

B. Contra Decline

Future authorization attempts on this card will be blocked until it is removed from the Contra list. Here is an attempt to perform a Sale on a blocked card.

Field Name	Value
TERMID	EXAMPLE1
TYPE	S
CARD	5191111111111111
EXP	1214
AMT	5895
REF	CONTRATEST

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=S&CARD=5191111111111111&EXP=1214&AMT=5895&REF=CONTRATEST

Response:
TEXT=DECLINED (CONTRA) &CODE=1008

C. Contra Delete

In this example we will remove the credit card from the Contra table

Field Name	Value
TERMID	EXAMPLE1
TYPE	-
CARD	5191111111111111

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=-&CARD=5191111111111111

Response:
TEXT=DELETED &CODE=0000

Token Transactions

This set of examples will show the use of tokens in transaction processing.

Creating A Token

In this example, we will associate a token with a credit card and expiry date. We will also assign some token reference data that can be used for Token Search via Payroc’s Dashboard web application.

Field Name	Value
TERMID	EXAMPLE1
TYPE	G
TOKEN_ACTION	ADD
TOKEN	45125206MCRD5111
CARD	5191111111111111
EXP	1214
TOKEN_REF	JSMITH-MCRD

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=G&TOKEN_ACTION=ADD&TOKEN=45125206MCRD5111&CARD=5191111111111111&EXP=1214&TOKEN_REF=JSMITH-MCRD

Response:
TEXT=TOKEN ADDED &CODE=0000

Creating Auto-Generated Tokens

In the following examples, we will associate a credit card and expiry date with a token where the Token ID value is automatically generated by Payroc.

Examples are based on configuration for a merchant where the maximum length for Token IDs has been setup as 16 characters. TOKEN field containing a “?” is included in the request for all examples indicating that the Token ID is to be generated by Payroc.

In this example, the options for card type and last four digits of card number suffix are not turned on so a 16 digit unique Token ID value is generated.

Field Name	Value
TERMID	EXAMPLE1
TYPE	G
TOKEN_ACTION	ADD
TOKEN	?
CARD	5191111111111111
EXP	1214
TOKEN_REF	JSMITH-MCRD

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=G&TOKEN_ACTION=ADD&TOKEN=?&CARD=5191111111111111&EXP=1214&TOKEN_REF=JSMITH-MCRD

Response:
TEXT=TOKEN ADDED &CODE=0000&TOKEN=2000000250110334

Auto-generated Token ID options for card type and last four digits of card number have been turned on for this example. The Token ID is generated to include a unique 11 digit value along with a suffix specifying the card type and last four digits of the card number.

Field Name	Value
TERMID	EXAMPLE1
TYPE	G
TOKEN_ACTION	ADD
TOKEN	?
CARD	5191111111111111
EXP	1214
TOKEN_REF	JSMITH-MCRD

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=G&TOKEN_ACTION=ADD&TOKEN=?&CARD=5191111111111111&EXP=1214&TOKEN_REF=JSMITH-MCRD

Response:
TEXT=TOKEN ADDED &CODE=0000&TOKEN=20250110334M1111

Auto-generated Token ID formatting options turned on for this example are use of customer prefix along with suffix containing card type and last four digits of the card number.

Field Name	Value
TERMID	EXAMPLE1
TYPE	G
TOKEN_ACTION	ADD
TOKEN	31121345?
CARD	5191111111111111
EXP	1214
TOKEN_REF	JSMITH-MCRD

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=G&TOKEN_ACTION=ADD&TOKEN=?&CARD=5191111111111111&EXP=1214&TOKEN_REF=JSMITH-MCRD

Response:
TEXT=TOKEN ADDED &CODE=0000&TOKEN=31121345M1111

Token Update

In this example, we will be updating the token to change the expiry date. The TOKEN_REF field is not required, but is being sent in this example.

Field Name	Value
TERMID	EXAMPLE1
TYPE	G
TOKEN_ACTION	UPDATE
TOKEN	45125206MCRD5111
EXP	1215
TOKEN_REF	JSMITH-MCRD

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=G&TOKEN_ACTION=UPDATE&TOKEN=45125206MCRD5111&EXP=1215&TOKEN_REF=JSMITH-MCRD

Response:
TEXT=TOKEN UPDATED &CODE=0000

Token Operation with Card Authentication

In these examples, we will request card authentication for a Token Add operation using the Extended Response option.

Values for CSC (CVV2 field) and AVS included in the first example will simulate successful authentication when submitted with Visa, MasterCard or Discover card along with a test Terminal ID. CSC value starting with a ‘3’ will need to be used to simulate successful authentication for an American Express card.

Field Name	Value
TERMID	EXAMPLE1
TYPE	G
TOKEN_ACTION	ADD
TOKEN	45125206MCRD0003
CARD	5550000000000003
EXP	1214
CVV2	400
AVS	12345
TOKEN_REF	JSMITH-MCRD
EXT_RESP	Y

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=G&TOKEN_ACTION=ADD&TOKEN=45125206MCRD0003&CARD=5550000000000003&EXP=1214&CVV2=400&AVS=12345&TOKEN_REF=JSMITH-MCRD&EXT_RESP=Y

Response:
TEXT=TOKEN ADDED &AVS=Y&CODE=0000&CTYPE=MCRD&CPROD=MC&CCO=124 &CVV2=M

Values for CSC (CVV2 field) and AVS included in this example will simulate authentication failure when submitted with a test Terminal ID. The Token operation (ADD or UPDATE) is not executed since the authentication result was a failure.

Field Name	Value
TERMID	EXAMPLE1
TYPE	G
TOKEN_ACTION	ADD
TOKEN	45125206MCRD0003
CARD	5550000000000003
EXP	1214
CVV2	500
AVS	99999
TOKEN_REF	JSMITH-MCRD
EXT_RESP	Y

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=G&TOKEN_ACTION=ADD&TOKEN=45125206MCRD0003&CARD=5550000000000003&EXP=1214&CVV2=500&AVS=99999&TOKEN_REF=JSMITH-MCRD&EXT_RESP=Y

Response:
TEXT=CARD VERIFY FAIL &AVS=N&CODE=1013&CTYPE=MCRD&CPROD=MC&CCO=124 &CVV2=N&RESP_TYPE=D

Token Deactivate

In this example, we will de-activating the token.

Field Name	Value
TERMID	EXAMPLE1
TYPE	G
TOKEN_ACTION	DEACTIVATE
TOKEN	45125206MCRD5111

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=G&TOKEN_ACTION=DEACTIVATE&TOKEN=45125206MCRD5111

Response:
TEXT=TOKEN DEACTIVATED &CODE=0000

Token Reactivate

In this example, we will re-activate the token. All data is preserved while the token is deactivated, but the token cannot be used.

Field Name	Value
TERMID	EXAMPLE1
TYPE	G
TOKEN_ACTION	REACTIVATE
TOKEN	45125206MCRD5111

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=G&TOKEN_ACTION=REACTIVATE&TOKEN=45125206MCRD5111

Response:
TEXT=TOKEN REACTIVATED &CODE=0000

Creating a Token and Payment Schedule

In this example, we will create a Token and setup a Payment Schedule using a Payment Scheduling transaction type.

After the Token has been created then the Payment Schedule will be setup for 12 monthly payments starting on date of 20150401 (YYYYMMDD).

Field Name	Value
TERMID	EXAMPLE1
TYPE	N
TOKEN_ACTION	ADD
TOKEN	45125206MCRD5111
CARD	5191111111111111
EXP	1216
SCHEDULE_ACTION	ADD
SCHEDULE_TYPE	MONTHLY
SCHEDULE_NUM_PAYMENTS	12
SCHEDULE_START_DATE	20150401
AMT	12345

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=N&TOKEN_ACTION=ADD&TOKEN=45125206MCRD5111&CARD=5191111111111111&EXP=1216&SCHEDULE_ACTION=ADD&SCHEDULE_TYPE=MONTHLY&SCHEDULE_NUM_PAYMENTS=12&SCHEDULE_START_DATE=20150401&AMT=12345

Response:
TEXT=SCHEDULE ADDED &CODE=0000

Creating a Payment Schedule for an existing Token

In this example, we will create a Payment Schedule for an existing Token using a Payment Scheduling transaction type.

The Payment Schedule will be setup for 6 bi-monthly payments starting on date of 20150401 (YYYYMMDD).

Field Name	Value
TERMID	EXAMPLE1
TYPE	N
TOKEN	45125206MCRD5111
SCHEDULE_ACTION	ADD
SCHEDULE_TYPE	MONTHLY
SCHEDULE_FREQUENCY	2
SCHEDULE_NUM_PAYMENTS	6
SCHEDULE_START_DATE	20150401
AMT	12345

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=N&TOKEN=45125206MCRD5111&SCHEDULE_ACTION=ADD&SCHEDULE_TYPE=MONTHLY&SCHEDULE_FREQUENCY=2&SCHEDULE_NUM_PAYMENTS=6&SCHEDULE_START_DATE=20150401&AMT=12345

Response:
TEXT=SCHEDULE ADDED &CODE=0000

Updating a Payment Schedule

In this example, we will update a Payment Schedule using a Payment Scheduling transaction type.

The Payment Schedule will be changed to 10 weekly payments starting on date of 20150801 (YYYYMMDD).

Field Name	Value
TERMID	EXAMPLE1
TYPE	N
TOKEN	45125206MCRD5111
SCHEDULE_ACTION	UPDATE
SCHEDULE_TYPE	WEEKLY
SCHEDULE_FREQUENCY	1
SCHEDULE_NUM_PAYMENTS	10
SCHEDULE_START_DATE	20150801
AMT	12345

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=N&TOKEN=45125206MCRD5111&SCHEDULE_ACTION=UPDATE&SCHEDULE_TYPE=WEEKLY&SCHEDULE_FREQUENCY=1&SCHEDULE_NUM_PAYMENTS=10&SCHEDULE_START_DATE=20150801&AMT=12345

Response:
TEXT=SCHEDULE UPDATED &CODE=0000

Updating a Payment Schedule amount

In this example, we will update the amount setup for a Payment Schedule using a Payment Scheduling transaction type.

Field Name	Value
TERMID	EXAMPLE1
TYPE	N
TOKEN	45125206MCRD5111
SCHEDULE_ACTION	UPDATE
AMT	12345

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=N&TOKEN=45125206MCRD5111&SCHEDULE_ACTION=UPDATE&AMT=12345

Response:
TEXT=SCHEDULE UPDATED &CODE=0000

Deactivating a Payment Schedule

In this example, we will deactivate a Payment Schedule using a Payment Scheduling transaction type.

Field Name	Value
TERMID	EXAMPLE1
TYPE	N
TOKEN	45125206MCRD5111
SCHEDULE_ACTION	DEACTIVATE

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=N&TOKEN=45125206MCRD5111&SCHEDULE_ACTION=DEACTIVATE&AMT=12345

Response:
TEXT=SCHEDULE DEACTIVATED&CODE=0000

Sale Transaction Using A Token

In this example, we will perform a Sale transaction on the token from the previous examples. The card associated with the token will be charged.

Field Name	Value
TERMID	EXAMPLE1
TYPE	S
TOKEN	45125206MCRD5111
AMT	14259
REF	TOKENTRANSEXAMPLE

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=S&TOKEN=45125206MCRD5111&AMT=14259&REF=TOKENTRANSEXAMPLE

Response:
TEXT=T35698 $142.59&AUTH=T35698CODE=0000

Pre-Authorization Transaction Using A Token

In this example, we will process a Pre-Authorization transaction using the token from the preceding examples while also performing an address verification check.

Field Name	Value
TERMID	EXAMPLE1
TYPE	P
TOKEN	45125206MCRD5111
AMT	158700
REF	TOKENCVVAVSTEST
AVS	27MILLST

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=P&TOKEN=45125206MCRD5111&AMT=158700&REF=TOKENCVVAVSTEST&AVS=27MILLST

Response:
TEXT=T35710 $1587.00&AUTH=T35710&AVS=A&CODE=0000

Full Authorization Reversal

In this example, we will demonstrate the use of Authorization Reversal transactions to perform full reversals.

A. Pre-Authorization Transaction For $100.00

To begin, we will Pre-Authorize a transaction using the token from the previous examples in the Token Transactions examples.

Field Name	Value
TERMID	EXAMPLE1
TYPE	P
TOKEN	45125206MCRD5111
AMT	10000
REF	6598741

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=P&TOKEN=45125206MCRD5111&AMT=10000&REF=6598741

Response:
TEXT=T01727 $100.00&AUTH=T01727&CODE=0000

B. Pre-Authorization Reversal

In this example, we will perform a reversal for the full amount of $100.00

An amount of “0” is used as the replacement amount, meaning that we would like the actual authorization to be for zero dollars. This effectively removes the authorization, freeing the card’s open-to-buy limit of the $100.00 charge.

Field Name	Value
TERMID	EXAMPLE1
TYPE	W
TOKEN	45125206MCRD5111
AMT	0
REF	6598741

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=W&TOKEN=45125206MCRD5111&AMT=0&REF=6598741

Response:
TEXT=T01727 $0.00&AUTH=T01727&CODE=0000

Partial Authorization Reversal

In this example, we will demonstrate the use of Authorization Reversal transactions to perform partial charge reversals.

A. Pre-Authorization Transaction For $375.25

To begin, we will Pre-Authorize a transaction using the token from the previous examples in the Token Transactions examples.

Field Name	Value
TERMID	EXAMPLE1
TYPE	P
TOKEN	45125206MCRD5111
AMT	37525
REF	659847854

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=P&TOKEN=45125206MCRD5111&AMT=37525&REF=659847854

Response:
TEXT=T03006 $375.25&AUTH=T03006&CODE=0000

B. Replacing The Pre-Authorized Amount

In this example we will be replacing the original Pre-Authorization amount of $375.25 with a new amount of $255.59. The balance of the original Pre-Authorization will be reversed. The card’s open-to-buy will now be reduced by $255.59 instead of $375.25.

Field Name	Value
TERMID	EXAMPLE1
TYPE	W
TOKEN	45125206MCRD5111
AMT	25559
REF	659847854

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=W&TOKEN=45125206MCRD5111&AMT=25559&REF=659847854

Response:
TEXT=T03006 $255.59&AUTH=T03006&CODE=0000

Account Status Inquiry

In this example, we will demonstrate the use of Account Status Inquiry transactions to check the status of card and perform CSC and AVS authentication.

Extended Response option is used in the examples in order to show all of the response fields that are available.

Account Status Inquiry - Positive Card Status

Field Name	Value
TERMID	EXAMPLE1
TYPE	J
CARD	4520700000000008
EXP	0117
CVV2	456
AVS	45678
EXT_RESP	Y

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=J&CARD=4250700000000008&EXP=0117&CVV2=456&AVS=45678&EXT_RESP=Y

Response:
TEXT=T38223 $0.00&AUTH=T38223&AVS=W&CODE=0000&CTYPE=VISA&CCO=124 &CPROD=VB&CVV2=M&EXP=0215&LAST4=0008

An authorization code may not be included in responses for live transactions as Account Status Inquiry transactions do include an amount to be approved by the card issuer.

Account Status Inquiry - Negative Card Status

Field Name	Value
TERMID	EXAMPLE1
TYPE	J
CARD	4520700000000008
EXP	0121
CVV2	456
AVS	45678
EXT_RESP	Y

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=J&CARD=4250700000000008&EXP=0121&CVV2=456&AVS=45678&EXT_RESP=Y

Response:
TEXT=CARD VERIFY FAIL &AVS=W&CODE=1013&CTYPE=VISA&CCO=124&CPROD=VB &CVV2=M&EXP=0215&LAST4=0008

Level 2/Level 3 Transaction

In this set of examples, we will demonstrate a transaction with Level 2 and Level 3 commercial card data.

A. Sale With Level 2 Data

In this example, we will perform a Sale transaction and include Level 2 data in the L2 field.

Field Name	Value
TERMID	EXAMPLE1
TYPE	S
TOKEN	45125206MCRD5111
AMT	10235
REF	98574741
L2	PC3.02|INV1234|S|ABC COMPANY|L9K9K9|ON||||10235|0|1300|0|1177|||PO123569 |20120914|1||||0||||||||REQBUY JSMITH|REF1234|CUSTNUM123|INV1234||||||||

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=S&TOKEN=45125206MCRD5111&AMT=10235&REF=98574741&L2=PC3.02|INV1234|S|ABC COMPANY|L9K9K9|ON||||10235|0|1300|0|1177|||PO123569|20120914|1||||0||||||||REQBUY JSMITH|REF1234|CUSTNUM123|INV1234|||||||

Response:
TEXT=T27712 $102.35 120RH1Z&UID=120RH1Z&AUTH=T27712&CODE=0000

B. Level 3 Detail Submission Transaction (Line Item)

Using the UID from the previous example’s Sale transaction, we will attach an invoice line item to the transaction using a Level 3 Detail Submission transaction. Since this is the first line item, we will send a Level 3 Sequence Number of “001”.

Field Name	Value
TERMID	EXAMPLE1
TYPE	L
UID	120RH1Z
SEQ	001
REF	98574741
L3	PC3.01|INV1234|123569|PENCILS|65985|EA|9058|100|| |T||1300||1178|10235 ||||||MSKU876|CSKU786756|CUSTPO12|SUPPDATA456|GL8765|DIV8765|00005

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&&UID=120RH1Z&SEQ=001&REF=98574741 &TYPE=L&L3=PC3.03|INV1234|123569|PENCILS|65985|EA|9058|100|||T||1300||1178|10235|||||| |MSKU|CSKU786756|CUSTPO12|SUPPDATA456|GL8765|DIV8765|00005

Response:
TEXT=DETAILS DELIVERED &CODE=0000

Delivery of the line item detail was successful.

Air Travel Data Transaction

In this set of examples, we will demonstrate a transaction with Level 2 and Air Travel Data.

Sale With Level 2 And Air Travel Data

The airline Level 2 data is included in the L2 field, and the Air Travel Data is included in the AIR field.

Field Name	Value
TERMID	EXAMPLE1
TYPE	S
TOKEN	45125206MCRD5111
AMT	10235
REF	98574755
L2	PC2.20|0800|0700|712|623||||PO58956
AIR	AIR-01|SMITH/JOHN R|1235874|65432165432121| XYULOYYZXYTZ|20120914|ACACAC|AIR CANADA

Request:
https://lt3a.caledoncard.com/TERMID=EXAMPLE1&TYPE=S&TOKEN=45125206MCRD5111&AMT=10235&REF=98574755&L2=PC2.20|0800|0700|712|623||||PO58956&AIR=AIR-01|SMITH/JOHN R|1235874|65432165432121|XYULOYYZXYTZ|20120914|ACACAC|AIR CANADA

Response:
TEXT=T30502 $102.35&AUTH=T30502&CODE=0000