Real-Time Transaction Processing Integration

Revision 18.3.1

March 19, 2018

Table of Contents

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 1st Digit and 1st 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