July 2018
Canada Only
Page 109 of 477
Moneris Gateway API - Integration Guide
5.5.2 Online Banking Response and Fund-Confirmation Request
The response variables are posted back in an HTML form to either the funded or non-funded URL that
was provided to INTERAC®.
The following variables must be validated (5.8, page 115):
l
l
l
l
l
l
IDEBIT_TRACK2
IDEBIT_ISSCONF
IDEBIT_ISSNAME
IDEBIT_VERSION
IDEBIT_ISSLANG
IDEBIT_INVOICE
Note that IDEBIT_ISSCONF and IDEBIT_ISSNAME must be displayed on the client’s receipt that is generated by the merchant.
After validation, IDEBIT_TRACK2 is used to form an IDebitPurchase transaction that is sent to Moneris
Gateway to confirm the fund.
If the validation fails, redirect the client to the main page and ask for a different means of payment.
If the validation passes, an IDebitPurchase transaction can be sent to Moneris Gateway.
5.6 INTERAC® Online Payment Purchase
INTERAC® Online Payment Purchase transaction object definition
IDebitPurchase IOP_Txn = new IDebitPurchase();
HttpsPostRequest object for INTERAC® Online Payment Purchase transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(IOP_Txn);
INTERAC® Online Payment Purchase transaction values
For a full description of mandatory and optional values, see Appendix A Definitions of Request Fields
Table 48: INTERAC® Online Payment transaction object mandatory values
Value
Type
Limits
Set method
Order ID
String
50-character alphanumeric
IOP_Txn.setOrderId(order_
id);
Amount
String
9-character decimal
IOP_Txn.setAmount(amount);
Track2 data
String
40-character alpha-
IOP_Txn.setTrack2(track2);
Page 110 of 477
Canada Only
July 2018
5 INTERAC® Online Payment
Table 48: INTERAC® Online Payment transaction object mandatory values
Value
Type
Limits
Set method
numeric
Table 49: INTERAC® Online Payment Purchase transaction optional values
Value
Type
Limits
Set method
Customer ID
String
50-character alphanumeric
IOP_Txn.setCustId(cust_id);
Dynamic
descriptor
String
20-character alphanumeric
IOP_Txn.setDynamicDescriptor
(dynamic_descriptor);
Customer
information
Object
Not applicable. Click hereSee IOP_Txn.setCustInfo(customer);
Section 13 (page 355).
Sample INTERAC® Online Payment Purchase
package Canada;
import JavaAPI.*;
public class TestCanadaIDebitPurchase
{
public static void main(String[] args)
{
String store_id = "store5";
String api_token = "yesguy";
java.util.Date createDate = new java.util.Date();
String order_id = "Test"+createDate.getTime();
String cust_id = "Lance_Briggs_55";
String amount = "5.00";
String track2 = "5268051119993326=0609AAAAAAAAAAAAA000";
String processing_country_code = "CA";
boolean status_check = false;
/********************* Billing/Shipping Variables ****************************/
String first_name = "Bob";
String last_name = "Smith";
String company_name = "ProLine Inc.";
String address = "623 Bears Ave";
String city = "Chicago";
String province = "Illinois";
String postal_code = "M1M2M1";
String country = "Canada";
String phone = "777-999-7777";
String fax = "777-999-7778";
String tax1 = "10.00";
String tax2 = "5.78";
String tax3 = "4.56";
String shipping_cost = "10.00";
/********************* Order Line Item Variables *****************************/
String[] item_description = new String[] { "Chicago Bears Helmet", "Soldier Field Poster" };
String[] item_quantity = new String[] { "1", "1" };
String[] item_product_code = new String[] { "CB3450", "SF998S" };
String[] item_extended_amount = new String[] { "150.00", "19.79" };
/********************** Customer Information Object **************************/
July 2018
Canada Only
Page 111 of 477
Moneris Gateway API - Integration Guide
Sample INTERAC® Online Payment Purchase
CustInfo customer = new CustInfo();
/********************** Set Customer Billing Information **********************/
customer.setBilling(first_name, last_name, company_name, address, city,
province, postal_code, country, phone, fax, tax1, tax2,
tax3, shipping_cost);
/******************** Set Customer Shipping Information ***********************/
customer.setShipping(first_name, last_name, company_name, address, city,
province, postal_code, country, phone, fax, tax1, tax2,
tax3, shipping_cost);
/***************************** Order Line Items ******************************/
customer.setItem(item_description[0], item_quantity[0],
item_product_code[0], item_extended_amount[0]);
customer.setItem(item_description[1], item_quantity[1],
item_product_code[1], item_extended_amount[1]);
/************************** Request *************************/
IDebitPurchase IOP_Txn = new IDebitPurchase();
IOP_Txn.setOrderId(order_id);
IOP_Txn.setCustId(cust_id);
IOP_Txn.setAmount(amount);
IOP_Txn.setIdebitTrack2(track2);
IOP_Txn.setCustInfo(customer);
//IOP_Txn.setDynamicDescriptor("dynamicdescriptor1");
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(IOP_Txn);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
}
catch (Exception e)
{
e.printStackTrace();
}
}
}
Page 112 of 477
Canada Only
July 2018
5 INTERAC® Online Payment
5.7 INTERAC® Online Payment Refund
To process this transaction, you need the order ID and transaction number from the original INTERAC®
Online Payment Purchase transaction.
INTERAC® Online Payment Refund transaction object definition
IDebitRefund refund = new IDebitRefund();
HttpsPostRequest object for INTERAC® Online Payment Refund transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(refund);
INTERAC® Online Payment Refund transaction object values
For a full description of mandatory and optional values, see Appendix A Definitions of Request Fields
Table 50: INTERAC® Online Payment Refund transaction object mandatory variables
Value
Type
Limits
Set method
Order ID
String
50-character alphanumeric
refund.setOrderId(order_id);
Amount
String
9-character decimal
refund.setAmount(amount);
Transaction number
String
255-character alphanumeric
refund.setTxnNumber(txn_
number);
Table 51: INTERAC® Online Payment Refund transaction optional values
Value
Type
Limits
Set method
Customer ID
String
50-character alphanumeric
refund.setCustId(cust_id);
Status Check
Boolean
true/false
mpgReq.setStatusCheck
(status_check);
Sample code
Sample INTERAC® Online Payment Refund
package Canada;
import JavaAPI.*;
public class TestCanadaIDebitRefund
{
public static void main(String[] args)
{
July 2018
Canada Only
Page 113 of 477
Moneris Gateway API - Integration Guide
Sample INTERAC® Online Payment Refund
String store_id = "store5";
String api_token = "yesguy";
String order_id = "Test1435508096214";
String amount = "5.00";
String txn_number = "116181-0_10";
String processing_country_code = "CA";
String cust_id = "my customer id";
boolean status_check = false;
IDebitRefund refund = new IDebitRefund();
refund.setOrderId(order_id);
refund.setAmount(amount);
refund.setTxnNumber(txn_number);
refund.setCustId(cust_id);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(refund);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
}
catch (Exception e)
{
e.printStackTrace();
}
}
}
Page 114 of 477
Canada Only
July 2018
5 INTERAC® Online Payment
5.8 INTERAC® Online Payment Field Definitions
Table 52: Field Definitions
Characters
Limits
Value
Description
IDEBIT_
MERCHNUM
5-14
Numbers and uppercase letters
This field is provided by Moneris. For example, 0003MONMPGXXXX.
IDEBIT_TERMID 8
Numbers and uppercase letters
Optional field
IDEBIT_
AMOUNT
1-12
IDEBIT_
CURRENCY
3
Numbers
Amount expressed in cents (for example, 1245 for $12.45) to charge to the card.
"CAD" or "USD"
National currency of the transaction.
IDEBIT_INVOICE 1-20
ISO-8859-1 encoded characters restricted to:
l
l
l
l
l
Uppercase and lowercase
Numbers
ÀÁÂÄÈÉÊËÎ Ï Ô ÙÛÜÇàáâäèéêëîïôù û ü ÿ ç
Spaces
#$. , -/ =?@'
Optional field
Can be the Order ID when used with Moneris Gateway fund confirmation transactions.
IDEBIT_
MERCHDATA
1024
ISO-8859-1 restricted to single-byte codes, hex 20 to 7E (consistent with
US-ASCII and ISO-8859-1 Latin-1).
Note that the following character combinations may not be accepted in
the IDEBIT_MERCHDATA field:
l
"/..", "/%2E.", "/.%2E", "/%2E%2E", "\\%2E%2E", "\\%2E.",
"\\.%2E", "\\%2E%2E", "&#", "<", "%3C", ">", "%3E"
Free form data provided by the merchant that will be passed back unchanged to the
merchant once the payment has been guaranteed in online banking.
This may be used to identify the customer, session or both.
July 2018
Canada Only
Page 115 of 477
Moneris Gateway API - Integration Guide
Table 52: Field Definitions (continued)
Characters
Limits
Value
Description
IDEBIT_
FUNDEDURL
1024
ISO-8859-1 restricted to single-byte codes, restricted to:
l
l
l
Uppercase and lowercase letters
Numbers
;/ ?:@&=+$, -_. !~*‘ ()%
Https address to which the issuer will redirect cardholders after guaranteeing the
fund through online banking.
IDEBIT_
1024
NOTFUNDEDURL
ISO-8859-1, restricted to single-byte codes, restricted to:
l
l
l
Uppercase and lowercase letters
Numbers
;/ ?:@&=+$, -_. !~*‘ ()%
Https address to which the issuer redirects cardholders after failing or canceling the
online banking process.
IDEBIT_
MERCHLANG
2
“en” or “fr”
Customer's current language at merchant.
IDEBIT_VERSION 3
Numbers
Initially, the value is 1.
IDEBIT_ISSLANG 2
“en” or “fr”
Customer’s current language at issuer.
IDEBIT_TRACK2
37
ISO-8859-1 (restricted to single-byte codes), hex 20 to 7E (consistent with
US-ASCII and ISO-8859-1 Latin-1)
Value returned by the issuer. It includes the PAN, expiry date, and transaction ID.
IDEBIT_ISSCONF 15
ISO-8859-1 encoded characters restricted to:
l
l
l
l
l
Uppercase and lowercase letters
Numbers
ÀÁÂÄÈÉÊËÎ Ï Ô ÙÛÜÇàáâäèéêëîïôù û ü ÿ ç
Spaces
#$. , -/ =?@'
Confirmation number returned from the issuer to be displayed on the merchant’s
confirmation page and on the receipt.
Page 116 of 477
Canada Only
July 2018
5 INTERAC® Online Payment
Table 52: Field Definitions (continued)
Characters
Limits
Value
Description
IDEBIT_
ISSNAME
30
ISO-8859-1 encoded characters restricted to:
l
l
l
l
l
Uppercase and lowercase letters
Numbers
ÀÁÂÄÈÉÊËÎ Ï Ô ÙÛÜÇàáâäèéêëîïôù û ü ÿ ç
Spaces
#$. , -/ =?@•'
Issuer name to be displayed on the merchant’s confirmation page and on the
receipt.
July 2018
Canada Only
Page 117 of 477
6 Mag Swipe Transaction Set
l
l
l
l
l
l
l
l
6.1 Mag Swipe Transaction Type Definitions
6.2 Mag Swipe Purchase
l 6.2.1 Encrypted Mag Swipe Purchase
6.3 Mag Swipe Pre-Authorization
l 6.3.1 Encrypted Mag Swipe Pre-Authorization
6.4 Mag Swipe Completion
6.5 Mag Swipe Force Post
l 6.5.1 Encrypted Mag Swipe Force Post
6.6 Mag Swipe Purchase Correction
6.7 Mag Swipe Refund
6.8 Mag Swipe Independent Refund
l 6.8.1 Encrypted Mag Swipe Independent Refund
Mag Swipe transactions allow customers to swipe a credit card and submit the Track2 details.
These transactions support the submission of Track2 as well as a manual entry of the credit card number
and expiry date. If all three fields are submitted, the Track2 details are used to process the transaction.
6.1 Mag Swipe Transaction Type Definitions
Purchase
Verifies funds on the customer’s card, removes the funds and prepares them for deposit into
the merchant’s account.
Pre-Authorization
Verifies and locks funds on the customer’s credit card. The funds are locked for a specified
amount of time based on the card issuer.
To retrieve the funds that have been locked by a Pre-Authorization transaction so that they
may be settled in the merchant’s account, a Completion transaction must be performed. A
Pre-Authorization may only be "completed" once.
Completion
Retrieves funds that have been locked (by a Mag Swipe Pre-Authorization transaction), and
prepares them for settlement into the merchant’s account.
Force Post
Retrieves the locked funds and prepares them for settlement into the merchant’s account.
This is used when a merchant obtains the authorization number directly from the issuer by a
third-party authorization method (such as by phone).
Purchase Correction
Restores the full amount of a previous Mag Swipe Purchase or Mag Swipe Completion transaction to the cardholder's card, and removes any record of it from the cardholder's statement. The order ID and transaction number from the original transaction are required, but
the credit card does not need to be re-swiped.
This transaction can be used against a Purchase or Completion transaction that occurred
same day provided that the batch containing the original transaction remains open. When
using the automated closing feature, Batch Close occurs daily between 10 and 11 pm Eastern
Time.
July 2018
Page 118 of 477
Moneris Gateway API - Integration Guide
This transaction is sometimes referred to as "void".
Refund
Restores all or part of the funds from a Mag Swipe Purchase or Mag Swipe Completion transaction to the cardholder's card. Unlike a Purchase Correction, there is a record of the refund.
Independent Refund
Credits a specified amount to the cardholder’s credit card.
This does not require a previous transaction (such as Mag Swipe Purchase) to be logged in the
Moneris Gateway. However, a credit card must be swiped to provide the Track2 data.
6.1.1 Encrypted Mag Swipe Transactions
Encrypted Mag Swipe transactions allow the customer to swipe or key in a credit card using a Monerisprovided encrypted mag swipe reader, and submit the encrypted Track2 details.
The encrypted mag swipe reader can be used for processing:
l
l
l
Swiped card-present transactions
Manually keyed card-present transactions
Manually keyed card-not-present transactions.
Encrypted Mag Swipe transactions are identical to the regular Mag Swipe transactions from the customer's perspective. However, the card data must be swiped or keyed in via a Moneris-provided encrypted mag swipe reader. Contact Moneris for more details.
Only Mag Swipe Purchase and Mag Swipe Pre-Authorization have encrypted versions. Their explanations
appear in this document as subsections of the regular (unencrypted) Mag Swipe Purchase and Mag
Swipe Pre-Authorization transactions respectively.
6.2 Mag Swipe Purchase
Mag Swipe Purchase transaction object definition
Track2Purchase track2purchase = new Track2Purchase();
HttpsPostRequest object for Mag Swipe Purchase transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(track2purchase);
Mag Swipe Purchase transaction values
For a full description of mandatory and optional values, see Appendix A Definitions of Request Fields
Page 119 of 477
July 2018
6 Mag Swipe Transaction Set
Table 53: Mag Swipe Purchase transaction object mandatory values
Value
Type
Limits
Set method
Order ID
String
50-character alphanumeric
track2purchase.setOrderId
(order_id);
Amount
String
9-character decimal
track2purchase.setAmount
(amount);
Credit card number
String
20-character numeric
track2purchase.setPan(pan);
OR
OR
OR
Track2 data
40-character numeric
track2purchase.setTrack2
(track2);
4-character alphanumeric
track2purchase.setExpDate
(expiry_date);
Expiry date
String
(YYMM format)
POS code
String
2-character numeric
track2purchase.setPosCode
(pos_code);
Table 54: Mag Swipe Purchase transaction optional values
Value
Type
Limits
Set method
AVS information
Object
N/A
track2purchase.setAvsInfo
(avsCheck);
Customer ID
String
50-character alphanumeric
track2purchase.setCustId
(cust_id);
CVD information
Object
N/A
track2purchase.setCvdInfo
(cvdCheck);
Dynamic descriptor
String
20-character alphanumeric
track2purchase
.setDynamicDescriptor
(dynamic_descriptor);
Status Check
Boolean
true/false
mpgReq.setStatusCheck
(status_check);
Sample Mag Swipe Purchase
package Canada;
import JavaAPI.*;
July 2018
Page 120 of 477
Moneris Gateway API - Integration Guide
Sample Mag Swipe Purchase
public class TestCanadaTrack2Purchase
{
public static void main(String[] args)
{
String store_id = "store1";
String api_token = "yesguy";
java.util.Date createDate = new java.util.Date();
String order_id = "Test"+createDate.getTime();
String cust_id = "LBriggs";
String amount = "1.00";
String track2 = ";5258968987035454=06061015454001060101?";
String pan = "";
String exp = ""; //must send '0000' if swiped
String pos_code = "00";
String processing_country_code = "CA";
boolean status_check = false;
Track2Purchase track2purchase = new Track2Purchase();
track2purchase.setOrderId(order_id);
track2purchase.setCustId(cust_id);
track2purchase.setAmount(amount);
track2purchase.setTrack2(track2);
track2purchase.setPan(pan);
track2purchase.setExpdate(exp);
track2purchase.setPosCode(pos_code);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(track2purchase);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
//System.out.println("StatusCode = " + receipt.getStatusCode());
//System.out.println("StatusMessage = " + receipt.getStatusMessage());
}
catch (Exception e)
{
e.printStackTrace();
}
}
}
Page 121 of 477
July 2018
6 Mag Swipe Transaction Set
6.2.1 Encrypted Mag Swipe Purchase
Encrypted Mag Swipe Purchase transaction object definition
EncTrack2Purchase encpurchase = new EncTrack2Purchase();
HttpsPostRequest object for Encrypted Mag Swipe Purchase transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(encpurchase);
Encrypted Mag Swipe Purchase transaction values
For a full description of mandatory and optional values, see Appendix A Definitions of Request Fields
Table 55: Encrypted Mag Swipe Purchase transaction object mandatory values
Value
Type
Limits
Set method
Order ID
String
50-character alphanumeric
encpurchase.setOrderId
(order_id);
Amount
String
9-character decimal
encpurchase.setAmount
(amount);
Encrypted Track2 data
String
n/a
encpurchase.setEncTrack2
(enc_track2);
POS code
String
2-character numeric
encpurchase.setPosCode(pos_
code);
Device type
String
30-character alphanumeric
encpurchase.setDeviceType
(device_type);
Table 56: Encrypted Mag Swipe Purchase transaction optional values
Value
Type
Limits
Set method
Customer ID
String
50-character alphanumeric
encpurchase.setCustId(cust_
id);
Status Check
Boolean
true/false
mpgReq.setStatusCheck
(status_check);
AVS information
Object
Not applicable. Click
hereSee 9.1 (page
286).
encpurchase.setAvsInfo
(avsCheck);
Dynamic descriptor
String
20-character alpha-
encpurchase
July 2018
Page 122 of 477
Moneris Gateway API - Integration Guide
Table 56: Encrypted Mag Swipe Purchase transaction optional values (continued)
Value
Type
Limits
numeric
Set method
.setDynamicDescriptor
(dynamic_descriptor);
Sample Encrypted Mag Swipe Purchase
package Canada;
import JavaAPI.*;
public class TestCanadaEncTrack2Purchase
{
public static void main(String args[])
{
java.util.Date createDate = new java.util.Date();
String order_id = "Test"+createDate.getTime();
String store_id = "moneris";
String api_token = "hurgle";
String amount = "1.00";
String enc_track2 = "ENCRYPTEDTRACK2DATA";
String pan = "";
String expdate = "";
String pos_code = "00";
String device_type = "idtech_bdk";
String processing_country_code = "CA";
EncTrack2Preauth enc_track2_preauth = new EncTrack2Preauth ();
enc_track2_preauth.setOrderId(order_id);
enc_track2_preauth.setAmount(amount);
enc_track2_preauth.setEncTrack2(enc_track2);
enc_track2_preauth.setPan(pan);
enc_track2_preauth.setExpdate(expdate);
enc_track2_preauth.setPosCode(pos_code);
enc_track2_preauth.setDeviceType(device_type);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(enc_track2_preauth);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
Page 123 of 477
July 2018
6 Mag Swipe Transaction Set
Sample Encrypted Mag Swipe Purchase
System.out.println("TimedOut = " + receipt.getTimedOut());
}
catch (Exception e)
{
e.printStackTrace();
}
}
}
6.3 Mag Swipe Pre-Authorization
Mag Swipe Pre-Authorization transaction object definition
Track2PreAuth track2preauth = new Track2PreAuth();
HttpsPostRequest object for Mag Swipe Pre-Authorization transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(track2preauth);
Mag Swipe Pre-Authorization transaction values
For a full description of mandatory and optional values, see Appendix A Definitions of Request Fields
Table 57: Mag Swipe Pre-Authorization transaction object mandatory values
Value
Type
Limits
Set method
Order ID
String
50-character alphanumeric
track2preauth.setOrderId
(order_id);
Amount
String
9-character decimal
track2preauth.setAmount
(amount);
Credit card number
String
20-character numeric
track2preauth.setPan(pan);
OR
OR
OR
Track2 data
40-character numeric
track2preauth.setPan(pan);
4-character alphanumeric
track2preauth.setExpDate
(expiry_date);
Expiry date
String
(YYMM format)
POS code
July 2018
String
2-character numeric
track2preauth.setPosCode(pos_
code);
Page 124 of 477
Moneris Gateway API - Integration Guide
Table 58: Mag Swipe Pre-Authorization transaction optional values
Value
Type
Limits
Set method
Customer ID
String
50-character alphanumeric
track2preauth.setCustId
(cust_id);
Dynamic descriptor
String
20-character alphanumeric
track2preauth
.setDynamicDescriptor
(dynamic_descriptor);
Status Check
Boolean
true/false
mpgReq.setStatusCheck
(status_check);
Sample Mag Swipe Pre-Authorization
package Canada;
import JavaAPI.*;
public class TestCanadaTrack2PreAuth
{
public static void main(String[] args)
{
String store_id = "store1";
String api_token = "yesguy";
java.util.Date createDate = new java.util.Date();
String order_id = "Test"+createDate.getTime();
String cust_id = "LBriggs";
String amount = "5.00";
String track2 = ";5258968987035454=06061015454001060101?";
String pan = "";
String exp = "0000"; //must send '0000' if swiped
String pos_code = "00";
String processing_country_code = "CA";
boolean status_check = false;
Track2PreAuth track2preauth = new Track2PreAuth();
track2preauth.setOrderId(order_id);
track2preauth.setCustId(cust_id);
track2preauth.setAmount(amount);
track2preauth.setTrack2(track2);
track2preauth.setPan(pan);
track2preauth.setExpdate(exp);
track2preauth.setPosCode(pos_code);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(track2preauth);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
Page 125 of 477
July 2018
6 Mag Swipe Transaction Set
Sample Mag Swipe Pre-Authorization
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
//System.out.println("StatusCode = " + receipt.getStatusCode());
//System.out.println("StatusMessage = " + receipt.getStatusMessage());
}
catch (Exception e)
{
e.printStackTrace();
}
}
}
6.3.1 Encrypted Mag Swipe Pre-Authorization
Encrypted Mag Swipe Pre-Authorization transaction object definition
EncTrack2Preauth enc_track2_preauth = new EncTrack2Preauth ();
HttpsPostRequest object for Encrypted Mag Swipe Pre-Authorization transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(enc_track2_preauth);
Encrypted Mag Swipe Pre-Authorization transaction values
For a full description of mandatory and optional values, see Appendix A Definitions of Request Fields
Table 59: Encrypted Mag Swipe Pre-Authorization transaction object mandatory values
Value
Type
Limits
Set method
Order ID
String
50-character alphanumeric
enc_track2_
preauth.setOrderId(order_
id);
Amount
String
9-character decimal
enc_track2_preauth.setAmount
(amount);
Credit card number
String
20-character numeric
enc_track2_preauth.setPan
(pan);
OR
OR
OR
July 2018
Page 126 of 477
Moneris Gateway API - Integration Guide
Table 59: Encrypted Mag Swipe Pre-Authorization transaction object mandatory values
Value
Type
Encrypted Track2
Limits
Set method
n/a
enc_track2_
preauth.setEncTrack2(enc_
track2);
POS code
String
2-character numeric
enc_track2_
preauth.setPosCode(pos_
code);
Device type
String
30-character alphanumeric
enc_track2_
preauth.setDeviceType
(device_type);
Table 60: Encrypted Mag Swipe Pre-Authorization transaction optional values
Value
Type
Limits
Customer ID
String
50-character alphanumeric
Status Check
Boolean
true/false
Set method
enc_track2_preauth.setCustId
(cust_id);
mpgReq.setStatusCheck(status_
check);
Sample Encrypted Mag Swipe Pre-Authorization
package Canada;
import JavaAPI.*;
public class TestCanadaEncTrack2Preauth
{
public static void main(String args[])
{
String host = "esqa.moneris.com";
String store_id = "store1";
String api_token = "yesguy";
java.util.Date createDate = new java.util.Date();
String order_id = "Test"+createDate.getTime();
String amount = "1.00";
String enc_track2 ="ENCRYPTEDTRACK2DATA";
String pan = "";
String expdate = "";
String pos_code = "00";
String device_type = "idtech_bdk";
String processing_country_code = "CA";
EncTrack2Preauth enc_track2_preauth = new EncTrack2Preauth ();
enc_track2_preauth.setOrderId(order_id);
enc_track2_preauth.setAmount(amount);
enc_track2_preauth.setEncTrack2(enc_track2);
enc_track2_preauth.setPan(pan);
enc_track2_preauth.setExpdate(expdate);
enc_track2_preauth.setPosCode(pos_code);
enc_track2_preauth.setDeviceType(device_type);
Page 127 of 477
July 2018
6 Mag Swipe Transaction Set
Sample Encrypted Mag Swipe Pre-Authorization
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(enc_track2_preauth);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
receipt = null;
}
catch (Exception e)
{
e.printStackTrace();
}
}
}
6.4 Mag Swipe Completion
Mag Swipe Completion transaction object definition
Track2Completion track2completion = new Track2Completion();
HttpsPostRequest object for Mag Swipe Completion transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(track2completion);
Mag Swipe Completion transaction values
For a full description of mandatory and optional values, see Appendix A Definitions of Request Fields
July 2018
Page 128 of 477
Moneris Gateway API - Integration Guide
Table 61: Mag Swipe Completion transaction object mandatory values
Value
Type
Limits
Set method
Order ID
String
50-character alphanumeric
track2completion.setOrderId
(order_id);
Transaction number
String
255-character variable
character
track2completion.setTxnNumber
(txn_number);
Completion Amount
String
9-character decimal
track2completion.setCompAmount
(comp_amount);
POS code
String
2-character numeric
track2completion.setPosCode
(pos_code);
Table 62: Mag Swipe Completion transaction optional values
Value
Type
Limits
Set method
Customer ID
String
50-character alphanumeric
track2completion.setCustId
(cust_id);
Status Check
Boolean
true/false
mpgReq.setStatusCheck
(status_check);
Dynamic descriptor
String
20-character alphanumeric
track2completion
.setDynamicDescriptor
(dynamic_descriptor);
Sample Mag Swipe Completion
package Canada;
import JavaAPI.*;
public class TestCanadaTrack2Completion
{
public static void main(String[] args)
{
String store_id = "store1";
String api_token = "yesguy";
String order_id = "Test1432091015817";
String txn_number = "16540-0_10";
String amount = "1.00";
String pos_code = "00";
String dynamic_descriptor = "123456";
String processing_country_code = "CA";
boolean status_check = false;
Track2Completion track2completion = new Track2Completion();
track2completion.setOrderId(order_id);
track2completion.setTxnNumber(txn_number);
track2completion.setAmount(amount);
track2completion.setPosCode(pos_code);
track2completion.setDynamicDescriptor(dynamic_descriptor);
HttpsPostRequest mpgReq = new HttpsPostRequest();
Page 129 of 477
July 2018
6 Mag Swipe Transaction Set
Sample Mag Swipe Completion
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(track2completion);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
//System.out.println("StatusCode = " + receipt.getStatusCode());
//System.out.println("StatusMessage = " + receipt.getStatusMessage());
}
catch (Exception e)
{
e.printStackTrace();
}
}
}
6.5 Mag Swipe Force Post
Mag Swipe Force Post transaction object definition
Track2ForcePost track2forcePost = new Track2ForcePost();
HttpsPostRequest object for Mag Swipe Force Post transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(track2forcePost);
Mag Swipe Force Post transaction mandatory arguments
For a full description of mandatory and optional values, see Appendix A Definitions of Request Fields
July 2018
Page 130 of 477
Moneris Gateway API - Integration Guide
Table 63: Mag Swipe Force Post transaction object mandatory values
Value
Type
Limits
Set method
Order ID
String
50-character alphanumeric
track2forcePost.setOrderId
(order_id);
Amount
String
9-character decimal
track2forcePost.setAmount
(amount);
Credit card number
String
20-character numeric
track2forcePost.setPan(pan);
OR
OR
OR
Track2 data
40-character numeric
track2forcePost.setTrack2
(track2);
4-character alphanumeric
track2forcePost.setExpDate
(expiry_date);
Expiry date
String
(YYMM format)
POS code
String
2-character numeric
track2forcePost.setPosCode
(pos_code);
Authorization code
String
8-character alphanumeric
track2forcePost.setAuthCode
(auth_code);
Table 64: Mag Swipe Force Post transaction optional values
Value
Type
Limits
Set method
Customer ID
String
50-character alphanumeric
track2forcePost.setCustId
(cust_id);
Status Check
Boolean
true/false
mpgReq.setStatusCheck
(status_check);
Dynamic descriptor
String
20-character alphanumeric
track2forcePost
.setDynamicDescriptor
(dynamic_descriptor);
Sample Mag Swipe Force Post
package Canada;
import JavaAPI.*;
public class TestCanadaTrack2ForcePost
{
public static void main(String[] args)
Page 131 of 477
July 2018
6 Mag Swipe Transaction Set
Sample Mag Swipe Force Post
{
String store_id = "moneris";
String api_token = "hurgle";
java.util.Date createDate = new java.util.Date();
String order_id = "Test"+createDate.getTime();
String amount = "1.00";
String track2 = ";5258968987035454=06061015454001060101?";
String auth_code = "123456";
String processing_country_code = "CA";
boolean status_check = false;
Track2ForcePost track2forcePost = new Track2ForcePost();
track2forcePost.setOrderId(order_id);
track2forcePost.setAmount(amount);
track2forcePost.setTrack2(track2);
track2forcePost.setAuthCode(auth_code);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(track2forcePost);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
//System.out.println("StatusCode = " + receipt.getStatusCode());
//System.out.println("StatusMessage = " + receipt.getStatusMessage());
}
catch (Exception e)
{
e.printStackTrace();
}
}
}
6.5.1 Encrypted Mag Swipe Force Post
The Encrypted Mag Swipe Force Post is used when a merchant obtains the authorization number directly
from the issuer using a phone or any third-party authorization method. This transaction does not
require that an existing order be logged in the Moneris Gateway. However, the credit card must be
swiped or keyed in using a Moneris-provided encrypted mag swipe reader, and the encrypted Track2
July 2018
Page 132 of 477
Moneris Gateway API - Integration Guide
details must be submitted. There are also optional fields that may be submitted such as cust_id and
dynamic_descriptor.
To complete the transaction, the authorization number obtained from the issuer must be entered.
Encrypted Mag Swipe Force Post transaction object definition
EncTrack2Forcepost enctrack2fp = new EncTrack2Forcepost();
HttpsPostRequest object for Encrypted Mag Swipe Force Post transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(enctrack2fp);
Encrypted Mag Swipe Force Post transaction object values
Table 1: Encrypted Mag Swipe Force Post transaction object mandatory values
Value
Type
Limits
Set Method
Order ID
String
50-character alphanumeric
enctrack2fp.setOrderId
(order_id);
Amount
String
9-character decimal
enctrack2fp.setAmount
(amount);
Encrypted Track2 data
String
n/a
enctrack2fp.setEncTrack2
(enc_track2);
POS Code
String
2-character numeric
enctrack2fp.setPosCode(pos_
code);
Device type
String
30-character alphanumeric
enctrack2fp.setDeviceType
(device_type);
Authorization Code
String
8-character alphanumeric
enctrack2fp.setAuthCode
(auth_code);
Table 2: Encrypted Mag Swipe Force Post transaction object optional values
Value
Type
Limits
Set Method
Status Check
Boolean
true/false
mpgReq.setStatusCheck
(status_check);
Customer ID
String
50-character alphanumeric
enctrack2fp.setCustId(cust_
id);
Dynamic descriptor
String
20-character alphanumeric
enctrack2fp
.setDynamicDescriptor
Page 133 of 477
July 2018
6 Mag Swipe Transaction Set
Value
Type
Limits
Set Method
(dynamic_descriptor);
Sample Encrypted Mag Swipe Force Post
package Canada;
import JavaAPI.*;
public class TestCanadaEncTrack2Forcepost
{
public static void main(String[] args)
{
String store_id = "moneris";
String api_token = "hurgle";
java.util.Date createDate = new java.util.Date();
String order_id = "Test"+createDate.getTime();
String cust_id = "my customer id";
String amount = "5.00";
String pos_code = "00";
String device_type = "idtech_bdk";
String auth_code = "123456";
String processing_country_code = "CA";
boolean status_check = false;
String descriptor = "my descriptor";
String enc_track2 = "ENCRYPTEDTRACK2DATA";
EncTrack2Forcepost enctrack2fp = new EncTrack2Forcepost();
enctrack2fp.setOrderId(order_id);
enctrack2fp.setCustId(cust_id);
enctrack2fp.setAmount(amount);
enctrack2fp.setEncTrack2(enc_track2);
enctrack2fp.setPosCode(pos_code);
enctrack2fp.setDeviceType(device_type);
enctrack2fp.setAuthCode(auth_code);
enctrack2fp.setDynamicDescriptor(descriptor);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(enctrack2fp);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
July 2018
Page 134 of 477
Moneris Gateway API - Integration Guide
Sample Encrypted Mag Swipe Force Post
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
System.out.println("MaskedPan = " + receipt.getMaskedPan());
System.out.println("CardLevelResult = " + receipt.getCardLevelResult());
}
catch (Exception e)
{
e.printStackTrace();
}
}
}
6.6 Mag Swipe Purchase Correction
Mag Swipe Purchase Correction transaction object definition
Track2PurchaseCorrection track2purchasecorrection = new
Track2PurchaseCorrection();
HttpsPostRequest object for Mag Swipe Purchase Correction transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(track2purchasecorrection);
Mag Swipe Purchase Correction transaction values
For a full description of mandatory and optional values, see Appendix A Definitions of Request Fields
Table 65: Mag Swipe Purchase Correction transaction object mandatory values
Value
Type
Limits
Set method
Order ID
String
50-character alphanumeric
track2void.setOrderId(order_
id);
Transaction number
String
255-character alphanumeric
track2void.setTxnNumber(txn_
number);
Page 135 of 477
July 2018
6 Mag Swipe Transaction Set
Table 66: Mag Swipe Purchase Correction transaction optional values
Value
Type
Limits
Set method
Customer ID
String
50-character alphanumeric
track2void.setCustId(cust_
id);
Status Check
Boolean
true/false
mpgReq.setStatusCheck
(status_check);
Sample Mag Swipe Purchase Correction
package Canada;
import JavaAPI.*;
public class TestCanadaTrack2PurchaseCorrection
{
public static void main(String[] args)
{
String store_id = "store1";
String api_token = "yesguy";
String order_id = "Test1432090631783";
String txn_number = "16522-0_10";
String cust_id = "my customer id";
String processing_country_code = "CA";
boolean status_check = false;
Track2PurchaseCorrection track2void = new Track2PurchaseCorrection();
track2void.setOrderId(order_id);
track2void.setCustId(cust_id);
track2void.setTxnNumber(txn_number);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(track2void);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
//System.out.println("StatusCode = " + receipt.getStatusCode());
//System.out.println("StatusMessage = " + receipt.getStatusMessage());
July 2018
Page 136 of 477
Moneris Gateway API - Integration Guide
Sample Mag Swipe Purchase Correction
}
catch (Exception e)
{
e.printStackTrace();
}
}
}
6.7 Mag Swipe Refund
Mag Swipe Refund transaction object definition
Track2Refund track2refund = new Track2Refund();
HttpsPostRequest object for Mag Swipe Refund transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(track2refund);
Mag Swipe Refund transaction values
For a full description of mandatory and optional values, see Appendix A Definitions of Request Fields
Table 67: Mag Swipe Refund transaction object mandatory values
Value
Type
Limits
Set method
Order ID
String
50-character alphanumeric
track2refund.setOrderId
(order_id);
Amount
String
9-character decimal
track2refund.setAmount
(amount);
Transaction number
String
255-character alphanumeric
track2refund.setTxnNumber
(txn_number);
Table 68: Mag Swipe Refund transaction optional values
Value
Type
Limits
Set method
Customer ID
String
50-character alphanumeric
track2refund.setCustId(cust_
id);
Status Check
Boolean
true/false
mpgReq.setStatusCheck
(status_check);
Dynamic descriptor
String
20-character alphanumeric
track2refund
.setDynamicDescriptor
Page 137 of 477
July 2018
6 Mag Swipe Transaction Set
Table 68: Mag Swipe Refund transaction optional values (continued)
Value
Type
Limits
Set method
(dynamic_descriptor);
Sample Mag Swipe Refund
package Canada;
import JavaAPI.*;
public class TestCanadaTrack2Refund
{
public static void main(String[] args)
{
String store_id = "store1";
String api_token = "yesguy";
String order_id = "Test1432090722923"; //will prompt user for input
String txn_number = "16524-0_10";
String amount = "1.00";
String dynamic_descriptor = "123456";
String cust_id = "customer id";
String processing_country_code = "CA";
boolean status_check = false;
Track2Refund track2refund = new Track2Refund();
track2refund.setOrderId(order_id);
track2refund.setAmount(amount);
track2refund.setCustId(cust_id);
track2refund.setTxnNumber(txn_number);
track2refund.setDynamicDescriptor(dynamic_descriptor);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(track2refund);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
//System.out.println("StatusCode = " + receipt.getStatusCode());
//System.out.println("StatusMessage = " + receipt.getStatusMessage());
}
July 2018
Page 138 of 477
Moneris Gateway API - Integration Guide
Sample Mag Swipe Refund
catch (Exception e)
{
e.printStackTrace();
}
}
}
6.8 Mag Swipe Independent Refund
NOTE: If you receive a TRANSACTION NOT ALLOWED error, it may mean the Mag
Swipe Independent Refund transaction is not supported on your account. Contact Moneris
to have it temporarily (re-)enabled.
Mag Swipe Independent Refund transaction object definition
Track2IndependentRefund track2indrefund = new Track2IndependentRefund();
HttpsPostRequest object for Mag Swipe Independent Refund transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(track2indrefund);
Mag Swipe Independent Refund transaction values
Table 69: Mag Swipe Independent Refund transaction object mandatory values
Value
Type
Limits
Set method
Order ID
String
50-character alphanumeric
track2indrefund
.setOrderId(order_
id);
Amount
String
9-character decimal
track2indrefund
.setAmount
(amount);
Credit card number
String
20-character numeric
track2indrefund
.setPan(pan);
Track2 data
String
40-character numeric
track2indrefund
.setTrack2
(track2);
Expiry date
String
4-character alphanumeric
track2indrefund
.setExpDate
(expiry_date);
(YYMM format)
POS code
Page 139 of 477
String
2-character numeric
track2indrefund
July 2018
6 Mag Swipe Transaction Set
Table 69: Mag Swipe Independent Refund transaction object mandatory values
Value
Type
Limits
Set method
.setPosCode(pos_
code);
Table 70: Mag Swipe Independent Refund transaction optional values
Value
Type
Limits
Set method
Customer ID
String
50-character alphanumeric
track2indrefund
.setCustId(cust_id);
Dynamic descriptor
String
20-character alphanumeric
track2indrefund
.setDynamicDescriptor
(dynamic_descriptor);
Status Check
Boolean
true/false
mpgReq.setStatusCheck
(status_check);
Sample Mag Swipe Independent Refund
package Canada;
import JavaAPI.*;
public class TestCanadaTrack2IndependentRefund
{
public static void main(String[] args)
{
String store_id = "store1";
String api_token = "yesguy";
java.util.Date createDate = new java.util.Date();
String order_id = "Test"+createDate.getTime();
String cust_id = "Ced_Benson32";
String amount = "5.00";
String track2 = ";5258968987035454=06061015454001060101?";
String pan = "";
String exp_date = "0000";
String pos_code = "00";
String processing_country_code = "CA";
String dynamic_descriptor = "my descriptor";
boolean status_check = false;
Track2IndependentRefund track2indrefund = new Track2IndependentRefund();
track2indrefund.setOrderId(order_id);
track2indrefund.setCustId(cust_id);
track2indrefund.setAmount(amount);
track2indrefund.setTrack2(track2);
track2indrefund.setPan(pan);
track2indrefund.setExpdate(exp_date);
track2indrefund.setPosCode(pos_code);
track2indrefund.setDynamicDescriptor(dynamic_descriptor);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(track2indrefund);
mpgReq.setStatusCheck(status_check);
July 2018
Page 140 of 477
Moneris Gateway API - Integration Guide
Sample Mag Swipe Independent Refund
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
//System.out.println("StatusCode = " + receipt.getStatusCode());
//System.out.println("StatusMessage = " + receipt.getStatusMessage());
}
catch (Exception e)
{
e.printStackTrace();
}
}
}
6.8.1 Encrypted Mag Swipe Independent Refund
The Encrypted Mag Swipe Independent Refund credits a specified amount to the cardholder’s credit
card. The Encrypted Mag Swipe Independent Refund does not require an existing order to be logged in
the Moneris Gateway. However, the credit card must be swiped using the Moneris-provided encrypted
mag swipe reader to provide the encrypted track2 details.
There are also optional fields that may be submitted such as cust_id and dynamic_descriptor. The
transaction format is almost identical to Encrypted Mag Swipe Purchase and Encrypted Mag Swipe
PreAuth.
NOTE:
The Encrypted Mag Swipe Independent Refund transaction may not be supported on
your account. This may yield a TRANSACTION NOT ALLOWED error when attempting the
transaction.
To temporarily enable (or re-enable) the Independent Refund transaction type, contact
Moneris
Page 141 of 477
July 2018
6 Mag Swipe Transaction Set
Encrypted Mag Swipe Independent Refund transaction object definition
EncTrack2IndependentRefund encindrefund = new EncTrack2IndependentRefund();
HttpsPostRequest object for Encrypted Mag Swipe Independent Refund transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(encindrefund);
Encrypted Mag Swipe Independent Refund transaction object values
Table 1: Encrypted Mag Swipe Independent Refund transaction object mandatory values
Value
Type
Limits
Set Method
Order ID
String
50-character alphanumeric
encindrefund.setOrderId
(order_id);
Amount
String
9-character decimal
encindrefund.setAmount
(amount);
Encrypted Track 2 data
String
n/a
encindrefund.setEncTrack2
(enc_track2);
Device Type
String
30-character alphanumeric
encindrefund.setDeviceType
(device_type);
POS Code
String
2-character numeric
encindrefund.setPosCode(pos_
code);
Table 2: Encrypted Mag Swipe Independent Refund transaction object optional values
Value
Type
Limits
Set Method
Status Check
Boolean
true/false
mpgReq.setStatusCheck
(status_check);
Customer ID
String
50-character alphanumeric
encindrefund.setCustId(cust_
id);
Sample Encrypted Mag Swipe Independent Refund
package Canada;
import JavaAPI.*;
public class TestCanadaEncTrack2IndependentRefund
{
public static void main(String[] args)
{
String store_id = "moneris";
July 2018
Page 142 of 477
Moneris Gateway API - Integration Guide
Sample Encrypted Mag Swipe Independent Refund
String api_token = "hurgle";
java.util.Date createDate = new java.util.Date();
String order_id = "Test"+createDate.getTime();
String cust_id = "my customer id";
String amount = "5.00";
String pos_code = "00";
String device_type = "idtech_bdk";
String processing_country_code = "CA";
String enc_track2 = "ENCRYPTEDTRACK2DATA";
EncTrack2IndependentRefund encindrefund = new EncTrack2IndependentRefund();
encindrefund.setOrderId(order_id);
encindrefund.setCustId(cust_id);
encindrefund.setAmount(amount);
encindrefund.setEncTrack2(enc_track2);
encindrefund.setPosCode(pos_code);
encindrefund.setDeviceType(device_type);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(encindrefund);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
System.out.println("MaskedPan = " + receipt.getMaskedPan());
System.out.println("CardLevelResult = " + receipt.getCardLevelResult());
}
catch (Exception e)
{
e.printStackTrace();
}
}
}
Page 143 of 477
July 2018
7 Level 2/3 Transactions
l
l
l
l
7.1
7.2
7.3
7.4
About Level 2/3 Transactions
Level 2/3 Visa Transactions
Level 2/3 MasterCard Transactions
Level 2/3 American Express Transactions
7.1 About Level 2/3 Transactions
The Moneris Gateway API supports passing Level 2/3 purchasing card transaction data for
Visa, MasterCard and American Express corporate cards.
All Level 2/3 transactions use the same Pre-Authorization transaction as described in the topic PreAuthorization (page 18).
7.2 Level 2/3 Visa Transactions
l
l
l
l
l
l
l
l
7.2.1
7.2.2
7.2.3
7.2.5
7.2.4
7.2.6
7.2.7
7.2.8
Level 2/3 Transaction Types for Visa
Level 2/3 Transaction Flow for Visa
VS Completion
VS Force Post
VS Purchase Correction
VS Refund
VS Independent Refund
VS Corpais
7.2.1 Level 2/3 Transaction Types for Visa
This transaction set includes a suite of corporate card financial transactions as well as a transaction that
allows for the passing of Level 2/3 data. Please ensure that Visa Level 2/3 support is enabled on your merchant account. Batch Close, Open Totals and Pre-authorization are identical to the transactions outlined
in the section Basic Transaction Set (page 11).
l
l
When the Pre-authorization response contains CorporateCard equal to true then you can submit
the Visa transactions.
If CorporateCard is false then the card does not support Level 2/3 data and non Level 2/3 transaction are to be used. If the card is not a corporate card, please refer to the section 2 Basic Transaction Set for the appropriate non-corporate card transactions.
NOTE: This transaction set is intended for transactions where Corporate Card is true and
Level 2/3 data will be submitted. If the credit card is found to be a corporate card but you do
July 2018
Page 144 of 477
Moneris Gateway API - Integration Guide
not wish to send any Level 2/3 data then you may submit Visa transactions using the basic
transaction set outlined in 2 Basic Transaction Set.
Pre-authorization– (authorization/pre-authorization)
Pre-authorization verifies and locks funds on the customer’s credit card. The funds are locked
for a specified amount of time, based on the card issuer. To retrieve the funds from a preauth
so that they may be settled in the merchant account a capture must be performed. CorporateCard will return as true if the card supports Level 2/3.
VS Completion – (Capture/Pre-authorization Completion)
Once a Pre-authorization is obtained the funds that are locked need to be retrieved from the
customer’s credit card. The capture retrieves the locked funds and readies them for settlement into the merchant account. Prior to performing a VS Completion, a Pre-authorization
must be performed. Once the transaction is completed, VS Corpais must be used to process
the Level 2/3 data.
VS Force Post – (Force Capture/Pre-authorization Completion)
This transaction is an alternative to VS Completion to obtain the funds locked on Pre-auth
obtained from IVR or equivalent terminal. The VS Force Post retrieves the locked funds and
readies them for settlement in to the merchant account. Once the transaction is completed,
VS Corpais must be used to process the Level 2/3 data.
VS Purchase Correction (Void, Correction)
VS Completion and VS Force Post can be voided the same day* that they occur. A
VS Purchase Correction must be for the full amount of the transaction and will remove any
record of it from the cardholder statement.
VS Refund – (Credit)
A VS Refund can be performed against a VS Completion to refund any part or all of the transaction. Once the transaction is completed, VS Corpais must be used to process the Level 2/3
data.
VS Independent Refund – (Credit)
A VS Independent Refund can be performed against a purchase or a capture to refund any
part, or all of the transaction. Independent refund is used when the originating transaction
was not performed through Moneris Gateway. Once the transaction is completed, VS Corpais
must be used to process the Level 2/3 data.
NOTE: the Independent Refund transaction may or may not be supported on your
account. If you receive a transaction not allowed error when attempting an independent refund, it may mean the transaction is not supported on your account. If you
wish to have the Independent Refund transaction type temporarily enabled (or reenabled), please contact the Service Centre at 1-866-319-7450.
VS Corpais – (Level 2/3 Data)
VS Corpais will contain all the required and optional data fields for Level 2/3 Business to Business data. VS Corpais data can be sent when the card has been identified in the Pre-authorization transaction request as being a corporate card.
Page 145 of 477
July 2018
7 Level 2/3 Transactions
* A VS Purchase Correction can be performed against a transaction as long as the batch that contains the
original transaction remains open. When using the automated closing feature, the batch close occurs
daily between 10 – 11 pm EST.
July 2018
Page 146 of 477
Moneris Gateway API - Integration Guide
7.2.2 Level 2/3 Transaction Flow for Visa
Pre-authorization/Completion Transaction Flow
Page 147 of 477
July 2018
7 Level 2/3 Transactions
Purchase Correction Transaction Flow
July 2018
Page 148 of 477
Moneris Gateway API - Integration Guide
7.2.3 VS Completion
Once a Pre-authorization is obtained, the funds that are locked need to be retrieved from the customer’s
credit card. This VS Completion transaction is used to secure the funds locked by a pre-authorization
transaction and readies them for settlement into the merchant account.
NOTE: Once you have completed this transaction successfully, to submit the complete supplemental level 2/3 data, please proceed to VS Corpais.
VS Completion transaction object definition
VsCompletion vsCompletion = new VsCompletion();
HttpsPostRequest object for VS Completion transaction object
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(vsCompletion);
VS Completion transaction object values
Table 1: VS Completion transaction object mandatory values
Value
Type
Limits
Set Method
Order ID
String
50-character alphanumeric
vsCompletion.setOrderId
(order_id);
Completion amount
String
9-character decimal
vsCompletion.setCompAmount
(comp_amount);
Transaction number
String
255-character alphanumeric
vsCompletion.setTxnNumber
(txn_number);
E-Commerce Indicator
String
1-character alphanumeric
vsCompletion.setCryptType
(crypt);
Table 2: Visa - Corporate Card Common Data - Level 2 Request Fields
Req*
Y
Value
National Tax
Page 149 of 477
Limits
12-character decimal
Set Method
vsCompletion
.setNationalTax
(national_tax);
Description
Must reflect
the amount of
National Tax
(GST or HST)
appearing on
the invoice.
July 2018
7 Level 2/3 Transactions
Req*
Value
Limits
Set Method
Description
Minimum - 0.01
Maximum 999999.99.
Must have 2
decimal places.
Y
Merchant
VAT Registration/Single
Business Reference
20-character alphanumeric
vsCompletion
.setMerchantVatNo
(merchant_vat_no);
Merchant’s Tax
Registration
Number
must be
provided if tax
is included on
the invoice
NOTE: Must
not be all
spaces or all
zeroes
C
Local Tax
12-character decimal
vsCompletion
.setLocalTax
(local_tax);
Must reflect
the amount of
Local Tax (PST
or QST) appearing on the
invoice
If Local Tax
included then
must not be all
spaces or all zeroes; Must be
provided if
Local Tax (PST
or QST) applies
Minimum =
0.01
Maximum =
999999.99
Must have 2
decimal places
C
Local Tax (PST or QST)
July 2018
15-character alpha-
vsCompletion
.setLocalTaxNo
Merchant's
Page 150 of 477
Moneris Gateway API - Integration Guide
Req*
Value
Registration Number
Limits
numeric
Set Method
(local_tax_no);
Description
Local Tax
(PST/QST) Registration Number
Must be
provided if tax
is included on
the invoice; If
Local Tax
included then
must not be all
spaces or all zeroes
Must be
provided if
Local Tax (PST
or QST) applies
C
Customer
VAT Registration Number
13-character alphanumeric
vsCompletion
.setCustomerVatNo
(customer_vat_no);
If the Customer’s Tax
Registration
Number
appears on the
invoice to support tax
exempt transactions it must
be provided
here
C
Customer Code/Customer Reference Identifier (CRI)
16-character alphanumeric
vsCompletion
.setCri(cri);
Value which the
customer may
choose to
provide to the
supplier at the
point of sale –
must be
provided if
given by the
customer
N
Customer Code
17-character alphanumeric
vsCompletion
.setCustomerCode
(customer_code);
Optional customer code
field that will
not be passed
along to Visa,
Page 151 of 477
July 2018
7 Level 2/3 Transactions
Req*
Value
Limits
Set Method
Description
but will be
included on
Moneris reporting
N
Invoice Number
17-character alphanumeric
vsCompletion
.setInvoiceNumber
(invoice_number);
Optional
invoice number
field that will
not be passed
along to Visa,
but will be
included on
Moneris reporting
*Y = Required, N = Optional, C = Conditional
Sample VS Completion
package Level23;
import JavaAPI.*;
public class TestVsCompletion
{
public static void main(String[] args)
{
String store_id = "moneris";
String api_token = "hurgle";
String processing_country_code = "CA";
boolean status_check = false;
String order_id="ord-210916-15:14:46";
String comp_amount="5.00";
String txn_number = "19002-0_11";
String crypt="7";
String national_tax = "1.23";
String merchant_vat_no = "gstno111";
String local_tax = "2.34";
String customer_vat_no = "gstno999";
String cri = "CUST-REF-002";
String customer_code="ccvsfp";
String invoice_number="invsfp";
String local_tax_no="ltaxno";
VsCompletion vsCompletion = new VsCompletion();
vsCompletion.setOrderId(order_id);
vsCompletion.setCompAmount(comp_amount);
vsCompletion.setTxnNumber(txn_number);
vsCompletion.setCryptType(crypt);
vsCompletion.setNationalTax(national_tax);
vsCompletion.setMerchantVatNo(merchant_vat_no);
vsCompletion.setLocalTax(local_tax);
vsCompletion.setCustomerVatNo(customer_vat_no);
vsCompletion.setCri(cri);
vsCompletion.setCustomerCode(customer_code);
vsCompletion.setInvoiceNumber(invoice_number);
vsCompletion.setLocalTaxNo(local_tax_no);
July 2018
Page 152 of 477
Moneris Gateway API - Integration Guide
Sample VS Completion
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(vsCompletion);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
System.out.println("CavvResultCode = " + receipt.getCavvResultCode());
}
catch (Exception e)
{
System.out.println(e);
}
}
}
7.2.4 VS Purchase Correction
The VS Purchase Correction (also known as a "void") transaction is used to cancel a transaction that was
performed in the current batch. No amount is required because a void is always for 100% of the original
transaction. The only transaction that can be voided using VS Purchase Correction is a VS Completion or
VS Force Post. To send a void the order_id and txn_number from the VS Completion/VS Force Post are
required.
VS Purchase Correction transaction object definition
VsPurchaseCorrection vsPurchaseCorrection = new VsPurchaseCorrection();
HttpsPostRequest object for VS Purchase Correction transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(vsPurchaseCorrection);
Page 153 of 477
July 2018
7 Level 2/3 Transactions
VS Purchase Correction transaction object values
Table 1: VS Purchase Correction transaction object mandatory values
Value
Type
Limits
Set Method
Order ID
String
50-character alphanumeric
vsPurchaseCorrection
.setOrderId(order_id);
Transaction number
String
255-character alphanumeric
vsPurchaseCorrection
.setTxnNumber(txn_number);
E-Commerce Indicator
String
1-character alphanumeric
vsPurchaseCorrection
.setCryptType(crypt);
Sample VS Purchase Correction
package Level23;
import JavaAPI.*;
public class TestVsPurchaseCorrection
{
public static void main(String[] args)
{
String store_id = "moneris";
String api_token = "hurgle";
String processing_country_code = "CA";
boolean status_check = false;
String order_id="Test1485208113189";
String txn_number = "39793-0_11";
String crypt="7";
VsPurchaseCorrection vsPurchaseCorrection = new VsPurchaseCorrection();
vsPurchaseCorrection.setOrderId(order_id);
vsPurchaseCorrection.setTxnNumber(txn_number);
vsPurchaseCorrection.setCryptType(crypt);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(vsPurchaseCorrection);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
July 2018
Page 154 of 477
Moneris Gateway API - Integration Guide
Sample VS Purchase Correction
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
System.out.println("CavvResultCode = " + receipt.getCavvResultCode());
}
catch (Exception e)
{
System.out.println(e);
}
}
}
7.2.5 VS Force Post
The VS Force Post transaction is used to secure the funds locked by a pre-authorization transaction performed over IVR or equivalent terminal. When sending a force post request, you will need Order ID,
Amount,Credit Card Number, Expiry Date, E-commerce Indicator and the Authorization Code received in
the pre-authorization response.
NOTE: Once you have completed this transaction successfully, to submit the complete supplemental level 2/3 data, please proceed to VS Corpais.
VS Force Post transaction object definition
VsForcePost vsForcePost = new VsForcePost();
HttpsPostRequest object for VS Force Post transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(vsForcePost);
Page 155 of 477
July 2018
7 Level 2/3 Transactions
VS Force Post transaction object values
Table 1: VS Force Post transaction object mandatory values
Value
Type
Limits
Set Method
Order ID
String
50-character alphanumeric
vsForcePost.setOrderId
(order_id);
Amount
String
9-character decimal
vsForcePost.setAmount
(amount);
Credit card number
String
20-character numeric
vsForcePost.setPan(pan);
Expiry Date
String
4-character numeric
vsForcePost.setExpDate
(expiry_date);
YYMM format
Authorization code
String
8-character alphanumeric
vsForcePost.setAuthCode
(auth_code);
E-commerce Indicator
String
1-character alphanumeric
vsForcePost.setCryptType
(crypt);
Table 2: VS Force Post transaction object optional values
Value
Type
Customer ID
String
Limits
50-character alphanumeric
Set Method
vsForcePost.setCustId(cust_
id);
Table 3: Visa - Corporate Card Common Data - Level 2 Request Fields
Req*
Y
Value
National Tax
Limits
12-character decimal
Set Method
vsForcePost
.setNationalTax
(national_tax);
Description
Must reflect
the amount of
National Tax
(GST or HST)
appearing on
the invoice.
Minimum 0.01 Maximum
- 999999.99.
Must have 2
decimal places.
Y
Merchant
July 2018
20-character alphanumeric
vsForcePost
.setMerchantVatNo
Merchant’s Tax
Page 156 of 477
Moneris Gateway API - Integration Guide
Req*
Value
Limits
Set Method
(merchant_vat_no);
VAT Registration/Single
Business Reference
Description
Registration
Number
must be
provided if tax
is included on
the invoice
NOTE: Must
not be all
spaces or all
zeroes
C
Local Tax
12-character decimal
vsForcePost
.setLocalTax
(local_tax);
Must reflect
the amount of
Local Tax (PST
or QST) appearing on the
invoice
If Local Tax
included then
must not be all
spaces or all zeroes; Must be
provided if
Local Tax (PST
or QST) applies
Minimum =
0.01
Maximum =
999999.99
Must have 2
decimal places
C
Local Tax (PST or QST)
Registration Number
15-character alphanumeric
vsForcePost
.setLocalTaxNo
(local_tax_no);
Merchant's
Local Tax
(PST/QST)
Registration
Number
Must be
provided if tax
Page 157 of 477
July 2018
7 Level 2/3 Transactions
Req*
Value
Limits
Set Method
Description
is included on
the invoice; If
Local Tax
included then
must not be all
spaces or all zeroes
Must be
provided if
Local Tax (PST
or QST) applies
C
Customer
VAT Registration Number
13-character alphanumeric
vsForcePost
.setCustomerVatNo
(customer_vat_no);
If the Customer’s Tax
Registration
Number
appears on the
invoice to support tax
exempt transactions it must
be provided
here
C
Customer Code/Customer Reference Identifier (CRI)
16-character alphanumeric
vsForcePost
.setCri(cri);
Value which
the customer
may choose to
provide to the
supplier at the
point of sale –
must be
provided if
given by the
customer
N
Customer Code
17-character alphanumeric
vsForcePost
.setCustomerCode
(customer_code);
Optional customer code
field that will
not be passed
along to Visa,
but will be
included on
Moneris reporting
N
Invoice Number
17-character alpha-
vsForcePost
Optional
July 2018
Page 158 of 477
Moneris Gateway API - Integration Guide
Req*
Value
Limits
numeric
Set Method
.setInvoiceNumber
(invoice_number);
Description
invoice number
field that will
not be passed
along to Visa,
but will be
included on
Moneris reporting
*Y = Required, N = Optional, C = Conditional
Sample VS Force Post
package Level23;
import JavaAPI.*;
public class TestVsForcePost
{
public static void main(String[] args)
{
String store_id = "moneris";
String api_token = "hurgle";
String processing_country_code = "CA";
boolean status_check = false;
java.util.Date createDate = new java.util.Date();
String order_id="Test"+createDate.getTime();
String cust_id="CUST13343";
String amount="5.00";
String pan="4242424254545454";
String expiry_date="2012"; //YYMM
String auth_code="123456";
String crypt="7";
String national_tax = "1.23";
String merchant_vat_no = "gstno111";
String local_tax = "2.34";
String customer_vat_no = "gstno999";
String cri = "CUST-REF-002";
String customer_code="ccvsfp";
String invoice_number="invsfp";
String local_tax_no="ltaxno";
VsForcePost vsForcePost = new VsForcePost();
vsForcePost.setOrderId(order_id);
vsForcePost.setCustId(cust_id);
vsForcePost.setAmount(amount);
vsForcePost.setPan(pan);
vsForcePost.setExpDate(expiry_date);
vsForcePost.setAuthCode(auth_code);
vsForcePost.setCryptType(crypt);
vsForcePost.setNationalTax(national_tax);
vsForcePost.setMerchantVatNo(merchant_vat_no);
vsForcePost.setLocalTax(local_tax);
vsForcePost.setCustomerVatNo(customer_vat_no);
vsForcePost.setCri(cri);
vsForcePost.setCustomerCode(customer_code);
vsForcePost.setInvoiceNumber(invoice_number);
Page 159 of 477
July 2018
7 Level 2/3 Transactions
Sample VS Force Post
vsForcePost.setLocalTaxNo(local_tax_no);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(vsForcePost);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
System.out.println("CavvResultCode = " + receipt.getCavvResultCode());
}
catch (Exception e)
{
System.out.println(e);
}
}
}
7.2.6 VS Refund
VS Refund will credit a specified amount to the cardholder’s credit card. A refund can be sent up to the
full value of the original VS Completion or VS Force Post. To send a VS Refund you will require the Order
ID and Transaction Number from the original VS Completion or VS Force Post.
NOTE: Once you have completed this transaction successfully, to submit the complete supplemental level 2/3 data, please proceed to VS Corpais.
VS Refund transaction object definition
VsRefund vsRefund = new VsRefund();
HttpsPostRequest object for VS Refund transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
July 2018
Page 160 of 477
Moneris Gateway API - Integration Guide
mpgReq.setTransaction(vsRefund);
VS Refund transaction object values
Table 1: VS Refund transaction object mandatory values
Value
Type
Limits
Set Method
Order ID
String
50-character alphanumeric
vsRefund.setOrderId(order_
id);
Transaction number
String
255-character alphanumeric
vsRefund.setTxnNumber(txn_
number);
Amount
String
9-character decimal
vsRefund.setAmount(amount);
E-Commerce Indicator
String
1-character alphanumeric
vsRefund.setCryptType
(crypt);
Table 2: Visa - Corporate Card Common Data - Level 2 Request Fields
Req*
Y
Value
National Tax
Limits
12-character decimal
Set Method
vsRefund
.setNationalTax
(national_tax);
Description
Must reflect
the amount of
National Tax
(GST or HST)
appearing on
the invoice.
Minimum 0.01 Maximum
- 999999.99.
Must have 2
decimal places.
Y
Merchant
VAT Registration/Single
Business Reference
20-character alphanumeric
vsRefund
.setMerchantVatNo
(merchant_vat_no);
Merchant’s Tax
Registration
Number
must be
provided if tax
is included on
the invoice
NOTE: Must
not be all
Page 161 of 477
July 2018
7 Level 2/3 Transactions
Req*
Value
Limits
Set Method
Description
spaces or all
zeroes
C
Local Tax
12-character decimal
vsRefund
.setLocalTax
(local_tax);
Must reflect
the amount of
Local Tax (PST
or QST) appearing on the
invoice
If Local Tax
included then
must not be all
spaces or all zeroes; Must be
provided if
Local Tax (PST
or QST) applies
Minimum =
0.01
Maximum =
999999.99
Must have 2
decimal places
C
Local Tax (PST or QST)
Registration Number
15-character alphanumeric
vsRefund
.setLocalTaxNo
(local_tax_no);
Merchant's
Local Tax
(PST/QST)
Registration
Number
Must be
provided if tax
is included on
the invoice; If
Local Tax
included then
must not be all
spaces or all zeroes
Must be
provided if
July 2018
Page 162 of 477
Moneris Gateway API - Integration Guide
Req*
Value
Limits
Set Method
Description
Local Tax (PST
or QST) applies
C
Customer
VAT Registration Number
13-character alphanumeric
vsRefund
.setCustomerVatNo
(customer_vat_no);
If the Customer’s Tax
Registration
Number
appears on the
invoice to support tax
exempt transactions it must
be provided
here
C
Customer Code/Customer Reference Identifier (CRI)
16-character alphanumeric
vsRefund
.setCri(cri);
Value which
the customer
may choose to
provide to the
supplier at the
point of sale –
must be
provided if
given by the
customer
N
Customer Code
17-character alphanumeric
vsRefund
.setCustomerCode
(customer_code);
Optional customer code
field that will
not be passed
along to Visa,
but will be
included on
Moneris reporting
N
Invoice Number
17-character alphanumeric
vsRefund
.setInvoiceNumber
(invoice_number);
Optional
invoice number
field that will
not be passed
along to Visa,
but will be
included on
Moneris reporting
*Y = Required, N = Optional, C = Conditional
Page 163 of 477
July 2018
7 Level 2/3 Transactions
Sample VS Refund
package Level23;
import JavaAPI.*;
public class TestVsRefund
{
public static void main(String[] args)
{
String store_id = "moneris";
String api_token = "hurgle";
String processing_country_code = "CA";
boolean status_check = false;
String order_id="Test1485208133961";
String amount="5.00";
String txn_number = "39795-0_11";
String crypt="7";
String national_tax = "1.23";
String merchant_vat_no = "gstno111";
String local_tax = "2.34";
String customer_vat_no = "gstno999";
String cri = "CUST-REF-002";
String customer_code="ccvsfp";
String invoice_number="invsfp";
String local_tax_no="ltaxno";
VsRefund vsRefund = new VsRefund();
vsRefund.setOrderId(order_id);
vsRefund.setAmount(amount);
vsRefund.setTxnNumber(txn_number);
vsRefund.setCryptType(crypt);
vsRefund.setNationalTax(national_tax);
vsRefund.setMerchantVatNo(merchant_vat_no);
vsRefund.setLocalTax(local_tax);
vsRefund.setCustomerVatNo(customer_vat_no);
vsRefund.setCri(cri);
vsRefund.setCustomerCode(customer_code);
vsRefund.setInvoiceNumber(invoice_number);
vsRefund.setLocalTaxNo(local_tax_no);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(vsRefund);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
July 2018
Page 164 of 477
Moneris Gateway API - Integration Guide
Sample VS Refund
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
System.out.println("CavvResultCode = " + receipt.getCavvResultCode());
}
catch (Exception e)
{
System.out.println(e);
}
}
}
7.2.7 VS Independent Refund
VS Independent Refund will credit a specified amount to the cardholder’s credit card. The independent
refund does not require an existing order to be logged in the Moneris Gateway; however, the credit card
number and expiry date will need to be passed. The transaction format is almost identical to a pre-authorization.
NOTE: Once you have completed this transaction successfully, to submit the complete supplemental level 2/3 data, please proceed to VS Corpais.
VS Independent Refund transaction object definition
VsIndependentRefund vsIndependentRefund = new VsIndependentRefund();
HttpsPostRequest object for VS Independent Refund transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(vsIndependentRefund);
VS Independent Refund transaction object values
Table 1: VS Independent Refund transaction object mandatory values
Value
Type
Limits
Set Method
Order ID
String
50-character alphanumeric
vsIndependentRefund
.setOrderId(order_id);
Amount
String
9-character decimal
vsIndependentRefund
.setAmount(amount);
Credit card number
String
20-character numeric
vsIndependentRefund.setPan
(pan);
Page 165 of 477
July 2018
7 Level 2/3 Transactions
Value
Type
Expiry date
String
Limits
4-character numeric
Set Method
vsIndependentRefund
.setExpDate(expiry_date);
YYMM format
E-commerce indicator
String
1-character alphanumeric
vsIndependentRefund
.setCryptType(crypt);
Table 2: VS Independent Refund transaction object optional values
Value
Type
Customer ID
String
Limits
50-character alphanumeric
Set Method
vsIndependentRefund
.setCustId(cust_id);
Table 3: Visa - Corporate Card Common Data - Level 2 Request Fields
Req*
Y
Value
National Tax
Limits
Set Method
Description
12-character decimal
vsIndependentRefund
.setNationalTax
(national_tax);
Must reflect
the amount of
National Tax
(GST or HST)
appearing on
the invoice.
Minimum 0.01 Maximum
- 999999.99.
Must have 2
decimal places.
Y
Merchant
VAT Registration/Single
Business Reference
20-character alphanumeric
vsIndependentRefund
.setMerchantVatNo
(merchant_vat_no);
Merchant’s
Tax Registration Number
must be
provided if tax
is included on
the invoice
NOTE: Must
not be all
spaces or all
zeroes
July 2018
Page 166 of 477
Moneris Gateway API - Integration Guide
Req*
C
Value
Local Tax
Limits
Set Method
Description
12-character decimal
vsIndependentRefund
.setLocalTax(local_
tax);
Must reflect
the amount of
Local Tax (PST
or QST) appearing on the
invoice
If Local Tax
included then
must not be all
spaces or all
zeroes; Must
be provided if
Local Tax (PST
or QST) applies
Minimum =
0.01
Maximum =
999999.99
Must have 2
decimal places
C
Local Tax (PST or QST)
Registration Number
15-character alphanumeric
vsIndependentRefund
.setLocalTaxNo
(local_tax_no);
Merchant's
Local Tax
(PST/QST)
Registration
Number
Must be
provided if tax
is included on
the invoice; If
Local Tax
included then
must not be all
spaces or all
zeroes
Must be
provided if
Local Tax (PST
or QST) applies
Page 167 of 477
July 2018
7 Level 2/3 Transactions
Req*
Value
Limits
Set Method
Description
C
Customer
VAT Registration Number
13-character alphanumeric
vsIndependentRefund
.setCustomerVatNo
(customer_vat_no);
If the Customer’s Tax
Registration
Number
appears on the
invoice to support tax
exempt transactions it must
be provided
here
C
Customer Code/Customer Reference Identifier (CRI)
16-character alphanumeric
vsIndependentRefund
.setCri(cri);
Value which
the customer
may choose to
provide to the
supplier at the
point of sale –
must be
provided if
given by the
customer
N
Customer Code
17-character alphanumeric
vsIndependentRefund
.setCustomerCode
(customer_code);
Optional customer code
field that will
not be passed
along to Visa,
but will be
included on
Moneris
reporting
N
Invoice Number
17-character alphanumeric
vsIndependentRefund
.setInvoiceNumber
(invoice_number);
Optional
invoice number field that
will not be
passed along
to Visa, but will
be included on
Moneris
reporting
*Y = Required, N = Optional, C = Conditional
July 2018
Page 168 of 477
Moneris Gateway API - Integration Guide
Sample VS Independent Refund
package Level23;
import JavaAPI.*;
public class TestVsIndependentRefund
{
public static void main(String[] args)
{
String store_id = "moneris";
String api_token = "hurgle";
String processing_country_code = "CA";
boolean status_check = false;
java.util.Date createDate = new java.util.Date();
String order_id="Test"+createDate.getTime();
String cust_id="CUST13343";
String amount="5.00";
String pan="4242424254545454";
String expiry_date="2012"; //YYMM
String crypt="7";
String national_tax = "1.23";
String merchant_vat_no = "gstno111";
String local_tax = "2.34";
String customer_vat_no = "gstno999";
String cri = "CUST-REF-002";
String customer_code="ccvsfp";
String invoice_number="invsfp";
String local_tax_no="ltaxno";
VsIndependentRefund vsIndependentRefund = new VsIndependentRefund();
vsIndependentRefund.setOrderId(order_id);
vsIndependentRefund.setCustId(cust_id);
vsIndependentRefund.setAmount(amount);
vsIndependentRefund.setPan(pan);
vsIndependentRefund.setExpDate(expiry_date);
vsIndependentRefund.setCryptType(crypt);
vsIndependentRefund.setNationalTax(national_tax);
vsIndependentRefund.setMerchantVatNo(merchant_vat_no);
vsIndependentRefund.setLocalTax(local_tax);
vsIndependentRefund.setCustomerVatNo(customer_vat_no);
vsIndependentRefund.setCri(cri);
vsIndependentRefund.setCustomerCode(customer_code);
vsIndependentRefund.setInvoiceNumber(invoice_number);
vsIndependentRefund.setLocalTaxNo(local_tax_no);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(vsIndependentRefund);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
Page 169 of 477
July 2018
7 Level 2/3 Transactions
Sample VS Independent Refund
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
System.out.println("CavvResultCode = " + receipt.getCavvResultCode());
}
catch (Exception e)
{
System.out.println(e);
}
}
}
7.2.8 VS Corpais
VS Corpais will contain all the required and optional data fields for Level 2/3 Purchasing Card Addendum
data. VS Corpais data can be sent when the card has been identified in the Pre-authorization transaction
request as being a corporate card.
In addition to the Order ID and Transaction number, this transaction also contains two objects:
l
l
VS Purcha – Corporate Card Common Data
VS Purchl – Line Item Details
VS Corpais request must be preceded by a financial transaction (VS Completion, VS Force Post, VS
Refund, VS Independent Refund) and the Corporate Card flag must be set to “true” in the Pre-authorization response.
VS Corpais transaction object definition
VsCorpais vsCorpais = new VsCorpais();
HttpsPostRequest object for VS Corpais transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(vsCorpais);
July 2018
Page 170 of 477
Moneris Gateway API - Integration Guide
VS Corpais transaction object values
Table 1: VS Corpais transaction object mandatory values
Value
Type
Limits
Set Method
Order ID
String
50-character alphanumeric
vsCorpais.setOrderId(order_
id);
Transaction number
String
255-character alphanumeric
vsCorpais.setTxnNumber(txn_
number);
vsPurcha
Object
n/a
VsPurcha vsPurcha = new
VsPurcha();
vsCorpais.setVsPurch
(vsPurcha,vsPurchl);
For a list of the variables that appear in
this object, see the
table below
vsPurchl
Object
VsPurchl vsPurchl = new
VsPurchl();
n/a
For a list of the variables that appear in
this object, see the
table below
vsCorpais.setVsPurch
(vsPurcha,vsPurchl);
*Y = Required, N = Optional, C = Conditional
7.2.8.1 VS Purcha - Corporate Card Common Data
VS Corpais transactions use the VS Purcha object to contain Level 2 data.
Table 1: Corporate Card Common Data - Level 2 Request Fields - VSPurcha
Req*
C
Value
Buyer Name
Limits
30-character
alphanumeric
Set Method
vsPurcha.setBuyerName
(buyer_name);
Description
Buyer/Recipient
Name
NOTE: Name
required by CRA on
transactions >$150
C
Local Tax Rate
Page 171 of 477
4-character
decimal
vsPurcha
.setLocalTaxRate(local_
tax_rate);.
Indicates the
detailed tax rate
applied in relationship to a local
tax amount
July 2018
7 Level 2/3 Transactions
Req*
Value
Limits
Set Method
Description
EXAMPLE: 8% PST
should be 8.0
Minimum = 0.01
Maximum = 99.99
NOTE: Must be
provided if Local
Tax (PST or QST)
applies.
N
Duty Amount
9-character
decimal
vsPurcha.setDutyAmount
(duty_amount);
Duty on total purchase amount
A minus sign
means 'amount is a
credit', plus sign or
no sign means
'amount is a debit'
maximum without
sign is 999999.99
N
Invoice Discount
Treatment
1-character
numeric
vsPurcha
.setDiscountTreatment
(discount_treatment);
Indicates how the
merchant is managing discounts
Must be one of the
following values:
0 - if no invoice level
discounts apply for this
invoice
1 - if Tax was calculated on Post-Discount totals
2 - if Tax was calculated on Pre-Discount
totals
N
Invoice Level Discount Amount
July 2018
9-character
decimal
vsPurcha.setDiscountAmt
(discount_amt);
Amount of discount (if provided
at the invoice level
according to the
Invoice Discount
Treatment)
Page 172 of 477
Moneris Gateway API - Integration Guide
Req*
Value
Limits
Set Method
Description
Must be non-zero
if Invoice Discount
Treatment is 1 or 2
Minimum amount
is 0.00 and maximum is 999999.99
C
Ship To Postal
Code / Zip Code
10-character
alphanumeric
vsPurcha
.setShipToPostalCode
(ship_to_pos_code);
The postal code or
zip code for the
destination where
goods will be
delivered
NOTE: Required if
shipment is
involved
Full alpha postal
code - Valid
ANANAN
format required if
shipping to an
address within
Canada
C
Ship From Postal
Code / Zip Code
10-character
alphanumeric
vsPurcha
.setShipFromPostalCode
(ship_from_pos_code);
The postal code or
zip code from
which items were
shipped
For Canadian
addresses,requires
full alpha postal
code for the merchant with Valid
ANANAN
format
C
Destination
Country Code
2-character alphanumeric
vsPurcha.setDesCouCode
(des_cou_code);
Code of country
where purchased
goods will be
delivered
Use ISO 3166-1
alpha-2 format
Page 173 of 477
July 2018
7 Level 2/3 Transactions
Req*
Value
Limits
Set Method
Description
NOTE: Required if
it appears on the
invoice for an international transaction
Y
Unique VAT
Invoice Reference Number
25-character
alphanumeric
vsPurcha.setVatRefNum
(vat_ref_num);
Unique Value
Added Tax Invoice
Reference Number
Must be populated
with the invoice
number and this
cannot be all
spaces or zeroes
Y
Tax Treatment
1-character alphanumeric
vsPurcha
.setTaxTreatment(tax_
treatment);
Must be one of the
following values:
0 = Net Prices with tax
calculated at line item
level;
1 = Net Prices with tax
calculated at invoice
level;
2 = Gross prices given
with tax information
provided at line item
level;
3 = Gross prices given
with tax information
provided at invoice
level;
4 = No tax applies
(small merchant) on
the invoice for the
transaction
N
Freight/Shipping
Amount (Ship
Amount)
9-character
decimal
vsPurcha
.setFreightAmount
(freight_amount);
Freight charges on
total purchase
If shipping is not
provided as a line
item it must be
provided here, if
applicable
Signed monetary
July 2018
Page 174 of 477
Moneris Gateway API - Integration Guide
Req*
Value
Limits
Set Method
Description
amount:
Minus (-) sign
means 'amount is a
credit',
Plus (+) sign or no
sign means
'amount is a debit'
Maximum without
sign is 999999.99
C
GST HST Freight
Rate
4-character
decimal
vsPurcha
.setGstHstFreightRate
(gst_hst_freight_rate);
Rate of GST
(excludes PST) or
HST charged on the
shipping amount
(in accordance with
the Tax Treatment)
If Freight/Shipping
Amount is
provided then this
(National GST or
HST) tax rate must
be provided.
Monetary amount,
maximum is 99.99.
Such as 13% HST is
13.00
C
GST HST Freight
Amount
9-character
decimal
vsPurcha
.setGstHstFreightAmount
(gst_hst_freight_
amount);
Amount of GST
(excludes PST) or
HST charged on the
shipping amount
If Freight/Shipping
Amount is
provided then this
(National GST or
HST) tax amount
must be provided if
taxTreatment is 0
or 2
Signed monetary
amount: maximum
without sign is
Page 175 of 477
July 2018
7 Level 2/3 Transactions
Req*
Value
Limits
Set Method
Description
999999.99.
7.2.8.2 VS Purchl - Line Item Details
VS Corpais transactions use the VS Purchl object to contain Level 3 data.
Line Item Details for VS Purchl
String[] item_com_code = {"X3101", "X84802"};
String[] product_code = {"CHR123", "DDSK200"};
String[] item_description = {"Office Chair", "Disk Drive"};
String[] item_quantity = {"3", "1"};
String[] item_uom = {"EA", "EA"};
String[] unit_cost = {"0.20", "0.40"};
String[] vat_tax_amt = {"0.00", "0.00"};
String[] vat_tax_rate = {"13.00", "13.00"};
String[] discount_treatmentL = {"0", "0"};
String[] discount_amtL = {"0.00", "0.00"};
Setting VS Purchl Line Item Details
vsPurchl.setVsPurchl(item_com_code[0], product_code[0], item_description[0],
item_quantity[0], item_uom[0], unit_cost[0], vat_tax_amt[0], vat_tax_rate[0],
discount_treatmentL[0], discount_amtL[0]);
vsPurchl.setVsPurchl(item_com_code[1], product_code[1], item_description[1],
item_quantity[1], item_uom[1], unit_cost[1], vat_tax_amt[1], vat_tax_rate[1],
discount_treatmentL[1], discount_amtL[1]);
Table 1: Corporate Card Common Data - Level 3 Request Fields - VSPurchl
Req*
Value
Limits
Variable/Field
Description
C
Item Commodity
Code
12-character alphanumeric
item_com_code
Line item Comodity Code (if this
field is not sent,
then Product Code
must be sent)
Y
Product Code
12-character alphanumeric
product_code
Product code for
this line item – merchant’s product
July 2018
Page 176 of 477
Moneris Gateway API - Integration Guide
Req*
Value
Limits
Variable/Field
Description
code, manufacturer’s
product code or
buyer’s product
code
Typically this will
be the SKU or identifier by which the
merchant tracks
and prices the item
or service
This should always
be provided for
every line item
Y
Item Description
35-character alphanumeric
item_description
Line item description
Y
Item Quantity
12-character decimal
item_quantity
Quantity invoiced
for this line item
Up to 4 decimal
places supported,
whole numbers
are accepted
Minimum = 0.0001
Maximum =
999999999999
Y
Y
Item Unit of
Measure
2-character alphanumeric
item_uom
Item Unit Cost
12-character decimal
unit_cost
Unit of measure
Use ANSI X-12 EDI
Allowable Units of
Measure and
Codes
Line item cost per
unit
2-4 decimal places
accepted
Minimum = 0.0001
Maximum =
999999.9999
Page 177 of 477
July 2018
7 Level 2/3 Transactions
Req*
N
Value
VAT Tax Amount
Limits
12-character decimal
Variable/Field
vat_tax_amt
Description
Any value-added
tax or other sales
tax amount
Must have 2
decimal places
Minimum = 0.01
Maximum =
999999.99
N
VAT Tax Rate
4-character decimal
vat_tax_rate
Sales tax rate
EXAMPLE: 8% PST
should be 8.0
maximum 99.99
Y
Discount Treatment
1-character numeric
discount_treatmentL
Must be one of the
following values:
0 if no invoice level discounts apply for this
invoice
1 if Tax was calculated
on Post-Discount totals
2 if Tax was calculated
on Pre-Discount totals
C
Discount
Amount
12-character decimal
discount_amtL
Amount of discount, if provided
for this line item
according to the
Line Item Discount
Treatment
Must be non-zero
if Line Item Discount Treatment is
1 or 2
Must have 2
decimal places
Minimum = 0.01
Maximum =
999999.99
July 2018
Page 178 of 477
Moneris Gateway API - Integration Guide
7.2.8.3 Sample Code for VS Corpais
Sample VS Corpais
package Level23;
import JavaAPI.*;
public class TestVsCorpais
{
public static void main(String[] args)
{
String store_id = "moneris";
String api_token = "hurgle";
String processing_country_code = "CA";
boolean status_check = false;
String order_id="Test1485208069127";
String txn_number="39791-0_11";
String buyer_name = "Buyer Manager";
String local_tax_rate = "13.00";
String duty_amount = "0.00";
String discount_treatment = "0";
String discount_amt = "0.00";
String freight_amount = "0.20";
String ship_to_pos_code = "M8X 2W8";
String ship_from_pos_code = "M1K 2Y7";
String des_cou_code = "CAN";
String vat_ref_num = "VAT12345";
String tax_treatment = "3";//3 = Gross prices given with tax information provided at invoice level
String gst_hst_freight_amount = "0.00";
String gst_hst_freight_rate = "13.00";
String[] item_com_code = {"X3101", "X84802"};
String[] product_code = {"CHR123", "DDSK200"};
String[] item_description = {"Office Chair", "Disk Drive"};
String[] item_quantity = {"3", "1"};
String[] item_uom = {"EA", "EA"};
String[] unit_cost = {"0.20", "0.40"};
String[] vat_tax_amt = {"0.00", "0.00"};
String[] vat_tax_rate = {"13.00", "13.00"};
String[] discount_treatmentL = {"0", "0"};
String[] discount_amtL = {"0.00", "0.00"};
//Create and set VsPurcha
VsPurcha vsPurcha = new VsPurcha();
vsPurcha.setBuyerName(buyer_name);
vsPurcha.setLocalTaxRate(local_tax_rate);
vsPurcha.setDutyAmount(duty_amount);
vsPurcha.setDiscountTreatment(discount_treatment);
vsPurcha.setDiscountAmt(discount_amt);
vsPurcha.setFreightAmount(freight_amount);
vsPurcha.setShipToPostalCode(ship_to_pos_code);
vsPurcha.setShipFromPostalCode(ship_from_pos_code);
vsPurcha.setDesCouCode(des_cou_code);
vsPurcha.setVatRefNum(vat_ref_num);
vsPurcha.setTaxTreatment(tax_treatment);
vsPurcha.setGstHstFreightAmount(gst_hst_freight_amount);
vsPurcha.setGstHstFreightRate(gst_hst_freight_rate);
//Create and set VsPurchl
VsPurchl vsPurchl = new VsPurchl();
vsPurchl.setVsPurchl(item_com_code[0], product_code[0], item_description[0], item_quantity[0],
item_uom[0], unit_cost[0], vat_tax_amt[0], vat_tax_rate[0], discount_treatmentL[0], discount_
amtL[0]);
Page 179 of 477
July 2018
7 Level 2/3 Transactions
Sample VS Corpais
vsPurchl.setVsPurchl(item_com_code[1], product_code[1], item_description[1], item_quantity[1],
item_uom[1], unit_cost[1], vat_tax_amt[1], vat_tax_rate[1], discount_treatmentL[1], discount_
amtL[1]);
VsCorpais vsCorpais = new VsCorpais();
vsCorpais.setOrderId(order_id);
vsCorpais.setTxnNumber(txn_number);
vsCorpais.setVsPurch(vsPurcha, vsPurchl);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(vsCorpais);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
System.out.println("CavvResultCode = " + receipt.getCavvResultCode());
}
catch (Exception e)
{
System.out.println(e);
}
}
}
7.3 Level 2/3 MasterCard Transactions
l
l
l
l
l
l
l
l
7.3.1
7.3.2
7.3.3
7.3.4
7.3.5
7.3.6
7.3.7
7.3.8
July 2018
Level 2/3 Transaction Types for MasterCard
Level 2/3 Transaction Flow for MasterCard
MC Completion
MC Force Post
MC Purchase Correction
MC Refund
MC Independent Refund
MC Corpais - Corporate Card Common Data with Line Item Details
Page 180 of 477
Moneris Gateway API - Integration Guide
7.3.1 Level 2/3 Transaction Types for MasterCard
This transaction set includes a suite of corporate card financial transactions as well as a transaction that
allows for the passing of Level 2/3 data. Please ensure MC Level 2/3 processing support is enabled on
your merchant account. Batch Close, Open Totals and Pre-authorization are identical to the transactions
outlined in the section Basic Transaction Set (page 11).
When the Preauth response contains CorporateCard equal to true then you can submit the MC transactions.
If CorporateCard is false then the card does not support Level 2/3 data and non Level 2/3 transaction are
to be used. If the card is not a corporate card, please refer to section 4 for the appropriate non-corporate
card transactions.
NOTE: This transaction set is intended for transactions where Corporate Card is true and
Level 2/3 data will be submitted. If the credit card is found to be a corporate card but you do
not wish to send any Level 2/3 data then you may submit MC transactions using the transaction set outlined in Basic Transaction Set (page 11).
Pre-auth – (authorization/pre-authorization)
The pre-auth verifies and locks funds on the customer’s credit card. The funds are locked for a
specified amount of time, based on the card issuer. To retrieve the funds from a pre-auth so
that they may be settled in the merchant account a capture must be performed. Level 2/3
data submission is not supported as part of a pre-auth as a pre-auth is not settled. When CorporateCard is returned true then Level 2/3 data may be submitted.
MC Completion – (Capture/Preauth Completion)
Once a Pre-authorization is obtained the funds that are locked need to be retrieved from the
customer’s credit card. The capture retrieves the locked funds and readies them for settlement in to the merchant account. Prior to performing an MCCompletion a Pre-auth must
be performed.
MC Force Post – (Force Capture/Preauth Completion)
This transaction is an alternative to MC Completion to obtain the funds locked on Preauth
obtained from IVR or equivalent terminal. The MC Force Post requires that the original Preauthorization’s auth code is provided and it retrieves the locked funds and readies them for
settlement in to the merchant account.
MC Purchase Correction – (Void, Correction)
MC Completions can be voided the same day* that they occur. A void must be for the full
amount of the transaction and will remove any record of it from the cardholder statement. *
An MC Purchase Correction can be performed against a transaction as long as the batch that
contains the original transaction remains open. When using the automated closing feature
batch close occurs daily between 10 – 11 pm EST.
MC Refund – (Credit)
A MC Refund can be performed against an MC Completion or MC Force Post to refund an
amount less than or equal to the amount of the original transaction.
Page 181 of 477
July 2018
7 Level 2/3 Transactions
MC Independent Refund – (Credit)
A MC Indpendent Refund can be performed against an completion to refund any part, or all
of the transaction. Independent refund is used when the originating transaction was not performed through Moneris Gateway. Please note, the MC Independent Refund transaction
may or may not be supported on your account. If you receive a transaction not allowed error
when attempting an MC Independent Refund, it may mean the transaction is not supported
on your account. If you wish to have the MC Independent Refund transaction type temporarily enabled (or re-enabled), please contact the Service Centre at 1-866-319-7450.
MC Corpais Common Line Item – (Level 2/3 Data)
MC Corpais Common Line Item will contain the entire required and optional data field for
Level 2/3 data. MCCorpais Common Line Item data can be sent when the card has been identified in the transaction request as being a corporate card. This transaction supports multiple
data types and combinations:
l
July 2018
Purchasing Card Data:
l Corporate card common data with Line Item Details
Page 182 of 477
Moneris Gateway API - Integration Guide
7.3.2 Level 2/3 Transaction Flow for MasterCard
Pre-authorization/Completion Transaction Flow
Page 183 of 477
July 2018
7 Level 2/3 Transactions
Purchase Correction Transaction Flow
July 2018
Page 184 of 477
Moneris Gateway API - Integration Guide
7.3.3 MC Completion
The MC Completion transaction is used to secure the funds locked by a pre-authorization transaction.
When sending a capture request you will need two pieces of information from the original pre-authorization– the Order ID and the transaction number from the returned response.
Once you have completed this transaction successfully, to submit the complete supplemental level 2/3 data, please proceed to MC Corpais.
MC Completion transaction object definition
McCompletion mcCompletion = new McCompletion();
HttpsPostRequest object for MC Completion transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(mcCompletion);
MC Completion transaction object values
Table 1: MC Completion transaction object mandatory values
Value
Type
Limits
Set Method
Order ID
String
50-character alphanumeric
mcCompletion.setOrderId
(order_id);
Completion amount
String
9-character decimal
mcCompletion.setCompAmount
(comp_amount);
Transaction number
String
255-character alphanumeric
mcCompletion.setTxnNumber
(txn_number);
Merchant reference
number
String
19-character alphanumeric
mcCompletion
.setMerchantRefNo(merchant_
ref_no);
E-commerce indicator
String
1-character alphanumeric
mcCompletion.setCryptType
(crypt);
Sample MC Completion
package Level23;
import JavaAPI.*;
Page 185 of 477
July 2018
7 Level 2/3 Transactions
Sample MC Completion
public class TestMcCompletion
{
public static void main(String[] args)
{
String store_id = "moneris";
String api_token = "hurgle";
String processing_country_code = "CA";
boolean status_check = false;
String order_id="Test1485206444761";
String comp_amount="1.00";
String txn_number="39777-0_11";
String crypt="7";
String merchant_ref_no = "319038";
McCompletion mcCompletion = new McCompletion();
mcCompletion.setOrderId(order_id);
mcCompletion.setCompAmount(comp_amount);
mcCompletion.setTxnNumber(txn_number);
mcCompletion.setCryptType(crypt);
mcCompletion.setMerchantRefNo(merchant_ref_no);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(mcCompletion);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
System.out.println("CavvResultCode = " + receipt.getCavvResultCode());
}
catch (Exception e)
{
System.out.println(e);
}
}
}
July 2018
Page 186 of 477
Moneris Gateway API - Integration Guide
7.3.4 MC Force Post
MC Force Post transaction is used to secure the funds locked by a pre-authorization transaction performed over IVR or equivalent terminal`. When sending a force post request, you will need order_id,
amount, pan (card number), expiry date, crypt type and the authorization code received in the preauthorization response.
MC Force Post transaction object definition
McForcePost mcforcepost= new McForcePost();
HttpsPostRequest object for MC Force Post transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(mcforcepost);
MC Force Post transaction object values
Table 1: MC Force Post transaction object mandatory values
Value
Type
Limits
Set Method
Order ID
String
50-character alphanumeric
mcforcepost.setOrderId
(order_id);
Amount
String
9-character decimal
mcforcepost.setAmount
(amount);
Credit card number
String
20-character alphanumeric
mcforcepost.setPan(pan);
Expiry date
String
4-character alphanumeric
mcforcepost.setExpDate
(expiry_date);
(YYMM format)
Authorization code
String
8-character alphanumeric
mcforcepost.setAuthCode
(auth_code);
E-commerce indicator
String
1-character alphanumeric
mcforcepost.setCryptType
(crypt);
Merchant reference
number
String
19-character alphanumeric
mcforcepost.setMerchantRefNo
(merchant_ref_no);
Page 187 of 477
July 2018
7 Level 2/3 Transactions
Table 2: MC Force Post transaction object optional values
Value
Customer ID
Type
String
Limits
50-character alphanumeric
Set Method
mcforcepost.setCustId(cust_
id);
Sample MC Force Post
package Level23;
import JavaAPI.*;
public class TestMcForcePost
{
public static void main(String[] args)
{
String store_id = "moneris";
String api_token = "hurgle";
String processing_country_code = "CA";
boolean status_check = false;
java.util.Date createDate = new java.util.Date();
String order_id="Test"+createDate.getTime();
String cust_id = "CUST13343";
String amount = "5.00";
String pan = "5454545442424242";
String expiry_date = "1912"; //YYMM
String auth_code = "123456";
String crypt = "7";
String merchant_ref_no = "319038";
McForcePost mcforcepost = new McForcePost();
mcforcepost.setOrderId(order_id);
mcforcepost.setCustId(cust_id);
mcforcepost.setAmount(amount);
mcforcepost.setPan(pan);
mcforcepost.setExpDate(expiry_date);
mcforcepost.setAuthCode(auth_code);
mcforcepost.setCryptType(crypt);
mcforcepost.setMerchantRefNo(merchant_ref_no);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(mcforcepost);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
July 2018
Page 188 of 477
Moneris Gateway API - Integration Guide
Sample MC Force Post
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
System.out.println("CavvResultCode = " + receipt.getCavvResultCode());
}
catch (Exception e)
{
System.out.println(e);
}
}
}
7.3.5 MC Purchase Correction
The MC Purchase Correction (void) transaction is used to cancel a transaction that was performed in the
current batch. No amount is required because a void is always for 100% of the original transaction. The
only transaction that can be voided is completion. To send a void, the Order ID and Transaction Number
from the MC Completion or MC Force Post are required.
MC Purchase Correction transaction object definition
McPurchaseCorrection mcpurchasecorrection = new McPurchaseCorrection();
HttpsPostRequest object for MC Purchase Correction transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(mcpurchasecorrection);
MC Purchase Correction transaction object values
Table 1: MC Purchase Correction transaction object mandatory values
Value
Type
Limits
Set Method
Order ID
String
50-character alphanumeric
mcpurchasecorrection
.setOrderId(order_id);
Transaction number
String
255-character alphanumeric
mcpurchasecorrection
.setTxnNumber(txn_number);
E-commerce indicator
String
1-character alpha-
mcpurchasecorrection
.setCryptType(crypt);
Page 189 of 477
July 2018
7 Level 2/3 Transactions
Value
Type
Limits
Set Method
numeric
July 2018
Page 190 of 477
Moneris Gateway API - Integration Guide
Sample MC Purchase Correction
package Level23;
import JavaAPI.*;
public class TestMcPurchaseCorrection
{
public static void main(String[] args)
{
String store_id = "moneris";
String api_token = "hurgle";
String processing_country_code = "CA";
boolean status_check = false;
String order_id="Test1485207871499";
String txn_number="660117311902017023164431860-0_11";
String crypt="7";
McPurchaseCorrection mcpurchasecorrection = new McPurchaseCorrection();
mcpurchasecorrection.setOrderId(order_id);
mcpurchasecorrection.setTxnNumber(txn_number);
mcpurchasecorrection.setCryptType(crypt);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(mcpurchasecorrection);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
System.out.println("CavvResultCode = " + receipt.getCavvResultCode());
}
catch (Exception e)
{
System.out.println(e);
}
}
}
Page 191 of 477
July 2018
7 Level 2/3 Transactions
7.3.6 MC Refund
The MC Refund will credit a specified amount to the cardholder’s credit card. A refund can be sent up to
the full value of the original capture. To send a refund you will require the Order ID and Transaction Number from the original MC Completion or MC Force Post.
MC Refund transaction object definition
McRefund mcRefund = new McRefund();
HttpsPostRequest object for MC Refund transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(mcRefund);
MC Refund transaction object values
Table 1: MC Refund transaction object mandatory values
Value
Type
Limits
Set Method
Order ID
String
50-character alphanumeric
mcRefund.setOrderId(order_
id);
Amount
String
9-character decimal
mcRefund.setAmount(amount);
Transaction number
String
255-character alphanumeric
mcRefund.setTxnNumber(txn_
number);
E-commerce indicator
String
1-character alphanumeric
mcRefund.setCryptType
(crypt);
Merchant reference
number
String
19-character alphanumeric
mcRefund.setMerchantRefNo
(merchant_ref_no);
Sample MC Refund
package Level23;
import JavaAPI.*;
public class TestMcRefund
{
public static void main(String[] args)
{
String store_id = "moneris";
String api_token = "hurgle";
String processing_country_code = "CA";
July 2018
Page 192 of 477
Moneris Gateway API - Integration Guide
Sample MC Refund
boolean status_check = false;
String order_id="Test1485207913048";
String amount="5.00";
String txn_number="660117311902017023164513403-0_11";
String crypt="7";
String merchant_ref_no = "319038";
McRefund mcRefund = new McRefund();
mcRefund.setOrderId(order_id);
mcRefund.setAmount(amount);
mcRefund.setTxnNumber(txn_number);
mcRefund.setCryptType(crypt);
mcRefund.setMerchantRefNo(merchant_ref_no);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(mcRefund);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
System.out.println("CavvResultCode = " + receipt.getCavvResultCode());
}
catch (Exception e)
{
System.out.println(e);
}
}
}
7.3.7 MC Independent Refund
MC Independent Refund is used when the originating transaction was not performed through Moneris
Gateway and does not require an existing order to be logged in the Moneris Gateway; however, the
credit card number and the expiry date will need to be passed. The transaction format is almost identical
to a purchase or a pre-authorization.
Page 193 of 477
July 2018
7 Level 2/3 Transactions
NOTE: Independent refund transactions are not supported on all accounts. If you receive a
transaction not allowed error when attempting an independent refund transaction, it may
mean the feature is not supported on your account. To have Independent Refund transaction functionality temporarily enabled (or re-enabled), please contact the MonerisCustomer Service Centre at 1-866-319-7450.
Once you have completed this transaction successfully, to submit the complete supplemental level 2/3 data, please proceed to MC Corpais.
MC Independent Refund transaction object definition
McIndependentRefund mcindrefund = new McIndependentRefund();
HttpsPostRequest object for MC Independent Refund transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(mcindrefund);
MC Independent Refund transaction object values
Table 1: MC Independent Refund transaction object mandatory values
Value
Type
Limits
Set Method
Order ID
String
50-character alphanumeric
mcindrefund.setOrderId
(order_id);
Amount
String
9-character decimal
mcindrefund.setAmount
(amount);
E-commerce indicator
String
1-character alphanumeric
mcindrefund.setCryptType
(crypt);
Credit card number
String
20-character numeric
mcindrefund.setPan(pan);
Expiry date
String
4-character numeric
mcindrefund.setExpDate
(expiry_date);
(YYMM format)
Merchant reference
number
July 2018
String
19-character alphanumeric
mcindrefund.setMerchantRefNo
(merchant_ref_no);
Page 194 of 477
Moneris Gateway API - Integration Guide
Table 2: MC Independent Refund transaction object optional values
Value
Customer ID
Type
String
Limits
50-character alphanumeric
Set Method
mcindrefund.setCustId(cust_
id);
Sample MC Independent Refund
package Level23;
import JavaAPI.*;
public class TestMcIndependentRefund
{
public static void main(String[] args)
{
String store_id = "moneris";
String api_token = "hurgle";
String processing_country_code = "CA";
boolean status_check = false;
java.util.Date createDate = new java.util.Date();
String order_id="Test"+createDate.getTime();
String cust_id = "CUST13343";
String amount = "5.00";
String pan = "5454545442424242";
String expiry_date = "1912"; //YYMM
String crypt = "7";
String merchant_ref_no = "319038";
McIndependentRefund mcindrefund = new McIndependentRefund();
mcindrefund.setOrderId(order_id);
mcindrefund.setCustId(cust_id);
mcindrefund.setAmount(amount);
mcindrefund.setPan(pan);
mcindrefund.setExpDate(expiry_date);
mcindrefund.setCryptType(crypt);
mcindrefund.setMerchantRefNo(merchant_ref_no);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(mcindrefund);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
Page 195 of 477
July 2018
7 Level 2/3 Transactions
Sample MC Independent Refund
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
System.out.println("CavvResultCode = " + receipt.getCavvResultCode());
}
catch (Exception e)
{
System.out.println(e);
}
}
}
7.3.8 MC Corpais - Corporate Card Common Data with Line Item Details
This transaction example includes the following elements for Level 2 and 3 purchasing card corporate
card data processing:
l
l
Corporate Card Common Data (MC Corpac)
l only 1 set of MC Corpac fields can be submitted
l this data set includes data elements that apply to the overall order, e.g., the total overall
taxes
Line Item Details (MC Corpal)
l 1-998 counts of MC Corpal line items can be submitted
l This data set includes the details about each individual item or service purchased
The MC Corpais request must be preceded by a financial transaction (MC Completion, MC Force Post,
MC Refund, MC Independent Refund) and the Corporate Card flag must be set to “true” in the Preauthorization response. The MC Corpais request will need to contain the Order ID of the financial transaction as well as the Transaction Number.
In addition, MC Corpais has a tax array object that can be sent via the Tax fields in MC Corpac and
MC Corpal. For more about the tax array object, see 7.3.8.3 Tax Array Object - MC Corpais.
For descriptions of the Level 2/3 fields, please see Definition of Request Fields for Level 2/3 - MasterCard
(page 419).
MC Corpais transaction object definition
McCorpais mcCorpais = new McCorpais();
HttpsPostRequest object for MC Corpais transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(mcCorpais);
July 2018
Page 196 of 477
Moneris Gateway API - Integration Guide
MC Corpais transaction object values
Table 1: MC Corpais transaction object mandatory values
Value
Type
Limits
Set Method
Order ID
String
50-character alphanumeric
mcCorpais.setOrderId(order_
id);
Transaction number
String
255-character alphanumeric
mcCorpais.setTxnNumber(txn_
number);
MCCorpac
Object
n/a
mcCorpac.setMcCorpac
(mcCorpac);
MC Corpal
Object
n/a
mcCorpais.setMcCorpal
(mcCorpal);
*Y = Required, N = Optional, C = Conditional
7.3.8.1 MC Corpac - Corporate Card Common Data
Table 1: Corporate Card Common Data - Level 2 Request Fields - MCCorpac
Req*
Value
Limits
Set Method
Description
N
AustinTetra
Number
15-character alphanumeric
mcCorpac
.setAustinTetraNumber
(austin_tetra_number);
The Austin-Tetra Number
assigned to the card
acceptor
N
NAICS
Code
15-character alphanumeric
mcCorpac.setNaicsCode
(naics_code);
North American Industry
Classification System
(NAICS) code assigned to
the card acceptor
N
Customer
Code
25-character alphanumeric
mcCorpac.setCustomerCode1
(customer_code1_c);
A control number, such as
purchase order number,
project number, department allocation number or
name that the purchaser
supplied the merchant
Left-justified; may be
spaces
N
Unique
Invoice
Page 197 of 477
17-character alpha-
mcCorpac
.setUniqueInvoiceNumber
Unique number associated
with the individual trans-
July 2018
7 Level 2/3 Transactions
Re-
Value
Limits
Number
numeric
(unique_invoice_number_c);
action provided by the merchant
N
Commodity
Code
15-character alphanumeric
mcCorpac.setCommodityCode
(commodity_code);
Code assigned by the merchant that best categorizes
the item(s) being purchased
N
Order
Date
6-character
numeric
mcCorpac.setOrderDate
(order_date_c);
The date the item was
ordered
q*
Set Method
YYMMDD
format
Description
NOTE: If present, must contain a valid date
N
Corporation
VAT Number
20-character alphanumeric
mcCorpac
.setCorporationVatNumber
(corporation_vat_number_c);
Contains a corporation’s
value added tax (VAT) number
N
Customer
VAT Number
20-character alphanumeric
mcCorpac
.setCustomerVatNumber
(customer_vat_number_c);
Contains the VAT number
for the customer / cardholder used to identify the
customer when purchasing
goods and services from
the merchant
N
Freight
Amount
12-character
decimal
mcCorpac.setFreightAmount1
(freight_amount_c);
The freight on the total purchase
Must have 2 decimals
Minimum = 0.00 Maximum
= 999999.99
N
Duty
Amount
12-character
decimal
mcCorpac.setDutyAmount1
(duty_amount_c);
The duty on the total purchase
Must have 2 decimals
Minimum = 0.00
Maximum = 999999.99
N
Destination
State /
July 2018
3-character
alphanumeric
mcCorpac
.setDestinationProvinceCode
(destination_province_
State or Province of the
country where the goods
will be delivered
Page 198 of 477
Moneris Gateway API - Integration Guide
Req*
Value
Limits
Set Method
code);
Province
Code
Description
Left justified with trailing
spaces
EXAMPLE: ONT = Ontario
N
Destination
Country
Code
3-character
alphanumeric
mcCorpac
.setDestinationCountryCode
(destination_country_code);
The country code where
goods will be delivered
Left justified with trailing
spaces
ISO 3166-1
alpha-3
format
ISO 3166-1 alpha-3 format
EXAMPLE: CAN = Canada
N
Ship From
Postal
Code
10-character alphanumeric
mcCorpac.setShipFromPosCode
(ship_from_pos_code);
ANA NAN
format
N
The postal code or zip code
from which items were
shipped
Full alpha postal code Valid ANANAN
format
mcCorpac.setShipToPosCode
(ship_to_pos_code_c);
Destination
Postal
Code
10-character alphanumeric
N
Authorized
Contact
Name
36-character alphanumeric
mcCorpac
.setAuthorizedContactName
(authorized_contact_name_
c);
Name of an individual or
company contacted for
company authorized purchases
N
Authorized
Contact
Phone
17-character alphanumeric
mcCorpac
.setAuthorizedContactPhone
(authorized_contact_phone);
Phone number of an individual or company contacted for company
authorized purchases
N
Additional
Card
Acceptor
40-character alphanumeric
mcCorpac
.setAdditionalCardAcceptorD
ata(additional_card_
Information pertaining to
the card acceptor
Page 199 of 477
The postal code or zip code
where goods will be
delivered
Full alpha postal code Valid ANANAN
format if shipping to an
address within Canada
July 2018
7 Level 2/3 Transactions
Req*
Value
Limits
Card
Acceptor
Type
Description
acceptor_data);
Data
N
Set Method
8-character
alphanumeric
mcCorpac
.setCardAcceptorType(card_
acceptor_type);
Various classifications of
business ownership characteristics
This field takes 8 characters. Each character represents a different
component, as follows:
1st character represents
‘Business Type’ and contains a code to identify the
specific classification or
type of business:
1. Corporation
2. Not known
3. Individual/Sole Proprietorship
4. Partnership
5. Association/Estate/Trust
6. Tax Exempt Organizations (501C)
7. International Organization
8. Limited Liability Company (LLC)
9. Government Agency
2nd character represents
'Business Owner Type'.
Contains a code to identify
specific characteristics
about the business owner.
1 - No application
classification
2 - Female business
owner
3 - Physically handicapped female
July 2018
Page 200 of 477
Moneris Gateway API - Integration Guide
Req*
Value
Limits
Set Method
Description
business owner
4 - Physically handicapped male business owner
0 - Unknown
3rd character represents
'Business Certification
Type'. Contains a code to
identify specific characteristics about the business certification type,
such as small business, disadvantaged, or other certification type:
1 - Not certified
2 - Small Business
Administration (SBA)
certification small
business
3 - SBA certification
as small disadvantaged business
4 - Other government or agencyrecognized certification (such as
Minority Supplier
Development Council)
5 - Self-certified small
business
6 - SBA certification
as small and other
government or
agency-recognized
certification
7 - SBA certification
as small disadvantaged busi-
Page 201 of 477
July 2018
7 Level 2/3 Transactions
Req*
Value
Limits
Set Method
Description
ness and other government or agencyrecognized certification
8 - Other government or agencyrecognized certification and self-certified small business
A - SBA certification
as 8(a)
B - Self-certified
small disadvantaged
business (SDB)
C - SBA certification
as HUBZone
0 - Unknown
4th character represents
'Business Racial/Ethnic
Type'. Contains a code
identifying the racial or ethnic type of the majority
owner of the business.
1 - African American
2 - Asian Pacific
American
3 - Subcontinent
Asian American
4 - Hispanic American
5 - Native American
Indian
6 - Native Hawaiian
7 - Native Alaskan
8 - Caucasian
9 - Other
0 - Unknown
5th character represents
'Business Type Provided
Code'
July 2018
Page 202 of 477
Moneris Gateway API - Integration Guide
Req*
Value
Limits
Set Method
Description
Y - Business type is
provided.
N - Business type
was not provided.
R - Card acceptor
refused to provide
business type
6th character represents
'Business Owner Type
Provided Code'
Y - Business owner
type is provided.
N - Business owner
type was not
provided.
R - Card acceptor
refused to provide
business type
7th character represents
'Business Certification Type
Provided Code'
Y - Business certification type is
provided.
N - Business certification type was
not provided.
R - Card acceptor
refused to provide
business type
8th character represents
'Business Racial/Ethnic
Type’
Y - Business
racial/ethnic type is
provided.
N - Business
Page 203 of 477
July 2018
7 Level 2/3 Transactions
Req*
Value
Limits
Set Method
Description
racial/ethnic type
was not provided.
R - Card acceptor
refused to provide
business racial/ethnic type
N
Card
Acceptor
Tax ID
20-character alphanumeric
mcCorpac
.setCardAcceptorTaxTd(card_
acceptor_tax_id_c);
US federal tax ID number or
value-added tax (VAT) ID
N
Card
Acceptor
Reference
Number
25-character alphanumeric
mcCorpac
.setCardAcceptorReferenceNu
mber(card_acceptor_
reference_number);
Code that facilitates card
acceptor/corporation communication and record
keeping
N
Card
Acceptor
VAT Number
20-character alphanumeric
mcCorpac
.setCardAcceptorVatNumber
(card_acceptor_vat_number_
c);
Value added tax (VAT) number for the card acceptor
location
Tax
Up to 6
arrays
C
Used to identify the card
acceptor when collecting
and reporting taxes
mcCorpac.setTax(tax_c);
Can have up to 6 arrays
containing different tax
details
NOTE: If you use this variable, you must fill in all the
fields of tax array mentioned
below.
7.3.8.2 MC Corpal - Line Item Details
MC Corpal Object - Line Item Details
mcCorpal.setMcCorpal(customer_code1_l[0], line_item_date_l[0], ship_date_l[0],
order_date1_l[0], medical_services_ship_to_health_industry_number_l[0],
contract_number_l[0],medical_services_adjustment_l[0], medical_services_
product_number_qualifier_l[0], product_code1_l[0], item_description_l[0],
item_quantity_l[0], unit_cost_l[0], item_unit_measure_l[0], ext_item_amount_l
July 2018
Page 204 of 477
Moneris Gateway API - Integration Guide
[0], discount_amount_l[0], commodity_code_l[0], type_of_supply_l[0], vat_ref_
num_l[0], tax_l[0]);
Table 1: Line Item Details - Level 3 Request Fields - MC Corpal
Req*
Value
Limits
Variable
Description
N
Customer Code
25-character alphanumeric
customer_code1_l
A control number,
such as purchase
order number, project number,
department allocation number or
name that the purchaser supplied
the merchant
N
Line Item Date
6-character numeric
line_item_date_l
The purchase date
of the line item referenced in the
associated Corporate Card Line
Item Detail
YYMMDD format
Fixed length 6
Numeric, in
YYMMDD format
N
Ship Date
6-character numeric
ship_date_l
YYMMDD format
The date the merchandise was
shipped to the destination
Fixed length 6
Numeric, in
YYMMDD format
N
Order Date
6-character numeric
order_date1_ll
YYMMDD format
The date the item
was ordered
Fixed length 6-character numeric, in
YYMMDD format
Y
Product Code
Page 205 of 477
12-character alphanumeric
product_code1_ll
Line item Product
Code
July 2018
7 Level 2/3 Transactions
Req*
Value
Limits
Variable
Description
Contains the nonfuel related
product code of
the individual item
purchased
Y
Item Description
35-character alphanumeric
item_description_ll
Line Item description
Contains the
description of the
individual item purchased
Y
Item Quantity
12-character alphanumeric
item_quantity_ll
Quantity of line
item
Up to 5 decimal
places supported
Minimum amount
is 0.0 and maximum is
9999999.99999
Y
Unit Cost
12-character decimal
unit_cost_ll
Line item cost per
unit.
Must contain a
minimum of 2
decimal places, up
to 5 decimal places
supported.
Minimum amount
is 0.00001 and maximum is
999999.99999
Y
Item Unit Measure
12-character alphanumeric
item_unit_measure_
ll
The line item unit
of measurement
code
ANSI X-12 EDI
Allowable Units of
Measure and
Codes
July 2018
Page 206 of 477
Moneris Gateway API - Integration Guide
Req*
Y
Value
Extended Item
Amount
Limits
9-character decimal
Variable
ext_item_amount_ll
Description
Contains the individual item
amount that is normally calculated as
price multiplied by
quantity
Must contain 2
decimal places
Minimum amount
is 0.00 and maximum is 999999.99
N
Discount
Amount
9-character decimal
discount_amount_ll
Contains the item
discount amount
Must contain 2
decimal places
Minimum amount
is 0.00 and maximum is 999999.99
N
Commodity
Code
15-character alphanumeric
commodity_code_ll
Code assigned to
the merchant that
best categorizes
the item(s) being
purchased
C
Tax
Up to 6 arrays
tax_l
Can have up to 6
arrays containing
different tax details
–see Tax Array
Request Fields
table below for
each field description
NOTE: If you use
this variable, you
must fill in all the
fields of tax array
mentioned below.
Page 207 of 477
July 2018
7 Level 2/3 Transactions
7.3.8.3 Tax Array Object - MC Corpais
The tax array object is used when you use the Tax field of both MC Corpac and MC Corpal. If you use the
tax array object, all of the array fields must be sent.
Setting the tax array differs slightly between the two objects.
Setting tax array for MC Corpac
//Tax Details
String[] tax_amount_c = { "1.19", "1.29"};
String[] tax_rate_c = { "6.0", "7.0"};
String[] tax_type_c = { "GST", "PST"};
String[] tax_id_c = { "gst1298", "pst1298"};
String[] tax_included_in_sales_c = { "Y", "N"};
McTax tax_c = new McTax();
tax_c.setTax(tax_amount_c[0], tax_rate_c[0], tax_type_c[0], tax_id_c[0], tax_
included_in_sales_c[0]);
Setting tax array for MC Corpal
//Tax Details for Items
String[] tax_amount_l = {"0.52", "1.48"};
String[] tax_rate_l = {"13.0", "13.0"};
String[] tax_type_l = {"HST", "HST"};
String[] tax_id_l = {"hst1298", "hst1298"};
String[] tax_included_in_sales_l = {"Y", "Y"};
McTax[] tax_l = new McTax[2];
tax_l[1].setTax(tax_amount_l[1], tax_rate_l[1], tax_type_l[1], tax_id_l[1],
tax_included_in_sales_l[1]);
Table 1: MC Corpais Tax Array Request Fields
Req*
Y
Value
Tax Amount
Limits
12-character decimal
Variable
tax_amount_c/tax_
amount_l
Description
Contains detail tax
amount for purchase of goods or
services
Must be 2 decimal
places. Minimum
amount is 0.00 and
July 2018
Page 208 of 477
Moneris Gateway API - Integration Guide
Req*
Value
Limits
Variable
Description
maximum is
999999.99
Y
Tax Rate
5-character decimal
tax_rate_c/tax_
rate_l
Contains the
detailed tax rate
applied in relationship to a specific tax amount
EXAMPLE: 5% GST
should be ‘5.0’ or
or 9.975% QST
should be ‘9.975’
May contain up to
3 decimals, minimum 0.001, maximum up to 9999.9
Y
Tax Type
4-character alphanumeric
tax_type_c/tax_
type_l
Contains tax type,
such as
GST,QST,PST,HST
Y
Tax ID
20-character alphanumeric
tax_id_c/tax_id_l
Provides an identification number
used by the card
acceptor with the
tax authority in
relationship to a
specific tax
amount, such as
GST/HST number
Y
Tax included in
sales indicator
1-character alphanumeric
tax_included_in_
sales_c/tax_
included_in_sales_l
This is the indicator
used to reflect additional tax capture
and reporting
Valid values are:
Y = Tax included in
total purchase amount
N = Tax not included in
total purchase amount
Page 209 of 477
July 2018
7 Level 2/3 Transactions
7.3.8.4 Sample Code for MC Corpais
Sample MC Corpais - Corporate Card Common Data with Line Item Details
package Level23;
import JavaAPI.*;
public class TestMcCorpaisCommonLineItem
{
public static void main(String[] args)
{
String store_id = "moneris";
String api_token = "hurgle";
String processing_country_code = "CA";
boolean status_check = false;
String order_id="Test1485206444761";
String txn_number="39777-1_11";
String customer_code1_c ="CustomerCode123";
String card_acceptor_tax_id_c ="UrTaxId";//Merchant tax id which is mandatory
String corporation_vat_number_c ="cvn123";
String freight_amount_c ="1.23";
String duty_amount_c ="2.34";
String ship_to_pos_code_c ="M1R 1W5";
String order_date_c ="141211";
String customer_vat_number_c ="customervn231";
String unique_invoice_number_c ="uin567";
String authorized_contact_name_c ="John Walker";
//Tax Details
String[] tax_amount_c = { "1.19", "1.29"};
String[] tax_rate_c = { "6.0", "7.0"};
String[] tax_type_c = { "GST", "PST"};
String[] tax_id_c = { "gst1298", "pst1298"};
String[] tax_included_in_sales_c = { "Y", "N"};
//Item Details
String[] customer_code1_l = {"customer code", "customer code2"};
String[] line_item_date_l = {"150114", "150114"};
String[] ship_date_l = {"150120", "150122"};
String[] order_date1_l = {"150114", "150114"};
String[] medical_services_ship_to_health_industry_number_l = {"", ""};
String[] contract_number_l = {"", ""};
String[] medical_services_adjustment_l = {"", ""};
String[] medical_services_product_number_qualifier_l = {"", ""};
String[] product_code1_l = {"pc11", "pc12"};
String[] item_description_l = {"Good item", "Better item"};
String[] item_quantity_l = {"4", "5"};
String[] unit_cost_l ={"1.25", "10.00"};
String[] item_unit_measure_l = {"EA", "EA"};
String[] ext_item_amount_l ={"5.00", "50.00"};
String[] discount_amount_l ={"1.00", "50.00"};
String[] commodity_code_l ={"cCode11", "cCode12"};
String[] type_of_supply_l = {"", ""};
String[] vat_ref_num_l = {"", ""};
//Tax Details for Items
String[] tax_amount_l = {"0.52", "1.48"};
String[] tax_rate_l = {"13.0", "13.0"};
String[] tax_type_l = {"HST", "HST"};
String[] tax_id_l = {"hst1298", "hst1298"};
String[] tax_included_in_sales_l = {"Y", "Y"};
//Create and set Tax for McCorpac
McTax tax_c = new McTax();
tax_c.setTax(tax_amount_c[0], tax_rate_c[0], tax_type_c[0], tax_id_c[0], tax_included_in_sales_c
July 2018
Page 210 of 477
Moneris Gateway API - Integration Guide
Sample MC Corpais - Corporate Card Common Data with Line Item Details
[0]);
tax_c.setTax(tax_amount_c[1], tax_rate_c[1], tax_type_c[1], tax_id_c[1], tax_included_in_sales_c
[1]);
//Create and set McCorpac for common data - only set values that you know
McCorpac mcCorpac = new McCorpac();
mcCorpac.setCustomerCode1(customer_code1_c);
mcCorpac.setCardAcceptorTaxTd(card_acceptor_tax_id_c);
mcCorpac.setCorporationVatNumber(corporation_vat_number_c);
mcCorpac.setFreightAmount1(freight_amount_c);
mcCorpac.setDutyAmount1(duty_amount_c);
mcCorpac.setShipToPosCode(ship_to_pos_code_c);
mcCorpac.setOrderDate(order_date_c);
mcCorpac.setCustomerVatNumber(customer_vat_number_c);
mcCorpac.setUniqueInvoiceNumber(unique_invoice_number_c);
mcCorpac.setAuthorizedContactName(authorized_contact_name_c);
mcCorpac.setTax(tax_c);
//Create and set Tax for McCorpal
McTax[] tax_l = new McTax[2];
tax_l[0] = new McTax();
tax_l[0].setTax(tax_amount_l[0], tax_rate_l[0], tax_type_l[0], tax_id_l[0], tax_included_in_sales_
l[0]);
tax_l[1] = new McTax();
tax_l[1].setTax(tax_amount_l[1], tax_rate_l[1], tax_type_l[1], tax_id_l[1], tax_included_in_sales_
l[1]);
//Create and set McCorpal for each item
McCorpal mcCorpal = new McCorpal();
mcCorpal.setMcCorpal(customer_code1_l[0], line_item_date_l[0], ship_date_l[0], order_date1_l[0],
medical_services_ship_to_health_industry_number_l[0], contract_number_l[0],
medical_services_adjustment_l[0], medical_services_product_number_qualifier_l[0], product_code1_l
[0], item_description_l[0], item_quantity_l[0],
unit_cost_l[0], item_unit_measure_l[0], ext_item_amount_l[0], discount_amount_l[0], commodity_
code_l[0], type_of_supply_l[0], vat_ref_num_l[0], tax_l[0]);
mcCorpal.setMcCorpal(customer_code1_l[1], line_item_date_l[1], ship_date_l[1], order_date1_l[1],
medical_services_ship_to_health_industry_number_l[1], contract_number_l[1],
medical_services_adjustment_l[1], medical_services_product_number_qualifier_l[1], product_code1_l
[1], item_description_l[1], item_quantity_l[1],
unit_cost_l[1], item_unit_measure_l[1], ext_item_amount_l[1], discount_amount_l[1], commodity_
code_l[1], type_of_supply_l[1], vat_ref_num_l[1], tax_l[1]);
McCorpais mcCorpais = new McCorpais();
mcCorpais.setOrderId(order_id);
mcCorpais.setTxnNumber(txn_number);
mcCorpais.setMcCorpac(mcCorpac);
mcCorpais.setMcCorpal(mcCorpal);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(mcCorpais);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
Page 211 of 477
July 2018
7 Level 2/3 Transactions
Sample MC Corpais - Corporate Card Common Data with Line Item Details
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
System.out.println("CavvResultCode = " + receipt.getCavvResultCode());
}
catch (Exception e)
{
System.out.println(e);
}
}
}
7.4 Level 2/3 American Express Transactions
l
l
l
l
l
l
l
7.4.1
7.4.2
7.4.4
7.4.5
7.4.6
7.4.7
7.4.8
Level 2/3 Transaction Types for Amex
Level 2/3 Transaction Flow for Amex
AX Completion
AX Force Post
AX Purchase Correction
AX Refund
AX Independent Refund
7.4.1 Level 2/3 Transaction Types for Amex
This transaction set includes a suite of corporate card financial transactions as well as a transaction that
allows for the passing of Level 2/3 data. Please ensure American Express Level 2/3 processing support is
enabled on your merchant account. Batch Close, Open Totals and Pre-authorization are identical to the
transactions outlined in the section Basic Transaction Set (page 11).
l
l
When the Pre-authorization response contains CorporateCard equal to true then you can submit
the AX transactions.
If CorporateCard is false then the card does not support Level 2/3 data and non Level 2/3 transaction are to be used. If the card is not a corporate card, please refer to 2 Basic Transaction Set for
the appropriate non-corporate card transactions.
July 2018
Page 212 of 477
Moneris Gateway API - Integration Guide
NOTE: This transaction set is intended for transactions where Corporate Card is true and
Level 2/3 data will be submitted. If the credit card is found to be a corporate card but you do
not wish to send any Level 2/3 data then you may submit AX transactions using the transaction set outlined in the section Basic Transaction Set (page 11).
Pre-authorization – (authorization)
The preauth verifies and locks funds on the customer’s credit card. The funds are locked for a
specified amount of time, based on the card issuer. To retrieve the funds from a pre-auth so
that they may be settled in the merchant account a capture must be performed. CorporateCard will return as true if the card supports Level 2/3.
AX Completion – (Capture/Pre-authorization Completion)
Once a Pre-authorization is obtained the funds that are locked need to be retrieved from the
customer’s credit card. The capture retrieves the locked funds and readies them for settlement in to the merchant account. Prior to performing an AXCompletion a Preauth must be
performed.
AX Force Post – (Force Capture/Pre-authorization Completion)
This transaction is an alternative to AX Completion to obtain the funds locked on a Pre-authorization obtained from IVR or equivalent terminal. The capture retrieves the locked funds and
readies them for settlement in to the merchant account.
AX Purchase Correction – (Void, Correction)
AX Completion and AX Force Post can be voided the same day* that they occur. A void must
be for the full amount of the transaction and will remove any record of it from the cardholder
statement. * An AX Purchase Correction can be performed against a transaction as long as
the batch that contains the original transaction remains open. When using the automated
closing feature, the batch close occurs daily between 10 – 11 pm EST.
AX Refund – (Credit)
An AX Refund can be performed against an AX Completion and AX Force Post to refund any
part, or all of the transaction.
AX Independent Refund – (Credit)
An AX Independent Refund can be performed against a purchase or a capture to refund any
part, or all of the transaction. Independent refund is used when the originating transaction
was not performed through Moneris Gateway. Please note, the Independent Refund transaction may or may not be supported on your account. If you receive a transaction not
allowed error when attempting an independent refund, it may mean the transaction is not
supported on your account. If you wish to have the AX Independent Refund transaction type
temporarily enabled (or re-enabled), please contact the Service Centre at 1-866-319-7450.
Page 213 of 477
July 2018
7 Level 2/3 Transactions
7.4.2 Level 2/3 Transaction Flow for Amex
July 2018
Page 214 of 477
Moneris Gateway API - Integration Guide
7.4.3 Level 2/3 Data Objects in Amex
7.4.3.1 About the Level 2/3 Data Objects for Amex
7.4.3.2 Defining the AxLevel23 Object
l
Table 1 Object
l
Table 2 Object
l
Table 3 Object
l
l
7.4.3.1 About the Level 2/3 Data Objects for Amex
Many of the Level 2/3 transaction requests using American Express also include a mandatory data object
called AxLevel23. AxLevel23 is also comprised of other objects, also described in this section.
The Level 2/3 data objects within this section apply to all of the following transactions and are passed as
part of the transaction request for:
AX Completion
AX Force Post
AX Refund
AX Independent Refund
l
l
l
l
Things to Consider:
l
l
Please ensure the addendum data below is complete and accurate.
Please ensure the math on quantities calculations, amounts, discounts, taxes, etc. properly adds up to the overall transaction amount. Incorrect amounts will cause the transaction to be rejected.
7.4.3.2 Defining the AxLevel23 Object
AxLevel23 object definition
AxLevel23 level23 = new AxLevel23();
The AXLevel23 object itself has three objects, Table1, Table2 and Table3, all of which are mandatory.
Table 1: AxLevel23 Object
Req*
Y
Value
Table1
Limits
Object
Set Method
AxTable1 table1 =
new AxTable1();
level23.setTable1
Page 215 of 477
Description
Refer below for further breakdown
and definition of
table1
July 2018
7 Level 2/3 Transactions
Req*
Value
Limits
Set Method
Description
(table1);
Y
Table2
AxTable2 table2 =
new AxTable2();
Object
level23.setTable2
(table2);
Y
Table3
AxTable3 table3 =
new AxTable3();
Object
level23.setTable3
(table3);
Refer below for further breakdown
and definition of
table2
Refer below for further breakdown
and definition of
table3
*Y = Required, N = Optional, C = Conditional
Table 1 Object
Table 1 contains the addendum data heading information. Contains information such as identification
elements that uniquely identify an invoice (transaction), the customer name and shipping address.
Table 1 object definition
AxTable1 table1 = new AxTable1();
Table 1: AxLevel23 object - Table 1 object fields
Req*
C
Value
Purchase Order
Number
Limits
22-character alphanumeric
Set Method
table1.setBig04
(big04);
Description
The cardholder supplied Purchase Order
Number, which is
entered by the merchant at the point-ofsale
This entry is used in
the Statement/Reporting process and may include
accounting information specific to the
client
NOTE: This element
is mandatory, if the
merchant’s customer
provides a Purchase
Order Number.
July 2018
Page 216 of 477
Moneris Gateway API - Integration Guide
Req*
Value
Limits
Set Method
Description
N
Release Number
30-character alphanumeric
table1.setBig05
(big05);
A number that identifies a release
against a Purchase
Order previously
placed by the parties
involved in the transaction
N
Invoice Number
8-character alphanumeric
table1.setBig10
(big10);
Contains the Amex
invoice/reference
number
N
N1Loop
Object
table1.setN1Loop
(n1Loop)
Refer below for further breakdown and
definition of N1Loop
object
*Y = Required, N = Optional, C = Conditional
Table 1 also has its own objects:
l
l
N1Loop object
AxRef object
Table 1 - Setting the N1Loop Object
The N1Loop data set contains the Requester names. It can also optionally contain the buying group, ship
from, ship to and receiver details.
A minimum of at least 1 n1Loop must be set. Up to 5 n1Loop can be set.
N1Loop object definition
n1Loop.setN1Loop(n101, n102, n301, n401, n402, n403, axRef1);
Table 1: AxLevel23 object - Table 1 object - N1Loop object fields
Req*
Y
Value
Entity Identifier
Code
Limits
2-character alphanumeric
Variable or Set Method
n101
Description
Supported values:
R6 - Requester
(required)
BG - Buying Group
(optional)
SF - Ship From
(optional)
ST - Ship To (optional)
Page 217 of 477
July 2018
7 Level 2/3 Transactions
Req*
Value
Limits
Variable or Set Method
Description
40 - Receiver (optional)
Y
Name
40-character alphanumeric
n102
n101
code
n102
meaning
R6
Requester
Name
BG
Buying Group
Name
SF
Ship
From Name
ST
Ship To Name
40
Receiver Name
N
Address
40-character alphanumeric
n301
Address
N
City
30-character alphanumeric
n401
City
N
State or Province
2-character alphanumeric
n402
State or province
N
Postal Code
15-character alphanumeric
n403
Postal Code
N
AxRef
Object
AxRef axRef1 = new
AxRef();
Refer below for further breakdown
and definition of
AxRef object.
This object contains the customer
postal code (mandatory) and customer reference
number (optional)
A minimum of 1
axRef1 must be
set; maximum of 2
axRef1’s may be
set
*Y = Required, N = Optional, C = Conditional
July 2018
Page 218 of 477
Moneris Gateway API - Integration Guide
Table 1 - Setting the AxRef Object
Setting AXRef object
AxRef axRef1 = new AxRef();
String[] ref01 = {"4C", "CR"}; //Reference ID Qualifier
String[] ref02 = {"M5T3A5", "16802309004"}; //Reference ID
axRef1.setRef(ref01[0], ref02[0]);
axRef1.setRef(ref01[1], ref02[1]);
Table 1: AxLevel23 object - Table 1 object - AxRef object fields
Req*
Y
Value
Reference
Identification
Qualifier
Limits
2-character alphanumeric
Variable
ref01
Description
This element may contain the following qualifiers for the
corresponding occurrences of the N1Loop:
n101
value
R6
ref01
denotation
Supported values:
4C - Shipment
Destination
Code (mandatory)
CR - Customer
Reference
Number (conditional)
Y
Reference
Identification
Page 219 of 477
15-character alphanumeric
ref02
BG
n/a
SF
n/a
ST
n/a
40
n/a
This field must be populated for each ref01
provided
July 2018
7 Level 2/3 Transactions
Req*
Value
Limits
Variable
Description
ref01 ref02 denotavalue
tion
4C
(n101
value =
R6)
This element must
contain the Amex
Ship-to Postal Code
of the destination
where the commodity was shipped.
If the Ship-to Postal
Code is unavailable,
the postal code of
the merchant location where the
transaction took
place may be substituted.
CR
(n101
value =
R6):
This element must
contain the Amex
Card member Reference Number (e.g.,
purchase order, cost
center, project number, etc.) that corresponds to this
transaction, if
provided by the
Cardholder.
This information
may be displayed in
the statement/reporting process and may include
client-specific
accounting information.
*Y = Required, N = Optional, C = Conditional
Table 2 Object
Table 2 includes the transaction’s addendum detail. It contains transaction data including reference
codes, debit or credit and tax amounts, line item detail descriptions, shipping information and much
more. All transaction data in an invoice relate to a single transaction and cardholder account number.
Table 2 object definition
AxTable2 table2 = new AxTable2();
July 2018
Page 220 of 477
Moneris Gateway API - Integration Guide
Table 1: AxLevel23 object - Table 2 object fields
Req*
N
Value
It1loop
Limits
Set Method
table2.setIt1Loop
(it1Loop);
Object
Description
Refer below for further breakdown
and definition of
object details.
*Y = Required, N = Optional, C = Conditional
Table 2 - Setting the AxIt1Loop Object
The AxIt1Loop data defines the baseline item data for the invoice. This data is defined for each item/service purchased and included within this invoice. This data set contains basic transaction data, including
quantity, unit of measure, unit price and goods/services reference information.
l
l
A minimum of 1 it1Loop required
A maximum of 999 it1Loop’s supported
AxIt1Loop object definition
AxIt1Loop it1Loop = new AxIt1Loop();
it1Loop.setIt1Loop(it102[0], it103[0], it104[0], it105[0], it106s[0], txi[0],
pam05[0], pid05[0]);
it1Loop.setIt1Loop(it102[1], it103[1], it104[1], it105[1], it106s[1], txi[1],
pam05[1], pid05[1]);
Table 1: AxLevel23 object - Table 2 object - AxIt1Loop object fields
Req*
Y
Value
Line Item Quantity Invoiced
Limits
10-character decimal
Variable
it102
Description
Quantity of line
item
Up to 2 decimal
places supported
Minimum amount
is 0.0 and maximum is
9999999999
Y
Unit or Basis for
Measurement
Code
2-character alphanumeric
it103
The line item unit
of measurement
code
Must contain a
Page 221 of 477
July 2018
7 Level 2/3 Transactions
Req*
Value
Limits
Variable
Description
code that specifies
the units in which
the value is
expressed or the
manner in which a
measurement is
taken
EXAMPLE: EA =
each, E5=inches
See ANSI X-12 EDI
Allowable Units of
Measure and
Codes for the list
of codes
Y
Unit Price
15-character decimal
it104
Line item cost per
unit
Must contain 2
decimal places
Minimum amount
is 0.00 and maximum is 999999.99
N
Basis or Unit
Price Code
2-character alphanumeric
it105
Code identifying
the type of unit
price for an item
EXAMPLE: DR =
dealer, AP =
advise price
See ASC X12
004010 Element
639 for list of codes
N
AxIt106s
object
it106s
Refer below for further breakdown
and definition of
object details.
N
AxTxi
object
txi
Refer below for further breakdown
and definition of
July 2018
Page 222 of 477
Moneris Gateway API - Integration Guide
Req*
Value
Limits
Variable
Description
object details
A maximum of 12
AxTxi (tax information data sets)
may be defined
NOTE: that if line
item level tax
information is populated in AxTxi in
Table2, then tax
totals for the
entire invoice
(transaction) must
be entered in
Table3.
Y
Line Item Extended Amount
8-character decimal
pam05
Contains the individual item
amount that is normally calculated as
price multiplied by
quantity
Must contain 2
decimal places
Minimum amount
is 0.00 and maximum is 99999.99
Y
Line Item Description
80-character alphanumeric
pid05
Line Item description
Contains the
description of the
individual item purchased
This field pertain to
each line item in
the transaction
*Y = Required, N = Optional, C = Conditional
Page 223 of 477
July 2018
7 Level 2/3 Transactions
Table 2 - Setting the AxIt106s Object
AxIt106s[] it106s = {new AxIt106s(), new AxIt106s(), new AxIt106s(), new
AxIt106s(), new AxIt106s()};
String[] it10618 = {"MG", "MG", "MG", "MG", "MG"}; //Product/Service ID
qualifier
String[] it10719 = {"DJFR4", "JFJ49", "FEF33", "FEE43", "DISCOUNT"};
//Product/Service ID (corresponds to it10618)
Table 1: AxLevel23 object - Table 2 object - AxIt106s object fields
Req*
N
Value
Product/Service
ID Qualifier
Limits
2-character alphanumeric
Set Method
it106s
[0].setIt10618
(it10618[0]);
it106s
[1].setIt10618
(it10618[1]);
Description
Supported values:
MG - Manufacturer’s
Part Number
VC - Supplier Catalog
Number
SK - Supplier Stock
Keeping Unit Number
UP - Universal Product
Code
VP – Vendor Part Number
PO – Purchase Order
Number
AN – Client Defined
Asset Code
N
Product/Service
ID
it10618
VC
it10719 size/type
20-character
alphanumeric
PO
22-character
alphanumeric
Other
30-character
alphanumeric
it106s
[0].setIt10719
(it10719[0]);
it106s
[1].setIt10719
(it10719[1]);
Product/Service ID
corresponds to the
preceding qualifier
defined by it10618
The maximum
length depends on
the qualifier
defined in it10618
*Y = Required, N = Optional, C = Conditional
Table 2 - Setting the AxTxi Object
Table 2 AxiTxi object definition
//Create Table 2 with details
String[] txi01_GST = {"GS", "GS", "GS", "GS", "GS"}; //Tax type code
July 2018
Page 224 of 477
Moneris Gateway API - Integration Guide
String[] txi02_GST = {"0.70", "1.75", "1.00", "0.80","0.00"}; //Monetary
amount
String[] txi03_GST = {"5.0", "5.0", "5.0", "5.0","5.0"}; //Percent
String[] txi06_GST = {"2", "2", "2", "2","2"}; //Tax exempt code
String[] txi01_PST = {"PG", "PG", "PG","PG","PG"}; //Tax type code
String[] txi02_PST = {"0.80", "2.00", "1.00", "0.80","0.00"}; //Monetary
amount
String[] txi03_PST = {"7.0", "7.0", "7.0", "7.0","7.0"}; //Percent
String[] txi06_PST = {"2", "2", "2", "2","2"}; //Tax exempt code
AxTxi[] txi = {new AxTxi(), new AxTxi(), new AxTxi(), new AxTxi(), new AxTxi
()};
txi[0].setTxi(txi01_GST[0], txi02_GST[0], txi03_GST[0], txi06_GST[0]);
txi[0].setTxi(txi01_PST[0], txi02_PST[0], txi03_PST[0], txi06_PST[0]);
txi[1].setTxi(txi01_GST[1], txi02_GST[1], txi03_GST[1], txi06_GST[1]);
txi[1].setTxi(txi01_PST[1], txi02_PST[1], txi03_PST[1], txi06_PST[1]);
txi[2].setTxi(txi01_GST[2], txi02_GST[2], txi03_GST[2], txi06_GST[2]);
txi[2].setTxi(txi01_PST[2], txi02_PST[2], txi03_PST[2], txi06_PST[2]);
txi[3].setTxi(txi01_GST[3], txi02_GST[3], txi03_GST[3], txi06_GST[3]);
txi[3].setTxi(txi01_PST[3], txi02_PST[3], txi03_PST[3], txi06_PST[3]);
txi[4].setTxi(txi01_GST[4], txi02_GST[4], txi03_GST[4], txi06_GST[4]);
txi[4].setTxi(txi01_PST[4], txi02_PST[4], txi03_PST[4], txi06_PST[4]);
Table 1: AxLevel23 object - Table 2 object - AxiTxi object fields
Req*
C
Value
Tax Type code
Limits
txi01
Variable
2-character alphanumeric
Description
Tax type code
applicable to
Canada and US
only
For Canada, this
field must contain
a code that specifies the type of
tax
If txi01 is used,
Page 225 of 477
July 2018
7 Level 2/3 Transactions
Req*
Value
Limits
Variable
Description
then txi02, txi03 or
txi06 must be populated
Valid codes include
the following:
CT – County/Tax
(optional)
CA – City Tax
(optional)
EV – Environmental
Tax (optional)
GS – Good and Services Tax (GST)
(optional)
LS – State and Local
Sales Tax (optional)
LT – Local Sales Tax
(optional)
PG – Provincial Sales
Tax (PST) (optional)
SP – State/Provincial
Tax a.k.a. Quebec
Sales Tax (QST)
(optional)
ST – State Sales Tax
(optional)
TX – All Taxes
(required)
VA – Value-Added Tax
a.k.a. Canadian Harmonized Sales Tax
(HST) (optional)
C
Monetary
Amount
txi02
6-character decimal
This element may
contain the monetary tax amount
that corresponds
to the Tax Type
Code in txi01
NOTE:
If txi02 is used in
mandatory occur-
July 2018
Page 226 of 477
Moneris Gateway API - Integration Guide
Req*
Value
Limits
Variable
Description
rence txi01=TX, txi02
must contain the
total tax amount
applicable to the
entire invoice (transaction)
If taxes are not
applicable for the
entire invoice (transaction), txi02 must
be 0.00.
The maximum
value that can be
entered in this
field is “9999.99”,
which is $9,999.99
(CAD)
A debit is entered
as: 9999.99
A credit is entered
as: –9999.99
C
Percent
txi03
10-character decimal
Contains the tax
percentage (in
decimal format)
that corresponds
to the tax type
code defined in
txi01
Up to 2 decimal
places supported
C
Tax Exempt Code
txi06
1-character alphanumeric
This element may
contain the Tax
Exempt Code that
identifies the
exemption status
from sales and tax
that corresponds
to the Tax Type
Code in txi01
Supported values:
1 – Yes (Tax Exempt)
2 – No (Not Tax
Exempt)
Page 227 of 477
July 2018
7 Level 2/3 Transactions
Req*
Value
Limits
Variable
Description
4 – Not Exempt/For
Resale
A – Labor Taxable,
Material Exempt
B – Material Taxable,
Labor Exempt
C – Not Taxable
F – Exempt (Goods /
Services Tax)
G – Exempt (Provincial
Sales Tax)
L – Exempt Local Service
R – Recurring Exempt
U – Usage Exempt
*Y = Required, N = Optional, C = Conditional
Table 3 Object
Table 3 includes the transaction addendum summary. It contains the total invoice (transaction) amount,
sales tax, freight and/or handling charges and invoice summary information, including total line items,
number of segments in the invoice, and the transaction set control number (a.k.a., batch number).
Table 3 object definition
AxTable3 table3 = new AxTable3();
Table 1: AxLevel23 object - Table 3 object fields
Req*
C
Value
AxTxi
Limits
Object
Set Method
table3.setTxi
(taxTbl3);
Description
Refer below for further breakdown
and definition of
object details.
NOTE: if line item
level tax information is populated
in AxTxi in Table2,
then tax totals for
the entire invoice
July 2018
Page 228 of 477
Moneris Gateway API - Integration Guide
Req*
Value
Limits
Set Method
Description
(transaction) must
be entered in
Table3. A maximum of 10
AxTxi’s may be set
in Table3.
*Y = Required, N = Optional, C = Conditional
Table 3 - Setting the AxTxi Object
The mandatory tax information data set must contain the total tax amount applicable to the entire
invoice (transaction) which includes all line items identified in Table2. If taxes are not applicable for the
entire invoice (transaction), then txi02 must be set to 0.00.
Tax totals must be entered in this mandatory tax information segment in Table 3, even if line item detail
level tax data is reported in Table 2.
At least one occurrence of txi02, txi03 or txi06 is required.
Table 3 AxiTxi object definition
AxTxi taxTbl3 = new AxTxi();
taxTbl3.setTxi("GS", "4.25","",""); //sum of GST taxes
taxTbl3.setTxi("PG", "4.60","",""); //sum of PST taxes
taxTbl3.setTxi("TX", "8.85","",""); //sum of all taxes
Table 1: AxLevel23 object - Table 3 object - AxiTxi object fields
Req*
C
Value
Tax Type code
Limits
txi01
Variable
2-character alphanumeric
Description
Tax type code
applicable to
Canada and US
only
For Canada, this
field must contain
a code that specifies the type of
tax
If txi01 is used,
then txi02, txi03 or
txi06 must be populated
Page 229 of 477
July 2018
7 Level 2/3 Transactions
Req*
Value
Limits
Variable
Description
Valid codes include
the following:
CT – County/Tax
(optional)
CA – City Tax
(optional)
EV – Environmental
Tax (optional)
GS – Good and Services Tax (GST)
(optional)
LS – State and Local
Sales Tax (optional)
LT – Local Sales Tax
(optional)
PG – Provincial Sales
Tax (PST) (optional)
SP – State/Provincial
Tax a.k.a. Quebec
Sales Tax (QST)
(optional)
ST – State Sales Tax
(optional)
TX – All Taxes
(required)
VA – Value-Added Tax
a.k.a. Canadian Harmonized Sales Tax
(HST) (optional)
C
Monetary
Amount
txi02
6-character decimal
This element may
contain the monetary tax amount
that corresponds
to the Tax Type
Code in txi01
NOTE:
If txi02 is used in
mandatory occurrence txi01=TX, txi02
must contain the
total tax amount
applicable to the
entire invoice (transaction)
July 2018
Page 230 of 477
Moneris Gateway API - Integration Guide
Req*
Value
Limits
Variable
Description
If taxes are not
applicable for the
entire invoice (transaction), txi02 must
be 0.00.
The maximum
value that can be
entered in this
field is “9999.99”,
which is $9,999.99
(CAD)
A debit is entered
as: 9999.99
A credit is entered
as: –9999.99
C
Percent
txi03
10-character decimal
Contains the tax
percentage (in
decimal format)
that corresponds
to the tax type
code defined in
txi01
Up to 2 decimal
places supported
C
Tax Exempt Code
txi06
1-character alphanumeric
This element may
contain the Tax
Exempt Code that
identifies the
exemption status
from sales and tax
that corresponds
to the Tax Type
Code in txi01
Supported values:
1 – Yes (Tax Exempt)
2 – No (Not Tax
Exempt)
4 – Not Exempt/For
Resale
A – Labor Taxable,
Material Exempt
Page 231 of 477
July 2018
7 Level 2/3 Transactions
Req*
Value
Limits
Variable
Description
B – Material Taxable,
Labor Exempt
C – Not Taxable
F – Exempt (Goods /
Services Tax)
G – Exempt (Provincial
Sales Tax)
L – Exempt Local Service
R – Recurring Exempt
U – Usage Exempt
*Y = Required, N = Optional, C = Conditional
7.4.4 AX Completion
The AX Completion transaction is used to secure the funds locked by a pre-authorization transaction.
When sending a capture request you will need two pieces of information from the original pre-authorization – the Order ID and the transaction number from the returned response.
AX Completion transaction object definition
AxCompletion axCompletion = new AxCompletion()
HttpsPostRequest object for AX Completion
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(axCompletion);
AX Completion transaction object values
Table 1: AX Completion transaction object mandatory values
Value
Type
Limits
Set Method
Order ID
String
50-character alphanumeric
axCompletion.setOrderId
(order_id);
Completion amount
String
9-character decimal
axCompletion.setCompAmount
(comp_amount);
Transaction number
String
255-character alphanumeric
axCompletion.setTxnNumber
(txn_number);
July 2018
Page 232 of 477
Moneris Gateway API - Integration Guide
Value
Type
Limits
Set Method
E-commerce indicator
String
1-character alphanumeric
axCompletion.setCryptType
(crypt);
Level 2/3 Data
Object
n/a
axCompletion.setAxLevel23
(level23);
Sample AX Completion
package Level23;
import JavaAPI.*;
public class TestAxCompletion
{
public static void main(String[] args)
{
String store_id = "moneris";
String api_token = "hurgle";
String processing_country_code = "CA";
boolean status_check = false;
String
String
String
String
order_id="ord-210916-12:06:38";
comp_amount="62.37";
txn_number = "18924-0_11";
crypt="7";
//Create Table 1 with details
String n101 = "R6"; //Entity ID Code
String n102 = "Retailing Inc. International"; //Name
String n301 = "919 Oriole Rd."; //Address Line 1
String n401 = "Toronto"; //City
String n402 = "On"; //State or Province
String n403 = "H1T6W3"; //Postal Code
String[] ref01 = {"4C", "CR"}; //Reference ID Qualifier
String[] ref02 = {"M5T3A5", "16802309004"}; //Reference ID
String big04 = "PO7758545"; //Purchase Order Number
String big05 = "RN0049858"; //Release Number
String big10 = "INV99870E"; //Invoice Number
AxRef axRef1 = new AxRef();
axRef1.setRef(ref01[0], ref02[0]);
axRef1.setRef(ref01[1], ref02[1]);
AxN1Loop n1Loop = new AxN1Loop();
n1Loop.setN1Loop(n101, n102, n301, n401, n402, n403, axRef1);
AxTable1 table1 = new AxTable1();
table1.setBig04(big04);
table1.setBig05(big05);
table1.setBig10(big10);
table1.setN1Loop(n1Loop);
//Create Table 2
//the sum of the
String[] it102 =
String[] it103 =
String[] it104 =
String[] it105 =
Page 233 of 477
with details
extended amount field (pam05) must equal the level 1 amount field
{"1", "1", "1", "1", "1"}; //Line item quantity invoiced
{"EA", "EA", "EA", "EA", "EA"}; //Line item unit or basis of measurement code
{"10.00", "25.00", "8.62", "10.00", "-10.00"}; //Line item unit price
{"", "", "", "", ""}; //Line item basis of unit price code
July 2018
7 Level 2/3 Transactions
Sample AX Completion
String[] it10618 = {"MG", "MG", "MG", "MG", "MG"}; //Product/Service ID qualifier
String[] it10719 = {"DJFR4", "JFJ49", "FEF33", "FEE43", "DISCOUNT"}; //Product/Service ID
(corresponds to it10618)
String[]
String[]
String[]
String[]
txi01_GST
txi02_GST
txi03_GST
txi06_GST
=
=
=
=
{"GS", "GS", "GS", "GS", "GS"}; //Tax type code
{"0.70", "1.75", "1.00", "0.80","0.00"}; //Monetary amount
{"", "", "", "",""}; //Percent
{"", "", "", "",""}; //Tax exempt code
String[] txi01_PST = {"PG", "PG", "PG","PG","PG"}; //Tax type code
String[] txi02_PST = {"0.80", "2.00", "1.00", "0.80","0.00"}; //Monetary amount
String[] txi03_PST = {"", "", "", "",""}; //Percent
String[] txi06_PST = {"", "", "", "",""}; //Tax exempt code
String[] pam05 = {"11.50", "28.75", "10.62", "11.50", "-10.00"}; //Extended line-item amount
String[] pid05 = {"Stapler", "Lamp", "Bottled Water", "Fountain Pen", "DISCOUNT"}; //Line item
description
AxIt106s[] it106s = {new AxIt106s(), new AxIt106s(), new AxIt106s(), new AxIt106s(), new AxIt106s
()};
it106s[0].setIt10618(it10618[0]);
it106s[0].setIt10719(it10719[0]);
it106s[1].setIt10618(it10618[1]);
it106s[1].setIt10719(it10719[1]);
it106s[2].setIt10618(it10618[2]);
it106s[2].setIt10719(it10719[2]);
it106s[3].setIt10618(it10618[3]);
it106s[3].setIt10719(it10719[3]);
it106s[4].setIt10618(it10618[4]);
it106s[4].setIt10719(it10719[4]);
AxTxi[] txi = {new AxTxi(), new AxTxi(), new AxTxi(), new AxTxi(), new AxTxi()};
txi[0].setTxi(txi01_GST[0], txi02_GST[0], txi03_GST[0], txi06_GST[0]);
txi[0].setTxi(txi01_PST[0], txi02_PST[0], txi03_PST[0], txi06_PST[0]);
txi[1].setTxi(txi01_GST[1], txi02_GST[1], txi03_GST[1], txi06_GST[1]);
txi[1].setTxi(txi01_PST[1], txi02_PST[1], txi03_PST[1], txi06_PST[1]);
txi[2].setTxi(txi01_GST[2], txi02_GST[2], txi03_GST[2], txi06_GST[2]);
txi[2].setTxi(txi01_PST[2], txi02_PST[2], txi03_PST[2], txi06_PST[2]);
txi[3].setTxi(txi01_GST[3], txi02_GST[3], txi03_GST[3], txi06_GST[3]);
txi[3].setTxi(txi01_PST[3], txi02_PST[3], txi03_PST[3], txi06_PST[3]);
txi[4].setTxi(txi01_GST[4], txi02_GST[4], txi03_GST[4], txi06_GST[4]);
txi[4].setTxi(txi01_PST[4], txi02_PST[4], txi03_PST[4], txi06_PST[4]);
AxIt1Loop it1Loop = new AxIt1Loop();
it1Loop.setIt1Loop(it102[0], it103[0], it104[0], it105[0], it106s[0], txi[0], pam05[0],
it1Loop.setIt1Loop(it102[1], it103[1], it104[1], it105[1], it106s[1], txi[1], pam05[1],
it1Loop.setIt1Loop(it102[2], it103[2], it104[2], it105[2], it106s[2], txi[2], pam05[2],
it1Loop.setIt1Loop(it102[3], it103[3], it104[3], it105[3], it106s[3], txi[3], pam05[3],
it1Loop.setIt1Loop(it102[4], it103[4], it104[4], it105[4], it106s[4], txi[4], pam05[4],
AxTable2 table2 = new AxTable2();
table2.setIt1Loop(it1Loop);
//Create Table 3 with details
AxTxi taxTbl3 = new AxTxi();
taxTbl3.setTxi("GS", "4.25","",""); //sum of GST taxes
taxTbl3.setTxi("PG", "4.60","",""); //sum of PST taxes
taxTbl3.setTxi("TX", "8.85","",""); //sum of all taxes
AxTable3 table3 = new AxTable3();
July 2018
pid05[0]);
pid05[1]);
pid05[2]);
pid05[3]);
pid05[4]);
Page 234 of 477
Moneris Gateway API - Integration Guide
Sample AX Completion
table3.setTxi(taxTbl3);
//Create and set Level23 Object
AxLevel23 level23 = new AxLevel23();
level23.setTable1(table1);
level23.setTable2(table2);
level23.setTable3(table3);
AxCompletion axCompletion = new AxCompletion();
axCompletion.setOrderId(order_id);
axCompletion.setCompAmount(comp_amount);
axCompletion.setTxnNumber(txn_number);
axCompletion.setCryptType(crypt);
axCompletion.setAxLevel23(level23);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(axCompletion);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
System.out.println("CavvResultCode = " + receipt.getCavvResultCode());
}
catch (Exception e)
{
System.out.println(e);
}
}
}
7.4.5 AX Force Post
The AX Force Post transaction is used to secure the funds locked by a pre-authorization transaction performed over IVR or equivalent terminal. When sending an AX Force Post request, you will need the order
ID, amount, credit card number, expiry date, authorization code and e-commerce indicator.
AX Force Post transaction object definition
AxForcePost axForcePost = new AxForcePost();
Page 235 of 477
July 2018
7 Level 2/3 Transactions
HttpsPostRequest object for AX Force Post transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(axForcePost);
AX Force Post transaction object values
Table 1: AX Force Post transaction object mandatory values
Value
Type
Limits
Set Method
Order ID
String
50-character alphanumeric
axForcePost.setOrderId
(order_id);
Amount
String
9-character decimal
axForcePost.setAmount
(amount);
Credit card number
String
20-character alphanumeric
axForcePost.setPan(pan);
Expiry date
String
4-character alphanumeric
axForcePost.setExpDate
(expiry_date);
(YYMM format)
Authorization code
String
8-character alphanumeric
axForcePost.setAuthCode
(auth_code);
E-commerce indicator
String
1-character alphanumeric
axForcePost.setCryptType
(crypt);
Level 2/3 Data
Object
n/a
axForcePost.setAxLevel23
(level23);
Table 2: AX Force Post transaction object optional values
Value
Customer ID
Type
String
Limits
50-character alphanumeric
Set Method
axForcePost.setCustId(cust_
id);
Sample AX Force Post
package Level23;
import JavaAPI.*;
public class TestAxForcePost
{
July 2018
Page 236 of 477
Moneris Gateway API - Integration Guide
Sample AX Force Post
public static void main(String[] args)
{
String store_id = "moneris";
String api_token = "hurgle";
String processing_country_code = "CA";
boolean status_check = false;
java.util.Date createDate = new java.util.Date();
String order_id="Test"+createDate.getTime();
String cust_id="CUST13343";
String amount="62.37";
String pan="373269005095005";
String expiry_date="2012"; //YYMM
String auth_code="123456";
String crypt="7";
//Create Table 1 with details
String n101 = "R6"; //Entity ID Code
String n102 = "Retailing Inc. International"; //Name
String n301 = "919 Oriole Rd."; //Address Line 1
String n401 = "Toronto"; //City
String n402 = "On"; //State or Province
String n403 = "H1T6W3"; //Postal Code
String[] ref01 = {"4C", "CR"}; //Reference ID Qualifier
String[] ref02 = {"M5T3A5", "16802309004"}; //Reference ID
String big04 = "PO7758545"; //Purchase Order Number
String big05 = "RN0049858"; //Release Number
String big10 = "INV99870E"; //Invoice Number
AxRef axRef1 = new AxRef();
axRef1.setRef(ref01[0], ref02[0]);
axRef1.setRef(ref01[1], ref02[1]);
AxN1Loop n1Loop = new AxN1Loop();
n1Loop.setN1Loop(n101, n102, n301, n401, n402, n403, axRef1);
AxTable1 table1 = new AxTable1();
table1.setBig04(big04);
table1.setBig05(big05);
table1.setBig10(big10);
table1.setN1Loop(n1Loop);
//Create Table 2 with details
//the sum of the extended amount field (pam05) must equal the level 1 amount field
String[]
String[]
String[]
String[]
it102
it103
it104
it105
=
=
=
=
{"1", "1", "1", "1", "1"}; //Line item quantity invoiced
{"EA", "EA", "EA", "EA", "EA"}; //Line item unit or basis of measurement code
{"10.00", "25.00", "8.62", "10.00", "-10.00"}; //Line item unit price
{"", "", "", "", ""}; //Line item basis of unit price code
String[] it10618 = {"MG", "MG", "MG", "MG", "MG"}; //Product/Service ID qualifier
String[] it10719 = {"DJFR4", "JFJ49", "FEF33", "FEE43", "DISCOUNT"}; //Product/Service ID
(corresponds to it10618)
String[]
String[]
String[]
String[]
txi01_GST
txi02_GST
txi03_GST
txi06_GST
=
=
=
=
{"GS", "GS", "GS", "GS", "GS"}; //Tax type code
{"0.70", "1.75", "1.00", "0.80","0.00"}; //Monetary amount
{"", "", "", "",""}; //Percent
{"", "", "", "",""}; //Tax exempt code
String[] txi01_PST = {"PG", "PG", "PG","PG","PG"}; //Tax type code
String[] txi02_PST = {"0.80", "2.00", "1.00", "0.80","0.00"}; //Monetary amount
String[] txi03_PST = {"", "", "", "",""}; //Percent
Page 237 of 477
July 2018
7 Level 2/3 Transactions
Sample AX Force Post
String[] txi06_PST = {"", "", "", "",""}; //Tax exempt code
String[] pam05 = {"11.50", "28.75", "10.62", "11.50", "-10.00"}; //Extended line-item amount
String[] pid05 = {"Stapler", "Lamp", "Bottled Water", "Fountain Pen", "DISCOUNT"}; //Line item
description
AxIt106s[] it106s = {new AxIt106s(), new AxIt106s(), new AxIt106s(), new AxIt106s(), new AxIt106s
()};
it106s[0].setIt10618(it10618[0]);
it106s[0].setIt10719(it10719[0]);
it106s[1].setIt10618(it10618[1]);
it106s[1].setIt10719(it10719[1]);
it106s[2].setIt10618(it10618[2]);
it106s[2].setIt10719(it10719[2]);
it106s[3].setIt10618(it10618[3]);
it106s[3].setIt10719(it10719[3]);
it106s[4].setIt10618(it10618[4]);
it106s[4].setIt10719(it10719[4]);
AxTxi[] txi = {new AxTxi(), new AxTxi(), new AxTxi(), new AxTxi(), new AxTxi()};
txi[0].setTxi(txi01_GST[0], txi02_GST[0], txi03_GST[0], txi06_GST[0]);
txi[0].setTxi(txi01_PST[0], txi02_PST[0], txi03_PST[0], txi06_PST[0]);
txi[1].setTxi(txi01_GST[1], txi02_GST[1], txi03_GST[1], txi06_GST[1]);
txi[1].setTxi(txi01_PST[1], txi02_PST[1], txi03_PST[1], txi06_PST[1]);
txi[2].setTxi(txi01_GST[2], txi02_GST[2], txi03_GST[2], txi06_GST[2]);
txi[2].setTxi(txi01_PST[2], txi02_PST[2], txi03_PST[2], txi06_PST[2]);
txi[3].setTxi(txi01_GST[3], txi02_GST[3], txi03_GST[3], txi06_GST[3]);
txi[3].setTxi(txi01_PST[3], txi02_PST[3], txi03_PST[3], txi06_PST[3]);
txi[4].setTxi(txi01_GST[4], txi02_GST[4], txi03_GST[4], txi06_GST[4]);
txi[4].setTxi(txi01_PST[4], txi02_PST[4], txi03_PST[4], txi06_PST[4]);
AxIt1Loop it1Loop = new AxIt1Loop();
it1Loop.setIt1Loop(it102[0], it103[0], it104[0], it105[0], it106s[0], txi[0], pam05[0],
it1Loop.setIt1Loop(it102[1], it103[1], it104[1], it105[1], it106s[1], txi[1], pam05[1],
it1Loop.setIt1Loop(it102[2], it103[2], it104[2], it105[2], it106s[2], txi[2], pam05[2],
it1Loop.setIt1Loop(it102[3], it103[3], it104[3], it105[3], it106s[3], txi[3], pam05[3],
it1Loop.setIt1Loop(it102[4], it103[4], it104[4], it105[4], it106s[4], txi[4], pam05[4],
AxTable2 table2 = new AxTable2();
table2.setIt1Loop(it1Loop);
//Create Table 3 with details
AxTxi taxTbl3 = new AxTxi();
taxTbl3.setTxi("GS", "4.25","",""); //sum of GST taxes
taxTbl3.setTxi("PG", "4.60","",""); //sum of PST taxes
taxTbl3.setTxi("TX", "8.85","",""); //sum of all taxes
AxTable3 table3 = new AxTable3();
table3.setTxi(taxTbl3);
pid05[0]);
pid05[1]);
pid05[2]);
pid05[3]);
pid05[4]);
AxLevel23 level23 = new AxLevel23();
level23.setTable1(table1);
level23.setTable2(table2);
level23.setTable3(table3);
AxForcePost axForcePost = new AxForcePost();
axForcePost.setOrderId(order_id);
axForcePost.setCustId(cust_id);
axForcePost.setAmount(amount);
axForcePost.setPan(pan);
axForcePost.setExpDate(expiry_date);
axForcePost.setAuthCode(auth_code);
July 2018
Page 238 of 477
Moneris Gateway API - Integration Guide
Sample AX Force Post
axForcePost.setCryptType(crypt);
axForcePost.setAxLevel23(level23);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(axForcePost);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
System.out.println("CavvResultCode = " + receipt.getCavvResultCode());
}
catch (Exception e)
{
System.out.println(e);
}
}
}
7.4.6 AX Purchase Correction
The AX Purchase Correction (Void) transaction is used to cancel a transaction that was performed in the
current batch. No amount is required because a void is always for 100% of the original transaction. The
only transaction that can be voided using AX Purchase Correction is AX Completion and AX Force Post.
To send an AX Purchase Correction the Order ID and transaction number from the AX Completion or AX
Force Post are required.
AX Purchase Correction transaction object definition
AxPurchaseCorrection axPurchaseCorrection = new AxPurchaseCorrection();
HttpsPostRequest object for AX Purchase Correction transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
Page 239 of 477
July 2018
7 Level 2/3 Transactions
mpgReq.setTransaction(axPurchaseCorrection);
AX Purchase Correction transaction object values
Table 1: AX Purchase Correction transaction object mandatory values
Value
Type
Limits
Set Method
Order ID
String
50-character alphanumeric
axPurchaseCorrection
.setOrderId(order_id);
Transaction number
String
255-character alphanumeric
axPurchaseCorrection
.setTxnNumber(txn_number);
E-commerce indicator
String
1-character alphanumeric
axPurchaseCorrection
.setCryptType(crypt);
AX Purchase Correction
package Level23;
import JavaAPI.*;
public class TestAxPurchaseCorrection
{
public static void main(String[] args)
{
String store_id = "moneris";
String api_token = "hurgle";
String processing_country_code = "CA";
boolean status_check = false;
String order_id="Test1485206180427";
String txn_number = "660117311902017023161620759-0_11";
String crypt="7";
AxPurchaseCorrection axPurchaseCorrection = new AxPurchaseCorrection();
axPurchaseCorrection.setOrderId(order_id);
axPurchaseCorrection.setTxnNumber(txn_number);
axPurchaseCorrection.setCryptType(crypt);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(axPurchaseCorrection);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
July 2018
Page 240 of 477
Moneris Gateway API - Integration Guide
AX Purchase Correction
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
System.out.println("CavvResultCode = " + receipt.getCavvResultCode());
}
catch (Exception e)
{
System.out.println(e);
}
}
}
7.4.7 AX Refund
The AX Refund will credit a specified amount to the cardholder’s credit card. A refund can be sent up to
the full value of the original AX Completion or AX Force Post. To send an AX Refund you will require the
Order ID and transaction number from the original AX Completion or AX Force Post.
AX Refund transaction object definition
AxRefund axRefund = new AxRefund();
HttpsPostRequest object for AX Refund transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(axRefund);
AX Refund transaction object values
Table 1: AX Refund transaction object mandatory values
Value
Type
Limits
Set Method
Order ID
String
50-character alphanumeric
axRefund.setOrderId(order_
id);
Transaction number
String
255-character alphanumeric
axRefund.setTxnNumber(txn_
number);
Amount
String
9-character decimal
axRefund.setAmount(amount);
Page 241 of 477
July 2018
7 Level 2/3 Transactions
Value
Type
Limits
Set Method
E-commerce indicator
String
1-character alphanumeric
axRefund.setCryptType
(crypt);
Level 2/3 Data
Object
n/a
axRefund.setAxLevel23
(level23);
Sample AX Refund
package Level23;
import JavaAPI.*;
public class TestAxRefund
{
public static void main(String[] args)
{
String store_id = "moneris";
String api_token = "hurgle";
String processing_country_code = "CA";
boolean status_check = false;
String
String
String
String
order_id="Test1485206231878";
amount="62.37";
txn_number = "660117311902017023161712265-0_11";
crypt="7";
//Create Table 1 with details
String n101 = "R6"; //Entity ID Code
String n102 = "Retailing Inc. International"; //Name
String n301 = "919 Oriole Rd."; //Address Line 1
String n401 = "Toronto"; //City
String n402 = "On"; //State or Province
String n403 = "H1T6W3"; //Postal Code
String[] ref01 = {"4C", "CR"}; //Reference ID Qualifier
String[] ref02 = {"M5T3A5", "16802309004"}; //Reference ID
String big04 = "PO7758545"; //Purchase Order Number
String big05 = "RN0049858"; //Release Number
String big10 = "INV99870E"; //Invoice Number
AxRef axRef1 = new AxRef();
axRef1.setRef(ref01[0], ref02[0]);
axRef1.setRef(ref01[1], ref02[1]);
AxN1Loop n1Loop = new AxN1Loop();
n1Loop.setN1Loop(n101, n102, n301, n401, n402, n403, axRef1);
AxTable1 table1 = new AxTable1();
table1.setBig04(big04);
table1.setBig05(big05);
table1.setBig10(big10);
table1.setN1Loop(n1Loop);
//Create Table 2
//the sum of the
String[] it102 =
String[] it103 =
String[] it104 =
String[] it105 =
July 2018
with details
extended amount field (pam05) must equal the level 1 amount field
{"1", "1", "1", "1", "1"}; //Line item quantity invoiced
{"EA", "EA", "EA", "EA", "EA"}; //Line item unit or basis of measurement code
{"10.00", "25.00", "8.62", "10.00", "-10.00"}; //Line item unit price
{"", "", "", "", ""}; //Line item basis of unit price code
Page 242 of 477
Moneris Gateway API - Integration Guide
Sample AX Refund
String[] it10618 = {"MG", "MG", "MG", "MG", "MG"}; //Product/Service ID qualifier
String[] it10719 = {"DJFR4", "JFJ49", "FEF33", "FEE43", "DISCOUNT"}; //Product/Service ID
(corresponds to it10618)
String[]
String[]
String[]
String[]
txi01_GST
txi02_GST
txi03_GST
txi06_GST
=
=
=
=
{"GS", "GS", "GS", "GS", "GS"}; //Tax type code
{"0.70", "1.75", "1.00", "0.80","0.00"}; //Monetary amount
{"", "", "", "",""}; //Percent
{"", "", "", "",""}; //Tax exempt code
String[] txi01_PST = {"PG", "PG", "PG","PG","PG"}; //Tax type code
String[] txi02_PST = {"0.80", "2.00", "1.00", "0.80","0.00"}; //Monetary amount
String[] txi03_PST = {"", "", "", "",""}; //Percent
String[] txi06_PST = {"", "", "", "",""}; //Tax exempt code
String[] pam05 = {"11.50", "28.75", "10.62", "11.50", "-10.00"}; //Extended line-item amount
String[] pid05 = {"Stapler", "Lamp", "Bottled Water", "Fountain Pen", "DISCOUNT"}; //Line item
description
AxIt106s[] it106s = {new AxIt106s(), new AxIt106s(), new AxIt106s(), new AxIt106s(), new AxIt106s
()};
it106s[0].setIt10618(it10618[0]);
it106s[0].setIt10719(it10719[0]);
it106s[1].setIt10618(it10618[1]);
it106s[1].setIt10719(it10719[1]);
it106s[2].setIt10618(it10618[2]);
it106s[2].setIt10719(it10719[2]);
it106s[3].setIt10618(it10618[3]);
it106s[3].setIt10719(it10719[3]);
it106s[4].setIt10618(it10618[4]);
it106s[4].setIt10719(it10719[4]);
AxTxi[] txi = {new AxTxi(), new AxTxi(), new AxTxi(), new AxTxi(), new AxTxi()};
txi[0].setTxi(txi01_GST[0], txi02_GST[0], txi03_GST[0], txi06_GST[0]);
txi[0].setTxi(txi01_PST[0], txi02_PST[0], txi03_PST[0], txi06_PST[0]);
txi[1].setTxi(txi01_GST[1], txi02_GST[1], txi03_GST[1], txi06_GST[1]);
txi[1].setTxi(txi01_PST[1], txi02_PST[1], txi03_PST[1], txi06_PST[1]);
txi[2].setTxi(txi01_GST[2], txi02_GST[2], txi03_GST[2], txi06_GST[2]);
txi[2].setTxi(txi01_PST[2], txi02_PST[2], txi03_PST[2], txi06_PST[2]);
txi[3].setTxi(txi01_GST[3], txi02_GST[3], txi03_GST[3], txi06_GST[3]);
txi[3].setTxi(txi01_PST[3], txi02_PST[3], txi03_PST[3], txi06_PST[3]);
txi[4].setTxi(txi01_GST[4], txi02_GST[4], txi03_GST[4], txi06_GST[4]);
txi[4].setTxi(txi01_PST[4], txi02_PST[4], txi03_PST[4], txi06_PST[4]);
AxIt1Loop it1Loop = new AxIt1Loop();
it1Loop.setIt1Loop(it102[0], it103[0], it104[0], it105[0], it106s[0], txi[0], pam05[0],
it1Loop.setIt1Loop(it102[1], it103[1], it104[1], it105[1], it106s[1], txi[1], pam05[1],
it1Loop.setIt1Loop(it102[2], it103[2], it104[2], it105[2], it106s[2], txi[2], pam05[2],
it1Loop.setIt1Loop(it102[3], it103[3], it104[3], it105[3], it106s[3], txi[3], pam05[3],
it1Loop.setIt1Loop(it102[4], it103[4], it104[4], it105[4], it106s[4], txi[4], pam05[4],
AxTable2 table2 = new AxTable2();
table2.setIt1Loop(it1Loop);
//Create Table 3 with details
AxTxi taxTbl3 = new AxTxi();
taxTbl3.setTxi("GS", "4.25","",""); //sum of GST taxes
taxTbl3.setTxi("PG", "4.60","",""); //sum of PST taxes
taxTbl3.setTxi("TX", "8.85","",""); //sum of all taxes
AxTable3 table3 = new AxTable3();
table3.setTxi(taxTbl3);
Page 243 of 477
pid05[0]);
pid05[1]);
pid05[2]);
pid05[3]);
pid05[4]);
July 2018
7 Level 2/3 Transactions
Sample AX Refund
//Create and set Level23 Object
AxLevel23 level23 = new AxLevel23();
level23.setTable1(table1);
level23.setTable2(table2);
level23.setTable3(table3);
AxRefund axRefund = new AxRefund();
axRefund.setOrderId(order_id);
axRefund.setAmount(amount);
axRefund.setTxnNumber(txn_number);
axRefund.setCryptType(crypt);
axRefund.setAxLevel23(level23);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(axRefund);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
System.out.println("CavvResultCode = " + receipt.getCavvResultCode());
}
catch (Exception e)
{
System.out.println(e);
}
}
}
7.4.8 AX Independent Refund
The AX Independent Refund will credit a specified amount to the cardholder’s credit card. The independent refund does not require an existing order to be logged in the Moneris Gateway; however, the
credit card number and expiry date will need to be passed.
AX Independent Refund transaction object definition
AxIndependentRefund axIndependentRefund = new AxIndependentRefund();
July 2018
Page 244 of 477
Moneris Gateway API - Integration Guide
HttpsPostRequest object for AX Independent Refund transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(axIndependentRefund);
AX Independent Refund transaction object values
Table 1: AX Independent Refund transaction object mandatory values
Value
Type
Limits
Set Method
Order ID
String
50-character alphanumeric
axIndependentRefund
.setOrderId(order_id);
Amount
String
9-character decimal
axIndependentRefund
.setAmount(amount);
Credit card number
String
20-character alphanumeric
axIndependentRefund.setPan
(pan);
Expiry date
String
4-character alphanumeric
axIndependentRefund
.setExpDate(expiry_date);
(YYMM format)
E-commerce indicator
String
1-character alphanumeric
axIndependentRefund
.setCryptType(crypt);
Table 2: AX Independent Refund transaction object optional values
Value
Customer ID
Type
String
Limits
50-character alphanumeric
Set Method
axIndependentRefund
.setCustId(cust_id);
Sample AX Independent Refund
package Level23;
import JavaAPI.*;
public class TestAxIndependentRefund
{
public static void main(String[] args)
{
String store_id = "moneris";
String api_token = "hurgle";
String processing_country_code = "CA";
boolean status_check = false;
java.util.Date createDate = new java.util.Date();
String order_id="Test"+createDate.getTime();
Page 245 of 477
July 2018
7 Level 2/3 Transactions
Sample AX Independent Refund
String
String
String
String
String
cust_id="CUST13343";
amount="62.37";
pan="373269005095005";
expiry_date="2012"; //YYMM
crypt="7";
//Create Table 1 with details
String n101 = "R6"; //Entity ID Code
String n102 = "Retailing Inc. International"; //Name
String n301 = "919 Oriole Rd."; //Address Line 1
String n401 = "Toronto"; //City
String n402 = "On"; //State or Province
String n403 = "H1T6W3"; //Postal Code
String[] ref01 = {"4C", "CR"}; //Reference ID Qualifier
String[] ref02 = {"M5T3A5", "16802309004"}; //Reference ID
String big04 = "PO7758545"; //Purchase Order Number
String big05 = "RN0049858"; //Release Number
String big10 = "INV99870E"; //Invoice Number
AxRef axRef1 = new AxRef();
axRef1.setRef(ref01[0], ref02[0]);
axRef1.setRef(ref01[1], ref02[1]);
AxN1Loop n1Loop = new AxN1Loop();
n1Loop.setN1Loop(n101, n102, n301, n401, n402, n403, axRef1);
AxTable1 table1 = new AxTable1();
table1.setBig04(big04);
table1.setBig05(big05);
table1.setBig10(big10);
table1.setN1Loop(n1Loop);
//Create Table 2
//the sum of the
String[] it102 =
String[] it103 =
String[] it104 =
String[] it105 =
with details
extended amount field (pam05) must equal the level 1 amount field
{"1", "1", "1", "1", "1"}; //Line item quantity invoiced
{"EA", "EA", "EA", "EA", "EA"}; //Line item unit or basis of measurement code
{"10.00", "25.00", "8.62", "10.00", "-10.00"}; //Line item unit price
{"", "", "", "", ""}; //Line item basis of unit price code
String[] it10618 = {"MG", "MG", "MG", "MG", "MG"}; //Product/Service ID qualifier
String[] it10719 = {"DJFR4", "JFJ49", "FEF33", "FEE43", "DISCOUNT"}; //Product/Service ID
(corresponds to it10618)
String[]
String[]
String[]
String[]
txi01_GST
txi02_GST
txi03_GST
txi06_GST
=
=
=
=
{"GS", "GS", "GS", "GS", "GS"}; //Tax type code
{"0.70", "1.75", "1.00", "0.80","0.00"}; //Monetary amount
{"", "", "", "",""}; //Percent
{"", "", "", "",""}; //Tax exempt code
String[] txi01_PST = {"PG", "PG", "PG","PG","PG"}; //Tax type code
String[] txi02_PST = {"0.80", "2.00", "1.00", "0.80","0.00"}; //Monetary amount
String[] txi03_PST = {"", "", "", "",""}; //Percent
String[] txi06_PST = {"", "", "", "",""}; //Tax exempt code
String[] pam05 = {"11.50", "28.75", "10.62", "11.50", "-10.00"}; //Extended line-item amount
String[] pid05 = {"Stapler", "Lamp", "Bottled Water", "Fountain Pen", "DISCOUNT"}; //Line item
description
AxIt106s[] it106s = {new AxIt106s(), new AxIt106s(), new AxIt106s(), new AxIt106s(), new AxIt106s
()};
it106s[0].setIt10618(it10618[0]);
it106s[0].setIt10719(it10719[0]);
it106s[1].setIt10618(it10618[1]);
July 2018
Page 246 of 477
Moneris Gateway API - Integration Guide
Sample AX Independent Refund
it106s[1].setIt10719(it10719[1]);
it106s[2].setIt10618(it10618[2]);
it106s[2].setIt10719(it10719[2]);
it106s[3].setIt10618(it10618[3]);
it106s[3].setIt10719(it10719[3]);
it106s[4].setIt10618(it10618[4]);
it106s[4].setIt10719(it10719[4]);
AxTxi[] txi = {new AxTxi(), new AxTxi(), new AxTxi(), new AxTxi(), new AxTxi()};
txi[0].setTxi(txi01_GST[0], txi02_GST[0], txi03_GST[0], txi06_GST[0]);
txi[0].setTxi(txi01_PST[0], txi02_PST[0], txi03_PST[0], txi06_PST[0]);
txi[1].setTxi(txi01_GST[1], txi02_GST[1], txi03_GST[1], txi06_GST[1]);
txi[1].setTxi(txi01_PST[1], txi02_PST[1], txi03_PST[1], txi06_PST[1]);
txi[2].setTxi(txi01_GST[2], txi02_GST[2], txi03_GST[2], txi06_GST[2]);
txi[2].setTxi(txi01_PST[2], txi02_PST[2], txi03_PST[2], txi06_PST[2]);
txi[3].setTxi(txi01_GST[3], txi02_GST[3], txi03_GST[3], txi06_GST[3]);
txi[3].setTxi(txi01_PST[3], txi02_PST[3], txi03_PST[3], txi06_PST[3]);
txi[4].setTxi(txi01_GST[4], txi02_GST[4], txi03_GST[4], txi06_GST[4]);
txi[4].setTxi(txi01_PST[4], txi02_PST[4], txi03_PST[4], txi06_PST[4]);
AxIt1Loop it1Loop = new AxIt1Loop();
it1Loop.setIt1Loop(it102[0], it103[0], it104[0], it105[0], it106s[0], txi[0], pam05[0],
it1Loop.setIt1Loop(it102[1], it103[1], it104[1], it105[1], it106s[1], txi[1], pam05[1],
it1Loop.setIt1Loop(it102[2], it103[2], it104[2], it105[2], it106s[2], txi[2], pam05[2],
it1Loop.setIt1Loop(it102[3], it103[3], it104[3], it105[3], it106s[3], txi[3], pam05[3],
it1Loop.setIt1Loop(it102[4], it103[4], it104[4], it105[4], it106s[4], txi[4], pam05[4],
AxTable2 table2 = new AxTable2();
table2.setIt1Loop(it1Loop);
//Create Table 3 with details
AxTxi taxTbl3 = new AxTxi();
taxTbl3.setTxi("GS", "4.25","",""); //sum of GST taxes
taxTbl3.setTxi("PG", "4.60","",""); //sum of PST taxes
taxTbl3.setTxi("TX", "8.85","",""); //sum of all taxes
AxTable3 table3 = new AxTable3();
table3.setTxi(taxTbl3);
pid05[0]);
pid05[1]);
pid05[2]);
pid05[3]);
pid05[4]);
//Create and set Level23 Object
AxLevel23 level23 = new AxLevel23();
level23.setTable1(table1);
level23.setTable2(table2);
level23.setTable3(table3);
AxIndependentRefund axIndependentRefund = new AxIndependentRefund();
axIndependentRefund.setOrderId(order_id);
axIndependentRefund.setCustId(cust_id);
axIndependentRefund.setAmount(amount);
axIndependentRefund.setPan(pan);
axIndependentRefund.setExpDate(expiry_date);
axIndependentRefund.setCryptType(crypt);
axIndependentRefund.setAxLevel23(level23);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(axIndependentRefund);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
Page 247 of 477
July 2018
7 Level 2/3 Transactions
Sample AX Independent Refund
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
System.out.println("CavvResultCode = " + receipt.getCavvResultCode());
}
catch (Exception e)
{
System.out.println(e);
}
}
}
July 2018
Page 248 of 477
8 MPI
l
l
l
l
l
l
8.1
8.2
8.3
8.4
8.5
8.6
About MPI Transactions
3-D Secure Implementations (VbV, MCSC, SafeKey)
Activating VbV and MCSC
Activating Amex SafeKey
Transaction Flow for MPI
MPI Transactions
8.1 About MPI Transactions
The Moneris Gateway can enable transactions using the 3-D Secure protocol via Merchant Plug-In (MPI)
and Access Control Server (ACS) .
Moneris Gateway supports the following 3-D Secure implementations:
l
l
l
Verified by Visa (VbV)
Mastercard Secure Code (MCSC)
American Express SafeKey (applies to Canadian integrations only)
8.2 3-D Secure Implementations (VbV, MCSC, SafeKey)
Verified by Visa (VbV), MasterCard Secure Code (MCSC) and American Express SafeKey are programs
based on the 3-D Secure Protocol to improve the security of online transactions.
These programs involve authentication of the cardholder during an online e-commerce transaction.
Authentication is based on the issuer’s selected method of authentication.
The following are examples of authentication methods:
l
l
l
Risk-based authentication
Dynamic passwords
Static passwords.
Some benefits of these programs are reduced risk of fraudulent transactions and protection against
chargebacks for certain fraudulent transactions.
Additional eFraud features
To further decrease fraudulent activity, Moneris also recommends implementing the following features:
l
l
AVS: Address Verification Service (page 286)
CVD: Card Validation Digits ().
July 2018
Page 250 of 477
Moneris Gateway API - Integration Guide
8.3 Activating VbV and MCSC
To integrate Verified by Visa and/or MasterCard Secure Code transaction functionality in your system,
call Moneris Sales Support to have Moneris enroll you in the program(s) and enable the functionality on
your account.
8.4 Activating Amex SafeKey
To Activate Amex SafeKey transaction functionality with your system via the Moneris Gateway API:
1. Enroll in the SafeKey program with American Express
at: https://network.americanexpress.com/ca/en/safekey/index.aspx
2. Call your Moneris sales centre at 1-855-465-4980 to get Amex SafeKey functionality enabled on
your account.
8.5 Transaction Flow for MPI
Figure 3: Transaction flow diagram
1. Cardholder enters the credit card number and submits the transaction information to the merchant.
2. Upon receiving the transaction request, the merchant calls the MonerisMPI API and passes a
TXN type request. For sample code please refer to MpiTxn Request Transaction (page 255).
3. The Moneris MPI receives the request, authenticates the merchant and sends the transaction
information to Visa, MasterCard or American Express.
4. Visa/MasterCard/Amex verifies that the card is enrolled and returns the issuer URL.
5. Moneris MPI receives the response from Visa, MasterCard or Amex and forwards the information to the merchant.
6. The MonerisMPI API installed at the merchant receives the response from the Moneris MPI.
If the response is "Y" for enrolled, the merchant makes a call to the API, which opens a popup/inline window in the cardholder browser.
If the response is “N” for not enrolled, a transaction could be sent to the processor identifying it
as VBV/MCSC/SafeKey attempted with an ECI value of 6.
Page 251 of 477
July 2018
8 MPI
7.
8.
9.
10.
11.
12.
If the response is “U” for unable to authenticate or the response times out, the transaction can
be sent to the processor with an ECI value of 7. The merchant can then choose to continue with
the transaction and be liable for a chargeback, or the merchant can choose to end the transaction.
The cardholder browser uses the URL that was returned from Visa/MasterCard/Amex via the merchant to communicate directly to the bank. The contents of the popup are loaded and the cardholder enters the PIN.
The information is submitted to the bank and authenticated. A response is then returned to the
client browser.
The client browser receives the response from the bank, and forwards it to the merchant.
The merchant receives the response information from the cardholder browser, and passes an
ACS request type to the Moneris MPI API.
Moneris MPI receives the ACS request and authenticates the information. The Moneris MPI then
provides a CAVV value (getCavv()) and a crypt type (getMpiEciO) to the merchant.
If the getSuccess() of the response is “true”, the merchant may proceed with the cavv purchase
or cavv preauth.
If the getSuccess() of the response is “false” and the getMessage() is “N”, the transaction must be
cancelled because the cardholder failed to authenticate.
If the getSuccess() of the response is “false” and the getMessage is “U”, the transaction can be
processed as a normal purchase or PreAuth; however in this case the merchant assumes liability
of a chargeback.
If the response times out, the transaction can be processed as a normal purchase or PreAuth;
however in this case the merchant assumes liability of a chargeback.
The merchant retrieves the CAVV value, and formats a cavv purchase or a cavv preauth request
using the method that is normally used. As part of this transaction method, the merchant must
pass the CAVV value and the crypt type.
8.6 MPI Transactions
Any of the transaction objects that are defined in this section can be passed to the HttpsPostRequest
connection object defined in Section 16.5 (page 384)here.
TXN
Sends the initial transaction data to the Moneris MPI to verify whether the card is enrolled.
The browser returns a PARes as well as a success field.
ACS
Passes the PARes (received in the response to the TXN transaction) to the Moneris MPI API.
Cavv Purchase
After receiving confirmation from the ACS transaction, this verifies funds on the customer’s
card, removes the funds and prepares them for deposit into the merchant’s account.
Cavv Pre-Authorization
After receiving confirmation from the ACS transaction, this verifies and locks funds on the customer’s credit card. The funds are locked for a specified amount of time based on the card
issuer.
July 2018
Page 252 of 477
Moneris Gateway API - Integration Guide
To retrieve the funds that have been locked by a Pre-Authorization transaction so that they
may be settled in the merchant’s account, a basic Completion transaction (page 23) must be
performed. A PreAuthorization transaction may only be "completed" once.
NOTE: Cavv Purchase and Cavv Pre-Authorization transactions are also used to process
Apple Pay and Android Pay transactions. For further details on how to process these wallet
transactions, please refer to 10 Apple Pay In-App and on the Web Integration.
8.6.1 VbV, MCSC and SafeKey Responses
For each transaction, a crypt type is sent to identify whether it is a VbV-, MCSC- or SafeKey-authenticated
transaction. Below are the tables defining the possible crypt types as well as the possible VARes and
PARes responses.
Table 71: Crypt type definitions
Crypt
type
5
Visa definition
l
l
6
l
l
7
l
l
l
Fully authenticated
There is a liability shift,
and the merchant is protected from chargebacks
VbV has been attempted
There is a liability shift,
and the merchant is protected from certain
chargebacks on fraudulent transactions
Non-VbV transaction
No liability shift
Merchant is not protected from chargebacks
Page 253 of 477
MasterCard definition
l
l
l
l
l
l
l
Fully authenticated
There is a liability shift,
and the merchant is protected from chargebacks.
MCSC has been attempted
There is a liability shift,
and the merchant is protected from certain
chargebacks on fraudulent transactions
Non-MCSC transaction
No liability shift
Merchant is not protected from chargebacks
American Express Definition
l
l
l
l
l
l
l
Fully authenticated
There is a liability shift,
and the merchant is protected from chargebacks.
SafeKey has been attempted
There is a liability shift,
and the merchant is protected from certain
chargebacks on fraudulent transactions
Non-SafeKey transaction
No liability shift
Merchant is not protected from chargebacks
July 2018
8 MPI
Table 72: VERes response definitions
VERes Response
Response Definition
N
The card/issuer is not enrolled.
Sent as a normal Purchase/PreAuth transaction with a crypt type of 6.
U
The card type is not participating in VbV/MCSC/SafeKey. It could be corporate
card or another card plan that Visa/MasterCard/Amex excludes.
Proceed with a regular transaction with a crypt type of 7 or cancel the transaction.
Y
The card is enrolled.
Proceed to create the VbV/MCSC/SafeKey inline window for cardholder authentication. Proceed to PARes for crypt type.
Table 73: PARes response definitions
PARes response
Response definition
A
Attempted to verify PIN, and will receive a CAVV.
Send as a cavv_purchase/cavv_preAuth, which returns a crypt type of 6.
Y
Fully authenticated, and will receive a CAVV.
Send as a cavv_purchase/cavv_preAuth which will return a crypt type of 5.
N
Failed to authenticate. No CAVV is returned.
Cancel transaction.
Merchant may proceed with a crypt type of 7 although this is strongly discouraged.
Table 74: 3-D Secure/CAVV transaction handling
Step 1: VERes
Step 2: PARes
Cardholder/issuer
enrolled?
VbV/MCSC InLine
window response
Step 3: Transaction
Are you protected?
Y
Y
Send a CAVV transaction
Y
N
Cancel transaction. Authentication failed or high-risk
transaction.
Y
A
Send a CAVV transaction
U
n/a
Send a regular transaction with a crypt type of 7
N
n/a
Send a regular transaction with a crypt type of 6
July 2018
Page 254 of 477
Moneris Gateway API - Integration Guide
8.6.2 MpiTxn Request Transaction
MpiTxn transaction object definition
MpiTxn mpiTxn = new MpiTxn();
HttpsPostRequest object for MpiTxn transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(mpiTxn);
MpiTxn transaction values
For a full description of mandatory and optional values, see Appendix A Definitions of Request Fields
Table 75: MpiTxn transaction object mandatory values
Value
Type
Limits
Set method
XID
String
20-character alphanumeric
mpiTxn.setXid(xid);
Credit card number
String
20-character numeric
mpiTxn.setPan(pan);
Expiry date
String
4-character alphanumeric
mpiTxn.setExpDate(expiry_
date);
(YYMM format)
Amount
String
9-character decimal
mpiTxn.setAmount(amount);
Must contain at least 3
digits including two
penny values.
MD
String
1024-character alphanumeric
mpiTxn.setMD(MD);
Merchant URL
String
N/A
mpiTxn.setMerchantUrl
(merchantUrl);
Accept
String
N/A
mpiTxn.setAccept(accept);
User Agent
String
N/A
mpiTxn.setUserAgent
(userAgent);
Page 255 of 477
July 2018
8 MPI
Sample MpiTxn Request
package Canada;
import JavaAPI.*;
public class TestCanadaMpiTxn
{
public static void main(String[] args)
{
String store_id = "moneris";
String api_token = "hurgle";
String amount = "1.00";
String xid = "12345678910111214037";
String MD = xid + "mycardinfo" + amount;
String merchantUrl = "www.mystoreurl.com";
String accept = "true";
String userAgent = "Mozilla";
String processing_country_code = "CA";
String pan = "4242424242424242";
String expdate = "1905";
boolean status_check = false;
MpiTxn mpiTxn = new MpiTxn();
mpiTxn.setXid(xid);
mpiTxn.setPan(pan);
mpiTxn.setExpDate(expdate);
mpiTxn.setAmount(amount);
mpiTxn.setMD(MD);
mpiTxn.setMerchantUrl(merchantUrl);
mpiTxn.setHttpAccept(accept);
mpiTxn.setHttpUserAgent(userAgent);
//************************OPTIONAL VARIABLES***************************
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production
transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(mpiTxn);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
/********************** REQUEST ************************/
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("MpiMessage = " + receipt.getMpiMessage());
System.out.println("MpiSuccess = " + receipt.getMpiSuccess());
if (receipt.getMpiSuccess().equals("true"))
{
System.out.println(receipt.getMpiInLineForm());
}
else
{
System.out.println(receipt.getMessage());
}
}
catch (Exception e)
{
e.printStackTrace();
}
}
} // end TestResMpiTxn
July 2018
Page 256 of 477
Moneris Gateway API - Integration Guide
8.6.2.1 TXN Response and Creating the Popup
The TXN request returns a response with one of several possible values. The get Message method of the
response object returns “Y”, “U”, or “N”.
N
Purchase or Pre-Authorization can be sent as a crypt type of 6 (attempted authentication).
Y
A call to the API to create the VBV form is made.
U
(Returned for non-participating cards such as corporate cards)
Merchant can send the transaction with crypt_type 7. However, the merchant is liable for
chargebacks.
Below is the TXN response code. This code can be found from the store.java sample included in the download.
MpiResponse mpiRes = mpiReq.getResponse();
String crypt_type;
if (mpiRes.getMessage().equals("Y") )
{
out.print(mpiRes.getInLineForm());
}
else {
if (mpiRes.getMessage().equals("N") )
{
//send transaction using the mpg API
// use crypt_type="6";
}
else // corporate cards, unable to authenticate or times out (eg. MPI is down)
{
//optional to send transaction using the mpg API in this case merchant
//assumes liability, use crypt_type="7";
}
}
8.6.3 Vault MPI Transaction – ResMpiTxn
Vault MPI Transaction transaction object definition
ResMpiTxn resMpiTxn = new ResMpiTxn();
HttpsPostRequest object for Vault MPI Transaction transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(resMpiTxn);
Vault MPI Transaction transaction values
For a full description of mandatory and optional values, see Appendix A Definitions of Request Fields
Page 257 of 477
July 2018
8 MPI
Table 76: Vault MPI Transaction transaction object mandatory values
Value
Type
Limits
Set method
Data key
String
25-character alphanumeric
resMpiTxn.setData(data_key);
XID
String
20-character alphanumeric
resMpiTxn.setXid(xid);
Amount
String
9-character decimal
resMpiTxn.setAmount(amount);
MD
String
1024-character alphanumeric
resMpiTxn.setMD(MD);
Merchant URL
String
n/a
resMpiTxn.setMerchantUrl
(merchantUrl);
Accept
String
n/a
resMpiTxn.setAccept(accept);
User Agent
String
n/a
resMpiTxn.setUserAgent
(userAgent);
Expiry date
String
4-character alphanumeric
resMpiTxn.setExpDate(expiry_
date);
(YYMM format)
Sample Vault MPI Transaction
package Canada;
import java.util.HashMap;
import java.util.Map;
import JavaAPI.*;
public class TestCanadaResMpiTxn
{
public static void main(String[] args)
{
String store_id = "store5";
String api_token = "yesguy";
String data_key = "ot-7hkuLdmybbHdUD0y2gCXQQx6J";
String amount = "1.00";
java.util.Date createDate = new java.util.Date();
String xid = "TEMPXID"+ createDate.getTime();
String MD = xid + "mycardinfo" + amount;
String merchantUrl = "www.mystoreurl.com";
String accept = "true";
String userAgent = "Mozilla";
String processing_country_code = "CA";
String expdate = "1712";
boolean status_check = false;
July 2018
Page 258 of 477
Moneris Gateway API - Integration Guide
Sample Vault MPI Transaction
ResMpiTxn resMpiTxn = new ResMpiTxn();
resMpiTxn.setData(data_key);
resMpiTxn.setXid(xid);
resMpiTxn.setAmount(amount);
resMpiTxn.setMD(MD);
resMpiTxn.setMerchantUrl(merchantUrl);
resMpiTxn.setAccept(accept);
resMpiTxn.setUserAgent(userAgent);
resMpiTxn.setExpDate(expdate);
//************************OPTIONAL VARIABLES***************************
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(resMpiTxn);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
/********************** REQUEST ************************/
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("MpiMessage = " + receipt.getMpiMessage());
System.out.println("MpiSuccess = " + receipt.getMpiSuccess());
if (receipt.getMpiSuccess().equals("true"))
{
System.out.println(receipt.getMpiInLineForm());
}
}
catch (Exception e)
{
e.printStackTrace();
}
}
} // end TestResMpiTxn
Vault response fields
For a list and explanation of (Receipt object) response fields that are available after sending this Vault
transaction, see Definitions of Response Fields (page 440).
8.6.4 MPI ACS Request Transaction
MPI ACS Request transaction object definition
MpiAcs mpiAcs = new MpiAcs();
HttpsPostRequest object for MPI ACS Request transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(mpiAcs);
Page 259 of 477
July 2018
8 MPI
MPI ACS Request transaction values
For a full description of mandatory and optional values, see Appendix A Definitions of Request Fields
Table 77: MPI ACS Request transaction object mandatory values
Value
Type
Limits
XID
String
20-character alphanumeric
Amount
String
9-character decimal
Set method
NOTE: Is the concatenated 20-character
prefix that forms part of the variable MD
mpiAcs.setAmount(amount);
Must contain at least 3
digits including two
penny values.
MD
String
1024-character alphanumeric
mpiAcs.setMD(MD);
PARes
String
n/a
mpiAcs.setPaRes(PaRes);
Sample MPI ACS Request - CA
package Canada;
import JavaAPI.*;
public class TestCanadaMpiAcs
{
public static void main(String[] args)
{
String store_id = "moneris";
String api_token = "hurgle";
String amount = "1.00";
String xid = "12345678910111214011";
String MD = xid + "mycardinfo" + amount;
String PaRes = "PaRes string";
String processing_country_code = "CA";
boolean status_check = false;
MpiAcs mpiAcs = new MpiAcs();
mpiAcs.setPaRes(PaRes);
mpiAcs.setMD(MD);
//************************OPTIONAL VARIABLES***************************
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(mpiAcs);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
/********************** REQUEST ************************/
try
{
July 2018
Page 260 of 477
Moneris Gateway API - Integration Guide
Sample MPI ACS Request - CA
Receipt receipt = mpgReq.getReceipt();
System.out.println("MpiMessage = " + receipt.getMpiMessage());
System.out.println("MpiSuccess = " + receipt.getMpiSuccess());
if (receipt.getMpiSuccess().equals("true"))
{
System.out.println("CAVV = " + receipt.getMpiCavv());
System.out.println("Crypt Type = " + receipt.getMpiEci());
}
}
catch (Exception e)
{
e.printStackTrace();
}
}
} // end TestResMpiTxn
8.6.4.1 ACS Response and Forming a Transaction
The ACS response contains the CAVV value and the e-commerce indicator. These values are to be passed
to the transaction engine using the Cavv Purchase or Cavv Pre-Authorization request. Please see the documentation provided by your payment solution.
Outlined below is how to send a transaction to Moneris Gateway.
if ( mpiRes.getSuccess().equals("true") )
{
//Send transaction to host using CAVV purchase or CAVV preauth, refer to sample
//code for Moneris Gateway. Call mpiRes.getCavv() to obtain the CAVV value.
//If you are using preauth/capture model, be sure to call getMessage() so the
//value can be stored and used in the capture transaction after on to protect
//your chargeback liability. (e.g. getMPIMessage()= A = crypt type of 6 for
//follow on transaction and getMPIMessage() = Y = crypt type of 5 for follow on
//transaction.
}
else
{
if (mpiRes.getMessage().equals(“N”))
{
//Do not send transaction as the cardholder failed authentication.
}
else
{
//Optional to send transaction using the mpg API. In this case merchant
//assumes liability.
}
}
8.6.5 Purchase with 3-D Secure – cavvPurchase
The Purchase with 3-D Secure transaction follows a 3-D Secure MPI authentication. After receiving confirmation from the MPI ACS transaction, this Purchase verifies funds on the customer’s card, removes
the funds and prepares them for deposit into the merchant’s account.
To perform the 3-D Secure authentication, the Moneris MPI or any 3rd party MPI may be used.
Page 261 of 477
July 2018
8 MPI
This transaction can also be used to process an Apple Pay transaction. This transaction is applicable only
if choosing to integrate directly to Apple Wallet (if not using the Moneris Apple Pay SDK). Please refer to
10 Apple Pay In-App and on the Web Integration for more details on your integration options.
Refer to Apple's developer portal for details on integrating directly to the wallet to retrieve the payload
data.
Purchase with 3-D Secure transaction object definition
CavvPurchase cavvPurchase = new CavvPurchase();
HttpsPostRequest object for Purchase with 3-D Secure transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(cavvPurchase);
Cavv Purchase transaction values
For a full description of mandatory and optional values, see Appendix A Definitions of Request Fields
Table 78: Purchase with 3-D Secure transaction object mandatory values
Value
Type
Limits
Set method
Order ID
String
50-character alphanumeric
cavvPurchase.setOrderId
(order_id);
Amount
String
9-character decimal
cavvPurchase.setAmount
(amount);
Credit card number
String
20-character alphanumeric
cavvPurchase.setPan(pan);
July 2018
Page 262 of 477
Moneris Gateway API - Integration Guide
Table 78: Purchase with 3-D Secure transaction object mandatory values
Value
Expiry date
Type
String
Limits
4-character alphanumeric
Set method
cavvPurchase.setExpDate
(expiry_date);
(YYMM format)
CAVV
String
50-character alphanumeric
cavvPurchase.setCavv(cavv);
String
1-character alphanumeric
cavvPurchase.setCryptType
(crypt);
NOTE: For Apple Pay
Cavv Purchase and
Cavv Pre-Authorization
transactions, CAVV
field contains the
decrypted cryptogram.
For more, see
Appendix A Definitions
of Request Fields.
E-commerce indicator
NOTE: For Apple Pay
Cavv Purchase and
Cavv Pre-Authorization
transactions, the Ecommerce indicator is
a mandatory field containing the value
received from the
decrypted payload or a
default value of 5. If
you get a 2-character
value (e.g.,. 05 or 07)
from the payload,
remove the initial 0
and just send us the
2nd character. For
more, see Appendix A
Definitions of Request
Fields.
Page 263 of 477
July 2018
8 MPI
Table 1: INTERAC® e-Commerce Fields – Required for Apple Pay and Google Pay Only
Variable and Field
Name
Network
Type
Limits
Set Method
String
alphabetical
cavvPurchase.SetNetwork
(network);
String
3-character alphanumeric
cavvPurchase.SetDataType
(data_type);
NOTE: This request
variable is mandatory
for INTERAC® e-Commerce transactions conducted via Apple Pay,
and is not for use with
credit card transactions.
Data Type
NOTE: This request
variable is mandatory
for INTERAC® e-Commerce transactions conducted via Apple Pay,
and is not for use with
credit card transactions.
Table 2: Purchase with 3-D Secure transaction object optional values
Value
Type
Limits
Set Method
Status Check
Boolean
true/false
mpgReq.setStatusCheck
(status_check);
Customer ID
String
50-character alphanumeric
cavvPurchase.setCustId(cust_
id);
Dynamic descriptor
String
20-character alphanumeric
cavvPurchase
.setDynamicDescriptor
(dynamic_descriptor);
Customer information
Object
N/A
CustInfo customer = new
CustInfo();
cavvPurchase.setCustInfo
(customer);
AVS
July 2018
Object
N/A
AvsInfo avsCheck = new
AvsInfo();
Page 264 of 477
Moneris Gateway API - Integration Guide
Value
Type
Limits
Set Method
cavvPurchase.setAvsInfo
(avsCheck);
CVD
Object
N/A
CvdInfo cvdCheck = new
CvdInfo();
cavvPurchase.setCvdInfo
(cvdCheck);
Convenience fee
NOTE: Not applicable
when processing
Apple Pay transactions.
Page 265 of 477
Object
N/A
ConvFeeInfo convFeeInfo =
new ConvFeeInfo();
cavvPurchase
.setConvenienceFee
(convFeeInfo);
July 2018
8 MPI
Value
Recurring billing
Type
Limits
Set Method
Object
N/A
cavvPurchase.setRecurInfo
(recurInfo);
String
3-character alphanumeric
cavvPurchase
.setWalletIndicator(wallet_
indicator);
Object
N/A
cof.setCofInfo(cof);
recur
NOTE: For sample
code for a Purchase
with 3-D Secure including the Recurring
Billing Info Object,
see 8.6.5.1 Purchase
with 3-D Secure and
Recurring Billing .
Wallet indicator
NOTE: For Cavv
Purchase and Cavv
Pre-Authorization, wallet indicator applies to
Apple Pay or Android
Pay only. For more,
see Appendix A Definitions of Request
Fields
Credential on File Info
cof
NOTE: This is a nested
object within the
transaction, and
required when storing
or using the customer's stored credentials. The
Credential on File Info
object has its own
request variables, listed in blue in the
table below, "Credential on File Object
Request Variables".
July 2018
Page 266 of 477
Moneris Gateway API - Integration Guide
Credential on File Transaction Object Request Fields
Value
Issuer ID
Type
String
NOTE: This variable is
required for all merchant-intiated transactions following the
first one; upon sending
the first transaction,
the Issuer ID value is
received in the transaction response and
then used in subsequent transaction
requests (Issuer ID
does not apply for Discover or Union Pay).
Payment Indicator
Limits
15-character alphanumeric
variable length
String
1-character alphabetic
Set Method
cof.setIssuerId("VALUE_FOR_
ISSUER_ID");
NOTE: For a list and explanation of the
possible values to send for this variable,
see Definitions of Request Fields – Credential on File
cof.setPaymentIndicator
("PAYMENT_INDICATOR_VALUE");
NOTE: For a list and explanation of the
possible values to send for this variable,
see Definitions of Request Fields – Credential on File
Payment Information
String
1-character numeric
cof.setPaymentInformation
("PAYMENT_INFO_VALUE");
NOTE: For a list and explanation of the
possible values to send for this variable,
see Definitions of Request Fields – Credential on File
Recurring Billing Info Object Request Fields
Variable and Field Name
Type and Limits
Number of Recurs
String
num_recurs
numeric, 1-99
Period
String
period
numeric, 1-999
Page 267 of 477
Description
The number of times that the
transaction must recur
Number of recur units that
must pass between recurring
billings
July 2018
8 MPI
Variable and Field Name
Type and Limits
Start Date
String
start_date
YYYY/MM/DD
Description
Date of the first future recurring
billing transaction
This value must be a date in the
future
If an additional charge is to be
made immediately, the value of
Start Now must be set to true
Start Now
String
start_now
true/false
If a single charge is to be made
against the card immediately,
set this value to true; the
amount to be billed immediately may differ from the
amount billed on a regular
basis thereafter
If the billing is to start in the
future, set this value to false
When set to false, use Card Verification prior to sending the
Purchase with Recur and Credential on File objects
Recurring Amount
String
recur_amount
9-character decimal; Up to 6
digits (dollars) + decimal point
+ 2 digits (cents) after the
decimal point
EXAMPLE:
123456.78
Recur Unit
String
recur_unit
day, week, month or eom
Amount of the recurring transaction
This is the amount that will be
billed on the Start Date and
then billed repeatedly based on
the interval defined by Period
and Recur Unit
Unit to be used as a basis for
the interval
Works in conjunction with
Period to define the billing frequency
Possible values are:
day
week
July 2018
Page 268 of 477
Moneris Gateway API - Integration Guide
Variable and Field Name
Type and Limits
Description
month
eom (end of month)
Sample Purchase with 3-D Secure - cavvPurchase
package Canada;
import JavaAPI.*;
public class TestCanadaCavvPurchase
{
public static void main(String[] args)
{
String store_id = "store5";
String api_token = "yesguy";
java.util.Date createDate = new java.util.Date();
String order_id = "Test"+createDate.getTime();
String cust_id = "CUS887H67";
String amount = "10.42";
String pan = "4242424242424242";
String expdate = "1901"; //YYMM
String cavv = "AAABBJg0VhI0VniQEjRWAAAAAAA=";
String dynamic_descriptor = "123456";
String processing_country_code = "CA";
String crypt_type = "5";
boolean status_check = false;
CavvPurchase cavvPurchase = new CavvPurchase();
cavvPurchase.setOrderId(order_id);
cavvPurchase.setCustId(cust_id);
cavvPurchase.setAmount(amount);
cavvPurchase.setPan(pan);
cavvPurchase.setExpdate(expdate);
cavvPurchase.setCavv(cavv);
cavvPurchase.setCryptType(crypt_type); //Mandatory for AMEX only
cavvPurchase.setDynamicDescriptor(dynamic_descriptor);
//cavvPurchase.setWalletIndicator("APP"); //set only for wallet transactions. e.g APPLE PAY
//cavvPurchase.setNetwork("Interac"); //set only for Interac e-commerce
//cavvPurchase.setDataType("3DSecure"); //set only for Interac e-commerce
//optional - Card on File details
CofInfo cof = new CofInfo();
cof.setPaymentIndicator("Z");
cof.setPaymentInformation("0");
cof.setIssurId("139X3130ASCXAS9");
cavvPurchase.setCofInfo(cof);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(cavvPurchase);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
Page 269 of 477
July 2018
8 MPI
Sample Purchase with 3-D Secure - cavvPurchase
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
System.out.println("CavvResultCode = " + receipt.getCavvResultCode());
System.out.println("IssueId = " + receipt.getIssuerId());
}
catch (Exception e)
{
e.printStackTrace();
}
}
}
8.6.5.1 Purchase with 3-D Secure and Recurring Billing
The example below illustrates the Purchase with 3-D Secure when also sending the Recurring Billing Info
object in the transaction.
Purchase with 3-D Secure and Recurring Billing
package Canada;
import JavaAPI.*;
public class TestCanadaCavvPurchaseRecur
{
public static void main(String[] args)
{
String store_id = "store5";
String api_token = "yesguy";
java.util.Date createDate = new java.util.Date();
String order_id = "Test"+createDate.getTime();
String cust_id = "CUS887H67";
String amount = "10.42";
String pan = "4242424242424242";
String expdate = "1901"; //YYMM
String cavv = "AAABBJg0VhI0VniQEjRWAAAAAAA=";
String dynamic_descriptor = "123456";
String processing_country_code = "CA";
String crypt_type = "5";
boolean status_check = false;
/************************* Recur Variables **********************************/
String recur_unit = "month"; //eom = end of month
String start_now = "true";
String start_date = "2018/02/09";
July 2018
Page 270 of 477
Moneris Gateway API - Integration Guide
Purchase with 3-D Secure and Recurring Billing
String num_recurs = "12";
String period = "1";
String recur_amount = "5.00";
/************************* Recur Object Option1 ******************************/
Recur recurring_cycle = new Recur(recur_unit, start_now, start_date,
num_recurs, period, recur_amount);
CavvPurchase cavvPurchase = new CavvPurchase();
cavvPurchase.setOrderId(order_id);
cavvPurchase.setCustId(cust_id);
cavvPurchase.setAmount(amount);
cavvPurchase.setPan(pan);
cavvPurchase.setExpdate(expdate);
cavvPurchase.setCavv(cavv);
cavvPurchase.setCryptType(crypt_type); //Mandatory for AMEX only
cavvPurchase.setDynamicDescriptor(dynamic_descriptor);
cavvPurchase.setRecur(recurring_cycle);
//cavvPurchase.setWalletIndicator("APP"); //set only for wallet transactions. e.g APPLE PAY
//cavvPurchase.setNetwork("Interac"); //set only for Interac e-commerce
//cavvPurchase.setDataType("3DSecure"); //set only for Interac e-commerce
//Mandatory on Recurs - Credential on File details
CofInfo cof = new CofInfo();
cof.setPaymentIndicator("R");
cof.setPaymentInformation("2");
cof.setIssuerId("139X3130ASCXAS9");
cavvPurchase.setCofInfo(cof);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(cavvPurchase);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
System.out.println("CavvResultCode = " + receipt.getCavvResultCode());
System.out.println("IssuerId = " + receipt.getIssuerId());
}
catch (Exception e)
{
Page 271 of 477
July 2018
8 MPI
Purchase with 3-D Secure and Recurring Billing
e.printStackTrace();
}
}
}
8.6.6 Pre-Authorization with 3-D Secure – cavvPreauth
The Pre-Authorization with 3-D Secure transaction follows a 3-D Secure MPI authentication. After receiving confirmation from the MPI ACS transaction, this Pre-Authorization verifies funds on the customer’s
card, removes the funds and prepares them for deposit into the merchant’s account.
To perform the 3-D Secure authentication, the Moneris MPI or any 3rd party MPI may be used.
This transaction can also be used to process an Apple Pay transaction. This transaction is applicable only
if choosing to integrate directly to Apple Wallet (if not using the Moneris Apple Pay SDK). Please refer to
10 Apple Pay In-App and on the Web Integration for more details on your integration options.
Refer to Apple's developer portal for details on integrating directly to the wallet to retrieve the payload
data.
Pre-Authorization with 3-D Secure transaction object definition
CavvPreAuth cavvPreauth = new CavvPreAuth();
HttpsPostRequest object for Pre-Authorization with 3-D Secure transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(cavvPreauth);
Pre-Authorization with 3-D Secure transaction values
For a full description of mandatory and optional values, see Appendix A Definitions of Request Fields
Table 79: Pre-Authorization with 3-D Secure object mandatory values
Value
Type
Limits
Set method
Order ID
String
50-character alphanumeric
cavvPreauth.setOrderId
(order_id);
Amount
String
9-character decimal
cavvPreauth.setAmount
(amount);
Credit card number
String
20-character numeric
cavvPreauth.setPan(pan);
Cardholder Authentication Verification
Value (CAVV)
String
50-character alphanumeric
cavvPreauth.setCavv(cavv);
July 2018
Page 272 of 477
Moneris Gateway API - Integration Guide
Value
Type
Limits
Set method
NOTE: For Apple Pay
Cavv Purchase and
Cavv Pre-Authorization
transactions, CAVV
field contains the
decrypted cryptogram.
For more, see
Appendix A Definitions
of Request Fields.
Expiry date
String
4-character numeric
cavvPreauth.setExpDate
(expiry_date);
E-commerce indicator
String
1-character alphanumeric
cavvPreauth.setCryptType
(crypt);
NOTE: For Apple Pay
Cavv Purchase and
Cavv Pre-Authorization
transactions, the Ecommerce indicator is
a mandatory field containing the value
received from the
decrypted payload or a
default value of 5. If
you get a 2-character
value (e.g.,. 05 or 07)
from the payload,
remove the initial 0
and just send us the
2nd character. For
more, see Appendix A
Definitions of Request
Fields.
Page 273 of 477
July 2018
8 MPI
Table 1: INTERAC® e-Commerce Fields – Required for Apple Pay and Google Pay Only
Variable and Field
Name
Network
Type
Limits
Set Method
String
alphabetical
cavvPurchase.SetNetwork
(network);
String
3-character alphanumeric
cavvPurchase.SetDataType
(data_type);
NOTE: This request
variable is mandatory
for INTERAC® e-Commerce transactions conducted via Apple Pay,
and is not for use with
credit card transactions.
Data Type
NOTE: This request
variable is mandatory
for INTERAC® e-Commerce transactions conducted via Apple Pay,
and is not for use with
credit card transactions.
Table 2: Pre-Authorization with 3-D Secure object optional values
Value
Type
Limits
Set method
Status Check
Boolean
true/false
mpgReq.setStatusCheck
(status_check);
Customer ID
String
50-character alphanumeric
cavvPreauth.setCustId(cust_
id);
Dynamic descriptor
String
20-character alphanumeric
cavvPreauth
.setDynamicDescriptor
(dynamic_descriptor);
AVS
Object
N/A
AvsInfo avsCheck = new
AvsInfo();
cavvPreauth.setAvsInfo
(avsCheck);
July 2018
Page 274 of 477
Moneris Gateway API - Integration Guide
Value
CVD
Type
Object
Limits
N/A
Set method
CvdInfo cvdCheck = new
CvdInfo();
cavvPreauth.setCvdInfo
(cvdCheck);
Wallet indicator
String
3-character alphanumeric
cavvPreauth
.setWalletIndicator(wallet_
indicator);
Object
N/A
cof.setCofInfo(cof);
NOTE: For Cavv
Purchase and Cavv
Pre-Authorization, wallet indicator applies to
Apple Pay or Android
Pay only. For more,
see Appendix A Definitions of Request
Fields
Credential on File Info
cof
NOTE: This is a nested
object within the
transaction, and
required when storing
or using the customer's stored credentials. The
Credential on File Info
object has its own
request variables, listed in blue in the
table below, "Credential on File Object
Request Variables".
Page 275 of 477
July 2018
8 MPI
Credential on File Transaction Object Request Fields
Value
Issuer ID
Type
String
NOTE: This variable is
required for all merchant-intiated transactions following the
first one; upon sending
the first transaction,
the Issuer ID value is
received in the transaction response and
then used in subsequent transaction
requests (Issuer ID
does not apply for Discover or Union Pay).
Payment Indicator
Limits
15-character alphanumeric
variable length
String
1-character alphabetic
Set Method
cof.setIssuerId("VALUE_FOR_
ISSUER_ID");
NOTE: For a list and explanation of the
possible values to send for this variable,
see Definitions of Request Fields – Credential on File
cof.setPaymentIndicator
("PAYMENT_INDICATOR_VALUE");
NOTE: For a list and explanation of the
possible values to send for this variable,
see Definitions of Request Fields – Credential on File
Payment Information
String
1-character numeric
cof.setPaymentInformation
("PAYMENT_INFO_VALUE");
NOTE: For a list and explanation of the
possible values to send for this variable,
see Definitions of Request Fields – Credential on File
Sample Pre-Authorization with 3-D Secure – cavvPreauth
package Canada;
import JavaAPI.*;
public class TestCanadaCavvPreauth
{
public static void main(String[] args)
{
String store_id = "store5";
String api_token = "yesguy";
java.util.Date createDate = new java.util.Date();
String order_id = "Test"+createDate.getTime();
String cust_id = "CUS887H67";
String amount = "10.42";
String pan = "4242424242424242";
July 2018
Page 276 of 477
Moneris Gateway API - Integration Guide
Sample Pre-Authorization with 3-D Secure – cavvPreauth
String expdate = "1911"; //YYMM format
String cavv = "AAABBJg0VhI0VniQEjRWAAAAAAA=";
String dynamic_descriptor = "123456";
String processing_country_code = "CA";
String crypt_type = "5";
boolean status_check = false;
CavvPreAuth cavvPreauth = new CavvPreAuth();
cavvPreauth.setOrderId(order_id);
cavvPreauth.setCustId(cust_id);
cavvPreauth.setAmount(amount);
cavvPreauth.setPan(pan);
cavvPreauth.setExpdate(expdate);
cavvPreauth.setCavv(cavv);
cavvPreauth.setCryptType(crypt_type); //Mandatory for AMEX only
cavvPreauth.setDynamicDescriptor(dynamic_descriptor);
//cavvPreauth.setWalletIndicator("APP"); //set only for wallet transactions. e.g APPLE PAY
//optional - Card on File details
CofInfo cof = new CofInfo();
cof.setPaymentIndicator("Z");
cof.setPaymentInformation("0");
cof.setIssurId("139X3130ASCXAS9");
cavvPreauth.setCofInfo(cof);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(cavvPreauth);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
System.out.println("CavvResultCode = " + receipt.getCavvResultCode());
System.out.println("IssueId = " + receipt.getIssuerId());
}
catch (Exception e)
{
e.printStackTrace();
}
}
}
Page 277 of 477
July 2018
8 MPI
8.6.7 Cavv Result Codes for Verified by Visa
Table 80: CAVV result codes for VbV
Code
0
Message
Significance
CAVV authentication results
invalid
For this transaction, you may not receive protection from chargebacks as a result of using VbV
because the CAVV was considered invalid at the
time the financial transaction was processed.
Check that you are following the VbV process correctly and passing the correct data in our transactions.
1
CAVV failed validation;
authentication
Provided that you have implemented the VbV
process correctly, the liability for this transaction
should remain with the Issuer for chargeback
reason codes covered by Verified by Visa.
2
CAVV passed validation;
authentication
The CAVV was confirmed as part of the financial
transaction. This transaction is a fully authenticated VbV transaction (ECI 5)
3
CAVV passed validation;
attempt
The CAVV was confirmed as part of the financial
transaction. This transaction is an attempted
VbV transaction (ECI 6)
4
CAVV failed validation;
attempt
Provided that you have implemented the VbV
process correctly the liability for this transaction
should remain with the Issuer for chargeback
reason codes covered by Verified by Visa.
7
CAVV failed validation;
attempt (US issued cards
only)
Please check that you are following the VbV process correctly and passing the correct data in
your transactions.
Provided that you have implemented the VbV
process correctly the liability for this transaction
should be the same as an attempted transaction
(ECI 6)
8
CAVV passed validation;
attempt (US issued cards
only
The CAVV was confirmed as part of the financial
transaction. This transaction is an attempted
VbV transaction (ECI 6)
9
CAVV failed validation;
attempt (US issued cards
Please check that you are following the VbV process correctly and passing the correct data in our
July 2018
Page 278 of 477
Moneris Gateway API - Integration Guide
Table 80: CAVV result codes for VbV (continued)
Code
Message
Significance
only)
transactions.
Provided that you have implemented the VbV
process correctly the liability for this transaction
should be the same as an attempted transaction
(ECI 6)
A
CAVV passed validation;
attempt (US issued cards
only)
The CAVV was confirmed as part of the financial
transaction. This transaction is an attempted
VbV transaction (ECI 6)
B
CAVV passed validation;
information only, no liability
shift
The CAVV was confirmed as part of the financial
transaction. However, this transaction does not
qualify for the liability shift. Treat this transaction
the same as an ECI 7.
8.6.8 Vault Cavv Purchase
Vault Cavv Purchase transaction object definition
ResCavvPurchaseCC resCavvPurchaseCC = new ResCavvPurchaseCC();
HttpsPostRequest object for Vault Cavv Purchase transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(resCavvPurchaseCC);
Vault Cavv Purchase transaction details
Table 81: Vault Cavv Purchase transaction object mandatory values
Value
Type
Limits
Set method
Data Key
String
25-character alphanumeric
resCavvPurchaseCC.setData
(data_key);
Order ID
String
50-character alphanumeric
resCavvPurchaseCC.setOrderId
(order_id);
Amount
String
9-character decimal
resCavvPurchaseCC.setAmount
(amount);
Cardholder Authentication Verification Value
String
50-character alphanumeric
resCavvPurchaseCC.setCavv
(cavv);
Page 279 of 477
July 2018
8 MPI
Table 81: Vault Cavv Purchase transaction object mandatory values
Value
Type
E-commerce indicator
String
Limits
Set method
(CAVV)
1-character alphanumeric
resCavvPurchaseCC
.setCryptType(crypt);
Table 82: Vault Cavv Purchase transaction object optional values
Value
Type
Limits
Set method
Customer ID
String
50-character alphanumeric
resCavvPurchaseCC.setCustId
(cust_id);
Status Check
Boolean
true/false
mpgReq.setStatusCheck
(status_check);
Expiry date
String
4-character alphanumeric
resCavvPurchaseCC.setExpDate
(expiry_date);
(YYMM format)
Sample Vault Cavv Purchase
package Canada;
import JavaAPI.*;
public class TestCanadaResCavvPurchaseCC
{
public static void main(String[] args)
{
String store_id = "store1";
String api_token = "yesguy";
String data_key = "4INQR1A8ocxD0oafSz50LADXy";
java.util.Date createDate = new java.util.Date();
String order_id = "Test"+createDate.getTime();
String amount = "1.00";
String cust_id = "customer1"; //if sent will be submitted, otherwise cust_id from profile will be
used
String cavv = "AAABBJg0VhI0VniQEjRWAAAAAAA";
String processing_country_code = "CA";
String exp_date = "1901";
boolean status_check = false;
ResCavvPurchaseCC resCavvPurchaseCC = new ResCavvPurchaseCC();
resCavvPurchaseCC.setOrderId(order_id);
resCavvPurchaseCC.setData(data_key);
resCavvPurchaseCC.setCustId(cust_id);
resCavvPurchaseCC.setAmount(amount);
resCavvPurchaseCC.setCavv(cavv);
resCavvPurchaseCC.setExpDate(exp_date);
July 2018
Page 280 of 477
Moneris Gateway API - Integration Guide
Sample Vault Cavv Purchase
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(resCavvPurchaseCC);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("DataKey = " + receipt.getDataKey());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Message = " + receipt.getMessage());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("TimedOut = " + receipt.getTimedOut());
System.out.println("ResSuccess = " + receipt.getResSuccess());
System.out.println("PaymentType = " + receipt.getPaymentType());
System.out.println("CavvResultCode = " + receipt.getCavvResultCode());
//ResolveData
System.out.println("Cust ID = " + receipt.getResCustId());
System.out.println("Phone = " + receipt.getResPhone());
System.out.println("Email = " + receipt.getResEmail());
System.out.println("Note = " + receipt.getResNote());
System.out.println("Masked Pan = " + receipt.getResMaskedPan());
System.out.println("Exp Date = " + receipt.getResExpdate());
System.out.println("Crypt Type = " + receipt.getResCryptType());
System.out.println("Avs Street Number = " + receipt.getResAvsStreetNumber());
System.out.println("Avs Street Name = " + receipt.getResAvsStreetName());
System.out.println("Avs Zipcode = " + receipt.getResAvsZipcode());
}
catch (Exception e)
{
e.printStackTrace();
}
}
}
8.6.9 Vault Cavv Pre-Authorization
Vault Cavv Pre-Authorization transaction object definition
ResCavvPreAuthCC resCavvPreauthCC = new ResCavvPreAuthCC();
HttpsPostRequest object for Vault Cavv Pre-Authorization
HttpsPostRequest mpgReq = new HttpsPostRequest();
Page 281 of 477
July 2018
8 MPI
mpgReq.setTransaction(resCavvPreauthCC);
Vault Cavv Pre-Authorization transaction details
Table 83: Vault Cavv Pre-Authorization object mandatory values
Value
Type
Limits
Set method
Data Key
String
25-character alphanumeric
resCavvPreauthCC.setData
(data_key);
Order ID
String
50-character alphanumeric
resCavvPreauthCC.setOrderId
(order_id);
Amount
String
9-character decimal
resCavvPreauthCC.setAmount
(amount);
CAVV
String
50-character alphanumeric
resCavvPreauthCC.setCavv
(cavv);
E-commerce indicator
String
1-character alphanumeric
resCavvPreauthCC
.setCryptType(crypt);
Table 84: Vault Cavv Pre-Authorization object optional values
Value
Customer ID
Type
String
Limits
50-character
alphanumeric
Set method
resCavvPreauthCC.setCustId
(cust_id);
Status Check
Boolean
true/false
mpgReq.setStatusCheck
(status_check);
Expiry date
String
4-character numeric
resCavvPreauthCC.setExpDate
(expiry_date);
Sample Vault Cavv Pre-Authorization
package Canada;
import JavaAPI.*;
public class TestCanadaResCavvPreauthCC
{
public static void main(String[] args)
{
String store_id = "store1";
String api_token = "yesguy";
String data_key = "4INQR1A8ocxD0oafSz50LADXy";
java.util.Date createDate = new java.util.Date();
July 2018
Page 282 of 477
Moneris Gateway API - Integration Guide
Sample Vault Cavv Pre-Authorization
String order_id = "Test"+createDate.getTime();
String amount = "1.00";
String cust_id = "customer1"; //if sent will be submitted, otherwise cust_id from profile will be
used
String cavv = "AAABBJg0VhI0VniQEjRWAAAAAAA";
String processing_country_code = "CA";
String expdate = "1901";
boolean status_check = false;
ResCavvPreauthCC resCavvPreauthCC = new ResCavvPreauthCC();
resCavvPreauthCC.setOrderId(order_id);
resCavvPreauthCC.setData(data_key);
resCavvPreauthCC.setCustId(cust_id);
resCavvPreauthCC.setAmount(amount);
resCavvPreauthCC.setCavv(cavv);
resCavvPreauthCC.setExpDate(expdate);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(resCavvPreauthCC);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("DataKey = " + receipt.getDataKey());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Message = " + receipt.getMessage());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("TimedOut = " + receipt.getTimedOut());
System.out.println("ResSuccess = " + receipt.getResSuccess());
System.out.println("PaymentType = " + receipt.getPaymentType());
System.out.println("CavvResultCode = " + receipt.getCavvResultCode());
//ResolveData
System.out.println("Cust ID = " + receipt.getResCustId());
System.out.println("Phone = " + receipt.getResPhone());
System.out.println("Email = " + receipt.getResEmail());
System.out.println("Note = " + receipt.getResNote());
System.out.println("Masked Pan = " + receipt.getResMaskedPan());
System.out.println("Exp Date = " + receipt.getResExpdate());
System.out.println("Crypt Type = " + receipt.getResCryptType());
System.out.println("Avs Street Number = " + receipt.getResAvsStreetNumber());
System.out.println("Avs Street Name = " + receipt.getResAvsStreetName());
System.out.println("Avs Zipcode = " + receipt.getResAvsZipcode());
}
catch (Exception e)
{
e.printStackTrace();
}
}
}
Page 283 of 477
July 2018
9 e-Fraud Tools
l
l
l
9.1 Address Verification Service
9.2 Card Validation Digits (CVD)
9.3 Transaction Risk Management Tool
July 2018
Page 284 of 477
9.1 Address Verification Service
l
l
l
l
9.1.1
9.1.2
9.1.3
9.1.4
About Address Verification Service (AVS)
AVS Info Object
AVS Response Codes
AVS Sample Code
9.1.1 About Address Verification Service (AVS)
Address Verification Service (AVS) is an optional fraud-prevention tool offered by issuing banks whereby a
cardholder's address is submitted as part of the transaction authorization. The AVS address is then compared to the address kept on file at the issuing bank. AVS checks whether the street number, street
name and zip/postal code match. The issuing bank returns an AVS result code indicating whether the
data was matched successfully. Regardless of the AVS result code returned, the credit card is authorized
by the issuing bank.
The response that is received from AVS verification is intended to provide added security and fraud prevention, but the response itself does not affect the completion of a transaction. Upon receiving a
response, the choice to proceed with a transaction is left entirely to the merchant. The responses is not a
strict guideline of whether a transaction will be approved or declined.
The following transactions support AVS:
l
l
l
l
l
Purchase (Basic and Mag Swipe)
Pre-Authorization (Basic)
Re-Authorization (Basic)
ResAddCC (Vault)
ResUpdateCC (Vault)
Things to Consider:
l
l
l
AVS is supported by Visa, MasterCard, American Express, Discover and JCB.
When testing AVS, you must only use the Visa test card numbers 4242424242424242 or
4005554444444403, and the amounts described in the Simulator eFraud Response
Codes document available at the Moneris developer portal (https://developer.moneris.com).
Store ID “store5” is set up to support AVS testing.
9.1.2 AVS Info Object
AVSInfo object definition
AvsInfo avsCheck = new AvsInfo();
July 2018
Page 286 of 477
Moneris Gateway API - Integration Guide
Transaction object set method
.setAvsInfo(avsCheck);
Table 1: AVS Info Object – Required Fields
Variable and Field
Name
AVS street number
Type and Limits
String
Set Method
Description
avsCheck.setAvsStreetNumber
("212");
Cardholder street
number
avsCheck.setAvsStreetName
("Payton Street");
Cardholder street
name
avsCheck.setAvsZipCode
("M1M1M1");
Cardholder zip/postal code
19-character alphanumeric
NOTE: this character limit is a
combined total
allowed for
AVS street number
and AVS street
name
AVS street name
String
19-character alphanumeric
NOTE: this character limit is the
combined total
allowed for
AVS street number
and AVS street
name
AVS zip/postal
code
String
9-character alphanumeric
9.1.3 AVS Response Codes
Below is a full list of possible AVS response codes. These can be returned when you call the receipt.getAvsResultCode() method .
Page 287 of 477
July 2018
Table 85: AVS result codes
Value
Visa
MasterCard/Discover
A
Street address matches, zip/postal code
does not. Acquirer rights not implied.
B
Street address matches. Zip/Postal code not N/A
verified due to incompatible formats.
(Acquirer sent both street address and zip/postal code.)
N/A
C
Street address not verified due to incompatible formats. (Acquirer sent both street
address and zip/postal code.)
N/A
N/A
D
Street address and zip/postal code match.
N/A
Customer name incorrect, zip/postal code
matches
E
N/A
N/A
Customer name incorrect, billing address and
zip/postal code match
F
(Applies to UK only) Street address and zip/- N/A
postal code match.
Customer name incorrect, billing address
matches.
G
Address information not verified for international transaction. Any of the following
may be true:
N/A
N/A
l
l
l
Address matches, zip/postal code does not.
Amex/JCB
Billing address
matches, zip/postal
code does not.
Issuer is not an AVS participant.
AVS data was present in the request,
but issuer did not return an AVS result.
Visa performs AVS on behalf of the
issuer and there was no address
record on file for this account.
I
Address information not verified.
N/A
N/A
K
N/A
N/A
Customer name
matches.
L
N/A
N/A
Customer name and
postal code match.
N/A
N/A
Customer name and
zip/postal code match.
July 2018
Page 288 of 477
Moneris Gateway API - Integration Guide
Table 85: AVS result codes (continued)
Value
Visa
MasterCard/Discover
Amex/JCB
M
Street address and zip/postal code match.
N/A
Customer name, billing
address, and zip/postal
code match.
N
No match.
Neither address nor
postal code matches.
Billing address and
postal code do not
match.
Also used when acquirer requests AVS but
sends no AVS data.
O
N/A
N/A
Customer name and
billing address match
P
Postal code matches. Acquirer sent both
postal code and street address, but street
address not verified due to incompatible
formats.
N/A
N/A
R
Retry: System unavailable or timed out.
Issuer ordinarily performs AVS, but was
unavailable.
Retry. System unable to Retry. System unavailprocess.
able.
The code R is used by Visa when issuers are
unavailable. Issuers should refrain from
using this code.
S
N/A
AVS currently not supported.
AVS currently not supported.
T
N/A
Nine-digit zip/postal
code matches, address
does not match.
N/A
U
Address not verified for domestic transaction. One of the following is true:
No data from
Issuer/Authorization
system.
Information is unavailable.
l
l
l
Issuer is not an AVS participant
AVS data was present in the request,
but issuer did not return an AVS result
Visa performs AVS on behalf of the
issuer and there was no address
record on file for this account.
Page 289 of 477
July 2018
Table 85: AVS result codes (continued)
Value
Visa
MasterCard/Discover
Amex/JCB
W
Not applicable. If present, replaced with ‘Z’
by Visa. Available for U.S. issuers only.
For US Addresses, nine- Customer name, billing
digit zip/postal code
address, and zip/postal
matches, address does code are all correct.
not. For addresses outside the US, zip/postal
code matches, address
does not.
X
N/A
For US addresses, nine- N/A
digit zip/postal code
and address match. For
addresses outside the
US,zip/postal code and
address match.
Y
Street address and zip/postal code match.
For US addresses, fivedigit zip/postal code
and address match.
Z
Zip/postal code matches, but street address For U.S. addresses, five- Postal code matches,
either does not match or street address was digit zip code matches, billing address does not
not included in request.
address does not
match.
match.
Billing address and zip/postal code match.
9.1.4 AVS Sample Code
This is a sample of Java code illustrating how AVS is implemented with a Purchase transaction. Purchase
object information that is not relevant to AVS has been removed.
For more about Purchase transactions, see 2.2 Purchase.
Sample Purchase with AVS information
AvsInfo avsCheck = new AvsInfo();
avsCheck.setAvsStreetNumber("212");
avsCheck.setAvsStreetName("Payton Street");
avsCheck.setAvsZipCode("M1M1M1");
avsCheck.setAvsEmail("test@host.com");
avsCheck.setAvsHostname("hostname");
avsCheck.setAvsBrowser("Mozilla");
avsCheck.setAvsShiptoCountry("CAN");
avsCheck.setAvsShipMethod("G");
avsCheck.setAvsMerchProdSku("123456");
avsCheck.setAvsCustIp("192.168.0.1");
avsCheck.setAvsCustPhone("5556667777");
Purchase purchase = new Purchase();
purchase.setAvsInfo(avsCheck);
July 2018
Page 290 of 477
9.2 Card Validation Digits (CVD)
l
l
l
l
9.2.1
9.2.3
9.2.4
9.2.5
About Card Validation Digits (CVD)
CVD Info Object
CVD Result Codes
Sample Purchase with CVD Info Object
9.2.1 About Card Validation Digits (CVD)
The Card Validation Digits (CVD) value is an additional number printed on credit cards that is used as an
additional check when verifying cardholder credentials during a transaction.
The response that is received from CVD verification is intended to provide added security and fraud prevention, but the response itself does not affect the completion of a transaction. Upon receiving a
response, the choice whether to proceed with a transaction is left entirely to the merchant. The
responses is not a strict guideline of which transaction will approve or decline.
The following transactions support CVD:
l
l
l
Purchase (Basic, Vault and Mag Swipe)
Pre-Authorization (Basic and Vault)
Re-Authorization
Things to Consider:
l
l
l
l
CVD is only supported by Visa, MasterCard, American Express, Discover, JCB and
UnionPay.
For UnionPay cards, the CVD response will not be returned; the issuer will approve or
decline based on the CVD result.
When testing CVD, you must only use the Visa test card numbers 4242424242424242 or
4005554444444403, and the amounts described in the Simulator eFraud Response
Codes document available at the Moneris developer portal (https://developer.moneris.com).
Test store_id “store5” is set up to support CVD testing.
9.2.2 Transactions Where CVD Is Required
The Card Validation Digits (CVD) object is required in transaction requests in the following scenarios:
l
l
Initial transactions when storing cardholder credentials in Credential on File scenarios; subsequent
follow-on transactions do not use CVD
Any Purchase, Pre-Authorization or Card Verification where you are not storing cardholder credentials
July 2018
Page 291 of 477
Moneris Gateway API - Integration Guide
9.2.3 CVD Info Object
NOTE: The CVD value must only be passed to the Moneris Gateway. Under no circumstances may it be stored for subsequent uses or displayed as part of the receipt information.
CvdInfo object definition
CvdInfo cvdCheck = new CvdInfo();
Transaction object set method
transaction.setCvdInfo(cvdCheck);
Table 1: CVD Info Object – Required Fields
Variable and Field
Name
CVD indicator
Type and Limits
String
Set Method
cvdCheck.setCvdIndicator
("1");
1-character
numeric
Description
Indicates presence
of CVD
Possible values:
0: CVD value is deliberately bypassed or is
not provided by the merchant.
1: CVD value is present.
2: CVD value is on the
card, but is illegible.
9: Cardholder states that
the card has no CVD
imprint.
CVD value
String
4-character
numeric
Page 292 of 477
cvdCheck.setCvdValue
("099");
CVD value located
on credit card
NOTE: The CVD
value must only be
passed to the Moneris Gateway.
Under no circumstances may it
be stored for subsequent uses or displayed as part of
July 2018
Variable and Field
Name
Type and Limits
Set Method
Description
the receipt information.
9.2.4 CVD Result Codes
Value
Definition
M
Match
N
No match
P
Not processed
S
CVD should be on the card, but Merchant has
indicated that CVD is not present
U
Issuer is not a CVD participant
Y
Match for Amex/JCB only
D
Invalid security code for Amex or JCB only
Other
Invalid response code
9.2.5 Sample Purchase with CVD Info Object
This is a sample of Java code illustrating how CVD is implemented with a Purchase transaction. Purchase
object information that is not relevant to CVD has been removed.
Sample Purchase with CVD Information
CvdInfo cvdCheck = new CvdInfo();
cvdCheck.setCvdIndicator("1");
cvdCheck.setCvdValue("099");
Purchase purchase = new Purchase();
purchase.setCvdInfo(cvdCheck);
July 2018
Page 293 of 477
9.3 Transaction Risk Management Tool
l
l
l
l
l
l
9.3.1
9.3.2
9.3.3
9.3.4
9.3.6
9.3.6
About the Transaction Risk Management Tool
Introduction to Queries
Session Query
Attribute Query
Inserting the Profiling Tags Into Your Website
Inserting the Profiling Tags Into Your Website
The Transaction Risk Management Tool (TRMT) is available to Canadian integrations only.
9.3.1 About the Transaction Risk Management Tool
The Transaction Risk Management Tool provides additional information to assist in identifying fraudulent transactions. To maximize the benefits from the Transaction Risk Management Tool, it is highly
recommended that you:
l
l
Carefully consider the business logic and processes that you need to implement surrounding the
handling of response information the Transaction Risk Management Tool provides.
Implement the other fraud tools available through Moneris Gateway (such as AVS, CVD, Verified
by Visa, MasterCard SecureCode and American Express SafeKey).
9.3.2 Introduction to Queries
There are two types of transactions associated with the Transaction Risk Management Tool (TRMT):
l
l
Session Query (page 295)
Attribute Query (page 302)
The Session Query and Attribute Query are used at the time of the transaction to obtain the risk assessment.
Moneris recommends that you use the Session Query as much as possible for obtaining your risk assessment because it uses the device fingerprint as well as other transaction information when providing the
risk scores.
To use the Session Query, you must implement two components:
l
l
Tags on your website to collect the device fingerprinting information
Session Query transaction.
If you are not able to collect the necessary information for the Session Query (such as the device fingerprint), then use the Attribute Query.
July 2018
Canada Only
Page 294 of 477
Moneris Gateway API - Integration Guide
9.3.3 Session Query
Once a device profiling session has been initiated upon a client device, the Session Query API is used at
the time of the transaction or even to obtain a device identifier or ‘fingerprint’, attribute list and risk
assessment for the client device.
Session Query transaction object definition
SessionQuery sq = new SessionQuery();
HttpsPostRequest object for Session Query transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(sq);
Session Query transaction values
Table 86: Session Query transaction object mandatory values
Type
Limits
Set method
Value
Description
Session ID
sq.setSessionId(session_id);
String 9-character decimal
Permitted characters: [a-z], [A-Z],
0-9, _, -
Web server session identifier generated when device profiling was initiated.
Service type
sq.setServiceType(service_type);
String 9-character decimal
Which output fields are returned.
session -- returns IP and device related attributes.
Event type
sq.setEventType(service_type);
String payment
Defines the type of transaction or event for reporting purposes.
payment - Purchasing of goods/services.
Credit card
String 20-character numeric
number (PAN)
No spaces or dashes
sq.setPan(pan);
Most credit card numbers today are 16 digits, but some 13-digit numbers are still
accepted by some issuers. This field has been intentionally expanded to 20 digits in
consideration for future expansion and potential support of private label card ranges.
Page 295 of 477
Canada Only
July 2018
Table 86: Session Query transaction object mandatory values (continued)
Type
Limits
Set method
Value
Description
sq.setAccountAddressStreet1
Account
String 32-character alphanumeric
("3300 Bloor St W");
address street
1
First portion of the street address component of the billing address.
sq.setAccountAddressStreet2("4th
Account
String 32-character alphanumeric
Flr West Tower");
Address street
2
Second portion of the street address component of the billing address.
Account
address city
String 50-character alphanumeric
sq.setAccountAddressCity
("Toronto");
The city component of the billing address.
sq.setAccountAddressState
Account
String 64-character alphanumeric
("Ontario");
address state/province
The state/province component of the billing address.
sq.setAccountAddressCountry
Account
String 2-character alphanumeric
("CA");
address country
ISO2 country code of the billing addresses.
Account
address ZIP/postal code
String 8-character alphanumeric
sq.setAccountAddressZip
("M8X2X2");
ZIP/postal code of the billing address.
sq.setShippingAddressStreet1
Shipping
String 32-character alphanumeric
("3300 Bloor St W");
address street
1
First portion of the street address component of the shipping address.
sq.setShippingAddressStreet2
Shipping
String 32-character alphanumeric
("4th Flr West Tower");
address street
2
Second portion of the street address component of the shipping address.
Shipping
address city
String 50-character alphanumeric
sq.setShippingAddressCity
("Toronto");
City component of the shipping address.
sq.setShippingAddressState
Shipping
String 64-character alphanumeric
("Ontario");
address state/province
The state/province component of the shipping address.
July 2018
Canada Only
Page 296 of 477
Moneris Gateway API - Integration Guide
Table 86: Session Query transaction object mandatory values (continued)
Type
Limits
Set method
Value
Description
sq.setShippingAddressCountry
Shipping
String 2-character alphanumeric
("CA");
address country
ISO2 country code of the account address country.
Shipping
address ZIP
sq.setAccountAddressZip
("M8X2X2");
String 8-character alphanumeric
The ZIP/postal code component of the shipping address.
sq.setLocalAttrib1("a");
Local attribute String 255-character alphanumeric
1-5
These five attributes can be used to pass custom attribute data. These are used if you
wish to correlate some data with the returned device information.
Transaction
amount
sq.setTransactionAmount("1.00");
String 255-character alphanumeric
Must contain 2 decimal places
The numeric currency amount.
Transaction
currency
sq.setTransactionCurrency
("CAN");
String 10-character numeric
The currency type that the transaction was denominated in. If TransactionAmount is
passed, the TransactionCurrency is required.
Values to be used are:
l
l
CAD – 124
USD – 840
Table 87: Session Query transaction object optional values
Type
Limits
Set method
Value
Description
Account login
String 255-character
alphanumeric
sq.setAccountLogin("13195417-8CA0-46cd-960D14C158E4DBB2");
The Account Login name.
Password
hash
String 40-character
alphanumeric
sq.setPasswordHash
("489c830f10f7c601d30599a0deaf66e64d2aa50a");
The input must be a SHA-2 hash of the password in hexadecimal format. Used to check
if it is on a watch list.
Page 297 of 477
Canada Only
July 2018
Table 87: Session Query transaction object optional values (continued)
Type
Limits
Set method
Value
Description
Account num- String 255-character
alphanumeric
ber
sq.setAccountNumber("3E17A905-AC8A-4c8d-A4173DADA2A55220");
The account number for the account.
Account name String 255-character
alphanumeric
sq.setAccountName("4590FCC0-DF4A-44d9-A57BAF9DE98B84DD");
Account name (or concatenation of first and last name of account holder).
Account email String 100-character
alphanumeric
sq.setAccountEmail("3CAE72EF-6B69-4a25-93FE2674735E78E8@test.threatmetrix.com");
The email address entered into the form for this contact. Used to check if this is a high
risk account email id.
Account telephone
String 32-character
alphanumeric
Contact telephone number including country and city codes. All whitespace is
removed.
Must be in format: 0..9,,(,),[,] braces must be matched.
Address street String 32-character
1
alphanumeric
The first portion of the street address component of the account address.
Address street String 32-character
2
alphanumeric
The second portion of the street address component of the account address.
Address city
String 50-character
alphanumeric
The city component of the account address.
Address state/- String 64-character
province
alphanumeric
The state/province component of the account address
Address coun- String 2-character
try
alphanumeric
The 2 character ISO2 country code of the account address country
July 2018
Canada Only
Page 298 of 477
Moneris Gateway API - Integration Guide
Table 87: Session Query transaction object optional values (continued)
Type
Limits
Set method
Value
Description
Address ZIP
String 8-character
alphanumeric
The ZIP/postal code of the account address.
Ship Address
Street 1
String 32-character
alphanumeric
The first portion of the street address component of the shipping address
Ship Address
Street 2
String 32-character
alphanumeric
The second portion of the street address component of the shipping address
Ship Address
City
String 50-character
alphanumeric
The city component of the shipping address
Ship Address String 64-character
State/Province
alphanumeric
The state/province component of the shipping address
Ship Address
Country
String 2-character
alphanumeric
The 2 character ISO2 country code of the shipping address country
Ship Address
ZIP
String 8-character
alphanumeric
The ZIP/postal code of the shipping address
CC Number
Hash
String 255-character
alphanumeric
This is a SHA-2 hash (in hexadecimal format) of the credit card number.
Custom Attrib- String 255-character
ute 1-8
alphanumeric
These 8 attributes can be used to pass custom attribute data which can be used within
the rules.
Page 299 of 477
Canada Only
July 2018
Sample Session Query - CA
package Canada;
import java.util.Hashtable;
import java.util.Iterator;
import java.util.Map;
import JavaAPI.*;
public class TestCanadaRiskCheckSession
{
public static void main(String[] args)
{
String store_id = "moneris";
String api_token = "hurgle";
java.util.Date createDate = new java.util.Date();
String order_id = "Test"+createDate.getTime();
String session_id = "abc123";
String service_type = "session";
//String event_type = "LOGIN";
String processing_country_code = "CA";
boolean status_check = false;
SessionQuery sq = new SessionQuery();
sq.setOrderId(order_id);
sq.setSessionId(session_id);
sq.setServiceType(service_type);
sq.setEventType(service_type);
//sq.setPolicy("");
//sq.setDeviceId("4EC40DE5-0770-4fa0-BE53-981C067C598D");
sq.setAccountLogin("13195417-8CA0-46cd-960D-14C158E4DBB2");
sq.setPasswordHash("489c830f10f7c601d30599a0deaf66e64d2aa50a");
sq.setAccountNumber("3E17A905-AC8A-4c8d-A417-3DADA2A55220");
sq.setAccountName("4590FCC0-DF4A-44d9-A57B-AF9DE98B84DD");
sq.setAccountEmail("3CAE72EF-6B69-4a25-93FE-2674735E78E8@test.threatmetrix.com");
//sq.setAccountTelephone("5556667777");
sq.setPan("4242424242424242");
//sq.setAccountAddressStreet1("3300 Bloor St W");
//sq.setAccountAddressStreet2("4th Flr West Tower");
//sq.setAccountAddressCity("Toronto");
//sq.setAccountAddressState("Ontario");
//sq.setAccountAddressCountry("CA");
//sq.setAccountAddressZip("M8X2X2");
//sq.setShippingAddressStreet1("3300 Bloor St W");
//sq.setShippingAddressStreet2("4th Flr West Tower");
//sq.setShippingAddressCity("Toronto");
//sq.setShippingAddressState("Ontario");
//sq.setShippingAddressCountry("CA");
//sq.setShippingAddressZip("M8X2X2");
//sq.setLocalAttrib1("a");
//sq.setLocalAttrib2("b");
//sq.setLocalAttrib3("c");
//sq.setLocalAttrib4("d");
//sq.setLocalAttrib5("e");
//sq.setTransactionAmount("1.00");
//sq.setTransactionCurrency("840");
//set SessionAccountInfo
sq.setTransactionCurrency("CAN");
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
July 2018
Canada Only
Page 300 of 477
Moneris Gateway API - Integration Guide
Sample Session Query - CA
mpgReq.setTransaction(sq);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
String[] rules;
Hashtable results = new Hashtable();
Receipt receipt = mpgReq.getReceipt();
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("Message = " + receipt.getMessage());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
results = receipt.getRiskResult();
Iterator> response = results.entrySet().iterator();
while (response.hasNext())
{
Map.Entry entry = response.next();
System.out.println(entry.getKey().toString() + " = " + entry.getValue().toString());
}
rules = receipt.getRiskRules();
for (int i = 0; i < rules.length; i++)
{
System.out.println("RuleName = " + rules[i]);
System.out.println("RuleCode = " + receipt.getRuleCode(rules[i]));
System.out.println("RuleMessageEn = " + receipt.getRuleMessageEn(rules[i]));
System.out.println("RuleMessageFr = " + receipt.getRuleMessageFr(rules[i]));
}
}
catch (Exception e)
{
e.printStackTrace();
}
}
}
9.3.3.1 Session Query Transaction Flow
Figure 4: Session Query transaction flow
1. Cardholder logs onto the merchant website.
2. When the page has loaded in the cardholder's browser, special tags within the site allow information from the device to be gathered and sent to ThreatMetrix as the device fingerprint.
The HTML tags should be placed where the cardholder is resident on the page for a couple of
seconds to get the broadest data possible.
Page 301 of 477
Canada Only
July 2018
3. Customer submits a transaction.
4. Merchant’s web application makes a Session Query transaction to the Moneris Gateway using
the same session id that was included in the device fingerprint. This call must be made within 30
minutes of profiling (2).
5. Moneris Gateway submits the Session Query data to ThreatMetrix.
6. ThreatMetrix uses the Session Query data and the device fingerprint information to assess the
transaction against the rules. A score is generated based on the rules.
7. The merchant uses the returned device information in its risk analysis to make a business
decision. The merchant may wish to continue or cancel with the cardholder’s payment transaction.
9.3.4 Attribute Query
The Attribute Query is used to obtain a risk assessment of transaction-related identifiers such as the
email address and the card number. Unlike the Session Query, the Attribute Query does not require the
device fingerprinting information to be provided.
AttributeQuery transaction object definition
AttributeQuery aq = new AttributeQuery();
HttpsPostRequest object for AttributeQuery transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(aq);
Attribute Query transaction values
Table 88: Attribute Query transaction object mandatory values
Type
Limits
Set method
Value
Description
Service type
aq.setServiceType(service_type);
String N/A
Which output fields are returned.
session -- returns IP and device related attributes.
Device ID
String 36-character alphanumeric
aq.setDeviceId("");
Unique device identifier generated by a previous call to the ThreatMetrix sessionquery API.
Credit card
number
String 20-character numeric
aq.setPan(pan);
No spaces or dashes
Most credit card numbers today are 16 digits, but some 13-digit numbers are still
accepted by some issuers. This field has been intentionally expanded to 20 digits in
consideration for future expansion and potential support of private label card ranges.
July 2018
Canada Only
Page 302 of 477
Moneris Gateway API - Integration Guide
Table 88: Attribute Query transaction object mandatory values (continued)
Type
Limits
Set method
Value
Description
IP address
String 64-character alphanumeric
aq.setIPAddress("192.168.0.1");
True IP address. Results will be returned as true_ip_geo, true_ip_score and so on.
IP forwarded
String 64-character alphanumeric
aq.setIPForwarded
("192.168.1.0");
The IP address of the proxy. If the IPAddress is supplied, results will be returned as
proxy_ip_geo and proxy_ip_score.
If the IP Address is not supplied, this IP address will be treated as the true IP address
and results will be returned as true_ip_geo, true_ip_score and so on
aq.setAccountAddressStreet1
Account
String 32-character alphanumeric
("3300 Bloor St W");
address street
1
First portion of the street address component of the billing address.
aq.setAccountAddressStreet2("4th
Account
String 32-character alphanumeric
Flr West Tower");
Address Street
2
Second portion of the street address component of the billing address.
Account
address city
String 50-character alphanumeric
aq.setAccountAddressCity
("Toronto");
The city component of the billing address.
aq.setAccountAddressState
Account
String 64-character alphanumeric
("Ontario");
address state/province
The state component of the billing address.
aq.setAccountAddressCountry
Account
String 2-character alphanumeric
("CA");
address country
ISO2 country code of the billing addresses.
Account
address zip/postal code
String 8-character alphanumeric
aq.setAccountAddressZip
("M8X2X2");
Zip/postal code of the billing address.
Shipping
String 32-character alphanumeric
address street
1
Account address country
aq.setShippingAddressStreet1
("3300 Bloor St W");
aq.setShippingAddressStreet2
Shipping
String 32-character alphanumeric
("4th Flr West Tower");
Address Street
2
Second portion of the street address component of the shipping address.
Page 303 of 477
Canada Only
July 2018
Table 88: Attribute Query transaction object mandatory values (continued)
Type
Limits
Set method
Value
Description
Shipping
Address City
String 50-character alphanumeric
aq.setShippingAddressCity
("Toronto");
City component of the shipping address.
aq.setShippingAddressState
Shipping
String 64-character alphanumeric
("Ontario");
Address
State/Province State/Province component of the shipping address.
aq.setShippingAddressCountry
Shipping
String 2-character alphanumeric
("CA");
Address Country
ISO2 country code of the account address country.
Shipping
Address zip/postal code
String 8-character alphanumeric
aq.setAccountAddressZip
("M8X2X2");
The zip/postal code component of the shipping address.
Sample Attribute Query
String store_id = "moneris";
String api_token = "hurgle";
java.util.Date createDate = new java.util.Date();
String order_id = "Test"+createDate.getTime();
String service_type = "session";
String processing_country_code = "CA";
boolean status_check = false;
AttributeQuery aq = new AttributeQuery();
aq.setOrderId(order_id);
aq.setServiceType(service_type);
aq.setDeviceId("");
aq.setAccountLogin("13195417-8CA0-46cd-960D-14C158E4DBB2");
aq.setPasswordHash("489c830f10f7c601d30599a0deaf66e64d2aa50a");
aq.setAccountNumber("3E17A905-AC8A-4c8d-A417-3DADA2A55220");
aq.setAccountName("4590FCC0-DF4A-44d9-A57B-AF9DE98B84DD");
aq.setAccountEmail("3CAE72EF-6B69-4a25-93FE-2674735E78E8@test.threatmetrix.com");
//aq.setCCNumberHash("4242424242424242");
//aq.setIPAddress("192.168.0.1");
//aq.setIPForwarded("192.168.1.0");
aq.setAccountAddressStreet1("3300 Bloor St W");
aq.setAccountAddressStreet2("4th Flr West Tower");
aq.setAccountAddressCity("Toronto");
aq.setAccountAddressState("Ontario");
aq.setAccountAddressCountry("CA");
aq.setAccountAddressZip("M8X2X2");
aq.setShippingAddressStreet1("3300 Bloor St W");
aq.setShippingAddressStreet2("4th Flr West Tower");
aq.setShippingAddressCity("Toronto");
aq.setShippingAddressState("Ontario");
aq.setShippingAddressCountry("CA");
July 2018
Canada Only
Page 304 of 477
Moneris Gateway API - Integration Guide
Sample Attribute Query
aq.setShippingAddressZip("M8X2X2");
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(aq);
mpgReq.send();
try
{
String[] rules;
Hashtable results = new Hashtable();
Receipt receipt = mpgReq.getReceipt();
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("Message = " + receipt.getMessage());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
results = receipt.getRiskResult();
Iterator> response = results.entrySet().iterator();
while (response.hasNext())
{
Map.Entry entry = response.next();
System.out.println(entry.getKey().toString() + " = " + entry.getValue().toString());
}
rules = receipt.getRiskRules();
for (int i = 0; i < rules.length; i++)
{
System.out.println("RuleName = " + rules[i]);
System.out.println("RuleCode = " + receipt.getRuleCode(rules[i]));
System.out.println("RuleMessageEn = " + receipt.getRuleMessageEn(rules[i]));
System.out.println("RuleMessageFr = " + receipt.getRuleMessageFr(rules[i]));
}
}
9.3.4.1 Attribute Query Transaction Flow
Figure 5: Attribute query transaction flow
1. Cardholder logs onto merchant website and submits a transaction.
2. The merchant’s web application makes an Attribute Query transaction that includes the session
ID to the Moneris Gateway.
3. Moneris Gateway submits Attribute Query data to ThreatMetrix.
4. ThreatMetrix uses the Attribute Query data to assess the transaction against the rules. A score is
generated based on the rules.
5. The merchant uses the returned device information in its risk analysis to make a business
decision. The merchant may wish to continue or cancel with the cardholder's payment transaction.
Page 305 of 477
Canada Only
July 2018
9.3.5 Handling Response Information
When reviewing the response information and determining how to handle the transaction, it is recommended that you (either manually or through automated logic on your site) use the following pieces of
information:
l
l
l
l
Risk score
Rules triggered (such as Rule Codes, Rule Names, Rule Messages)
Results obtained from Verified by Visa, MasterCard Secure Code, AVS, CVD and the financial transaction authorization
Response codes for the Transaction Risk Management Transaction that are included by automated processes.
9.3.5.1 TRMT Response Fields
Table 89: Receipt object response values for TRMT
Type
Limits
Get method
Value
Definition
Response
Code
String
receipt.getResponseCode();
3-character alphanumeric
001 – Success
981 – Data error
982 – Duplicate Order ID
983 – Invalid Transaction
984 – Previously asserted
985 – Invalid activity description
986- Invalid impact description
987 – Invalid Confidence description
988 - Cannot find Previous
Message
String
N/A
receipt.getMessage();
Response message
Event type
String
N/A
Type of transaction or event returned in the response.
July 2018
Canada Only
Page 306 of 477
Moneris Gateway API - Integration Guide
Table 89: Receipt object response values for TRMT (continued)
Type
Limits
Get method
Value
Definition
Org ID
String
N/A
ThreatMetrix-defined unique transaction identifier
Policy
String
N/A
Policy used for the Session Query will be returned with the return request. If the Policy
was not included, then the Policy name default is returned.
Policy score
String
N/A
The sum of all the risks weights from triggered rules within the selected policy in the
range [-100…100]
Request dur- String
N/A
ation
Length of time it takes for the transaction to be processed.
Request ID
String
N/A
Unique number and will always be returned with the return request.
Request res- String
N/A
ult
See 9.3.5.1 (page 306).
Review
status
String
Risk rating
String
receipt.getRiskResult();
N/A
The transaction status based on the assessments and risk scores.
N/A
The rating based on the assessments and risk scores.
Service type String
N/A
The service type will be returned in the attribute query response.
Session ID
String
N/A
Temporary identifier unique to the visitor will be returned in the return request.
Summary
risk score
String
Transaction
ID
String
Unknown
session
String
N/A
Based on all of the returned values in the range [-100 … 100]
N/A
This is the transaction identifier and will always be returned in the response when supplied as input.
N/A
If present, the value is "yes". It indicates the session ID that was passed was not found.
Page 307 of 477
Canada Only
July 2018
Table 90: Response code descriptions
Value
Definition
001
Success
981
Data error
982
Duplicate order ID
983
Invalid transaction
984
Previously asserted
985
Invalid activity description
986
Invalid impact description
987
Invalid confidence description
988
Cannot find previous
Table 91: Request result values and descriptions
Value
Definition
fail_duplicate_entities_of_same_type
More than one entity of the same was specified,
e.g. password_hash was specified twice.
fail_incomplete
ThreatMetrix was unable to process the request
due to incomplete or incorrect input data
fail_invalid_account_number
The format of the supplied account number was
invalid
fail_invalid_characters
Invalid characters submitted
fail_invalid_charset
The value of character set was invalid
fail_invalid_currency_code
The format of the currency_code was invalid
fail_invalid_currency_format
The format of the currency_format was invalid
fail_invalid_telephone_number
Format of the supplied telephone number was
invalid
fail_access
ThreatMetrix was unable to process the request
because of API verification failing
fail_internal_error
ThreatMetrix encountered an error while processing the request
July 2018
Canada Only
Page 308 of 477
Moneris Gateway API - Integration Guide
Value
Definition
fail_invalid_device_id
Format of the supplied device_id was invalid
fail_invalid_email_address
Format of the supplied email address was invalid
fail_invalid_fuzzy_device_id
The format of fuzzy_device_id was invalid
fail_invalid_ip_address_parameter
Format of a supplied ip_address parameter was
invalid
fail_invalid_parameter
The format of the parameter was invalid, or the
value is out of boundary
fail_invalid_sha_hash
The format of a parameter specified as a sha hash
was invalid, sha hash included sha1/2/3 hash
fail_invalid_submitter_id
The format of the submitter id was invalid or the
value is out of boundary
fail_no_policy_configured
No policy was configured against the org_id
fail_not_enough_params
Not enough device attributes were collected during profiling to perform a fingerprint match
fail_parameter_overlength
The value of the parameter was overlength
fail_temporarily_unavailable
Request failed because the service is temporarily
unavailable
fail_too_many_instances_of_same_parameter
Multiple values for some parameters which only
allow one instance
fail_verification
API query limit reached
success
ThreatMetrix was able to process the request successfully
9.3.5.2 Understanding the Risk Score
For each Session Query or Attribute Query, a score with a value between -100 and +100 is returned based
on the rules that were triggered for the transaction.
Table 92 defines the risk scores ranges.
Page 309 of 477
Canada Only
July 2018
Table 92: Session Query and Attribute Query risk score definitions
Risk score
Visa definition
-100 to -1
A lower score indicates a higher probability that the transaction is fraudulent.
0
Neutral transaction
1 to 100
A higher score indicates a lower probability that the transaction is fraudulent.
Note: All e-commerce transactions have some level of risk associated with them.
Therefore, it is rare to see risk score in the high positive values.
When evaluating the risk of a transaction, the risk score gives an initial indicator of the potential risk that
the transaction is fraudulent. Because some of the rules that are evaluated on each transaction may not
be relevant to your business scenario, review the rules that were triggered for the transaction before
determining how to handle the transaction.
9.3.5.3 Understanding the Rule Codes, Rule Names and Rule Messages
The rule codes, rule names and rule messages provide details about what rules were triggered during the
assessment of the information provided in the Session or Attribute Query. Each rule code has a rule
name and rule message. The rule name and rule message are typically similar. Table 93 provides additional information on each rule.
When evaluating the risk of a transaction, it is recommended that you review the rules that were
triggered for the transaction and assess the relevance to your business. (That is, how does it relate to the
typical buying habits of your customer base?)
If you are automating some or all of the decision-making processes related to handling the responses,
you may want to use the rule codes. If you are documenting manual processes, you may want to refer to
the more user-friendly rule name or rule message.
Table 93: Rule names, numbers and messages
Rule name
Rule number
Rule message
Rule explanation
White lists
DeviceWhitelisted
WL001
Device White Listed
Device is on the white list. This indicates that the device has
been flagged as always "ok".
Note: This rule is currently not in use.
July 2018
Canada Only
Page 310 of 477
Moneris Gateway API - Integration Guide
Table 93: Rule names, numbers and messages (continued)
Rule name
IPWhitelisted
Rule number
Rule message
Rule explanation
WL002
IP White Listed
IP address is on the white list. This indicates the device has
been flagged as always "ok".
Note: This rule is currently not in use.
EmailWhitelisted
WL003
Email White Listed
Email address is on the white list. This indicates that the
device has been flagged as always "ok".
Note: This rule is currently not in use.
Event velocity
2DevicePayment
EV003
2 Device Payment Velocity
Multiple payments were detected from this device in the
past 24 hours.
2IPPaymentVelocity
EV006
2 IP Payment Velocity
Multiple payments were detected from this IP within the
past 24 hours.
2ProxyPaymentVelocity
EV008
2 Proxy Payment Velocity
The device has used 3 or more different proxies during a 24
hour period. This could be a risk or it could be someone
using a legitimate corporate proxy.
Email
3EmailPerDeviceDay
EM001
3 Emails for the Device ID in 1 Day
This device has presented 3 different email IDs within the
past 24 hours.
3EmailPerDeviceWeek
EM002
3 emails for the Device ID in 1 week
This device has presented 3 different email IDs within the
past week.
3DevciePerEmailDay
EM003
3 Device Ids for email address in 1 day
This email has been presented from three different devices
in the past 24 hours.
3DevciePerEmailWeek
EM004
3 Device Ids for email address in 1 week
This email has been presented from three different devices
in the past week.
Page 311 of 477
Canada Only
July 2018
Table 93: Rule names, numbers and messages (continued)
Rule name
EmailDistanceTravelled
Rule number
Rule message
Rule explanation
EM005
Email Distance Travelled
This email address has been associated with different physical locations in a short period of time.
3EmailPerSmartIDHour
EM006
3 Emails for SmartID in 1 Hour
The SmartID for this device has been associated with 3 different email addresses in 1 hour.
GlobalEMailOverOneMonth
EM007
Global Email over 1 month
The e-mail address involved in the transaction over 30 days
ago. This generally indicates that the transaction is less
risky.
Note: This rule is set so that it does not impact the policy
score or risk rating.
ComputerGeneratedEmailAddress
EM008
Computer Generated Email Address
This transaction used a computer-generated email address.
Account Number
3AccountNumberPerDeviceDay
AN001
3 Account Numbers for device in 1 day
This device has presented 3 different user accounts within
the past 24 hours.
3AccountNumberPerDeviceWeek
AN002
3 Account Numbers for device in 1
week
This device has presented 3 different user accounts within
the past week.
3DevciePerAccountNumberDay
AN003
3 Device IDs for account number in 1
day
This user account been used from three different devices in
the past 24 hours.
3DevciePerAccountNumberWeek
AN004
3 Device IDs for account number in 1
week
This card number has been used from three different
devices in the past week.
AccountNumberDistanceTravelled
AN005
Account Number distance travelled
This card number has been used from a number of physically different locations in a short period of time.
July 2018
Canada Only
Page 312 of 477
Moneris Gateway API - Integration Guide
Table 93: Rule names, numbers and messages (continued)
Rule name
Rule number
Rule message
Rule explanation
Credit card/payments
3CreditCardPerDeviceDay
CP001
3 credit cards for device in 1 day
This device has used three credit cards within 24 hours.
3CreditCardPerDeviceWeek
CP002
3 credit cards for device in 1 week
This device has used three credit cards within 1 week.
3DevicePerCreditCardDay
CP003
3 device ids for credit card in 1 day
This credit card has been used on three different devices in
24 hours.
3DevciePerCreditCardWeek
CP004
3 device ids for credit card in 1 week
This credit card has been used on three different devices in 1
week.
CredtCardDistanceTravelled
CP005
Credit Card has travelled
The credit card has been used at a number of physically different locations in a short period of time.
CreditCardShipAddressGeoMismatch
CP006
Credit Card and Ship Address do not
match
The credit card was issued in a region different from the Ship
To Address information provided.
CreditCardBillAddressGeoMismatch
CP007
Credit Card and Billing Address do not
match
The credit card was issued in a region different from the
Billing Address information provided.
CreditCardDeviceGeoMismatch
CP008
Credit Card and device location do not
match
The device is located in a region different from where the
card was issued.
CreditCardBINShipAddressGeoMismatch CP009
Credit Card issuing location and Shipping address do not match
The credit card was issued in a region different from the Ship
To Address information provided.
CreditCardBINBillAddressGeoMismatch
CP010
Credit Card issuing location and Billing
address do not match
The credit card was issued in a region different from the
Billing Address information provided.
Page 313 of 477
Canada Only
July 2018
Table 93: Rule names, numbers and messages (continued)
Rule name
CreditCardBINDeviceGeoMismatch
Rule number
Rule message
Rule explanation
CP011
Credit Card issuing location and location of the device do not match
The device is located in a region different from where the
card was issued.
TransactionValueDay
CP012
Daily Transaction Value Threshold
The transaction value exceeds the daily threshold.
TransactionValueWeek
CP013
Weekly Transaction Value Threshold
The transaction value exceeds the weekly threshold.
Proxy rules
3ProxyPerDeviceDay
PX001
3 Proxy Ips in 1 day
This device has used three different proxy servers in the past
24 hours.
AnonymousProxy
PX002
Anonymous Proxy IP
This device is using an anonymous proxy
UnusualProxyAttributes
PX003
Unusual Proxy Attributes
This transaction is coming from a source with unusual proxy
attributes.
AnonymousProxy
PX004
Anonymous Proxy
This device is connecting through an anonymous proxy connection.
HiddenProxy
PX005
Hidden Proxy
This device is connecting via a hidden proxy server.
OpenProxy
PX006
Open Proxy
This transaction is coming from a source that is using an
open proxy.
TransparentProxy
PX007
Transparent Proxy
This transaction is coming from a source that is using a transparent proxy.
DeviceProxyGeoMismatch
PX008
Proxy and True GEO Match
This device is connecting through a proxy server that didn’t
match the devices geo-location.
July 2018
Canada Only
Page 314 of 477
Moneris Gateway API - Integration Guide
Table 93: Rule names, numbers and messages (continued)
Rule name
ProxyTrueISPMismatch
Rule number
Rule message
Rule explanation
PX009
Proxy and True ISP Match
This device is connecting through a proxy server that
doesn’t match the true IP address of the device.
ProxyTrueOrganizationMismatch
PX010
Proxy and True Org Match
The Proxy information and True ISP information for this
source do not match.
DeviceProxyRegionMismatch
PX011
Proxy and True Region Match
The proxy and device region location information do not
match.
ProxyNegativeReputation
PX012
Proxy IP Flagged Risky in Reputation
Network
This device is connecting from a proxy server with a known
negative reputation.
SatelliteProxyISP
PX013
Satellite Proxy
This transaction is coming from a source that is using a satellite proxy.
GEO
DeviceCountriesNotAllowed
GE001
True GEO in Countries Not Allowed
blacklist
This device is connecting from a high-risk geographic location.
DeviceCountriesNotAllowed
GE002
True GEO in Countries Not Allowed
(negative whitelist)
The device is from a region that is not on the whitelist of
regions that are accepted.
DeviceProxyGeoMismatch
GE003
True GEO different from Proxy GEO
The true geographical location of this device is different from
the proxy geographical location.
DeviceAccountGeoMismatch
GE004
Account Address different from True
GEO
This device has presented an account billing address that
doesn't match the devices geolocation.
DeviceShipGeoMismatch
GE005
Device and Ship Geo mismatch
The location of the device and the shipping address do not
match.
Page 315 of 477
Canada Only
July 2018
Table 93: Rule names, numbers and messages (continued)
Rule name
DeviceShipGeoMismatch
Rule number
Rule message
Rule explanation
GE006
Device and Ship Geo mismatch
The location of the device and the shipping address do not
match.
Device
SatelliteISP
DV001
Satellite ISP
This transaction is from a source that is using a satellite ISP.
MidsessionChange
DV002
Session Changed Mid-session
This device changed session details and identifiers in the
middle of a session.
LanguageMismatch
DV003
Language Mismatch
The language of the user does not match the primary language spoken in the location where the True IP is registered.
NoDeviceID
DV004
No Device ID
No device ID was available for this transaction.
Dial-upConnection
DV005
Dial-up connection
This device uses a less identifiable dial-up connection.
DeviceNegativeReputation
DV006
Device Blacklisted in Reputational Network
This device has a known negative reputation as reported to
the fraud network.
DeviceGlobalBlacklist
DV007
Device on the Global Black List
This device has been flagged on the global blacklist of known
problem devices.
DeviceCompromisedDay
DV008
Device compromised in last day
This device has been reported as compromised in the last 24
hours.
DeviceCompromisedHour
DV009
Device compromised in last hour
This device has been reported as compromised in the last
hour.
FlashImagesCookiesDisabled
DV010
Flash Images Cookies Disabled
Key browser functions/identifiers have been disabled on
this device.
July 2018
Canada Only
Page 316 of 477
Moneris Gateway API - Integration Guide
Table 93: Rule names, numbers and messages (continued)
Rule number
Rule name
Rule message
Rule explanation
FlashCookiesDisabled
DV011
Flash Cookies Disabled
Key browser functions/identifiers have been disabled on
this device.
FlashDisabled
DV012
Flash Disabled
Key browser functions/identifiers have been disabled on
this device.
ImagesDisabled
DV013
Images Disabled
Key browser functions/identifiers have been disabled on
this device.
CookiesDisabled
DV014
Cookies Disabled
Key browser functions/identifiers have been disabled on
this device.
DeviceDistanceTravelled
DV015
Device Distance Travelled
The device has been used from multiple physical locations in
a short period of time.
PossibleCookieWiping
DV016
Cookie Wiping
This device appears to be deleting cookies after each session.
PossibleCookieCopying
DV017
Possible Cookie Copying
This device appears to be copying cookies.
PossibleVPNConnection
DV018
Possibly using a VPN Connection
This device may be using a VPN connection
9.3.5.4 Examples of Risk Response
Session Query
Sample Risk Response - Session Query
001Successabc123
Page 317 of 477
Canada Only
July 2018
Sample Risk Response - Session Query
yespaymentsession-25riskcheck4211kue09691C1879B-33D4-4D72-8FCB-B60A172B3CACmediumsuccess-25defaultreviewComputerGeneratedEMailUN001Unknown RuleRegle InconnusNoDeviceIDDV004No Device IDnull
Attribute Query
Sample Risk Response - Attribute Query
11kue096443D7FB5-CC5C-4917-A57E-27EAC824069Csessionmedium-25successdefault-25riskcheck19reviewComputerGeneratedEMailUN001Unknown RuleRegle InconnusNoDeviceID
July 2018
Canada Only
Page 318 of 477
Moneris Gateway API - Integration Guide
Sample Risk Response - Attribute Query
DV004No Device IDnull
9.3.6 Inserting the Profiling Tags Into Your Website
Place the profiling tags on an HTML page served by your web application such that ThreatMetrix can collect device information from the customer’s web browser. The tags must be placed on a page that a visitor would display in a browser window for 3-5 seconds (such as a page that requires a user to input
data). After the device is profiled, a Session Query may be used to obtain the detail device information
for risk assessment before submitting a financial payment transaction.
There are two profiling tags that require two variables. Those tags are org_id and session_id. session_id must match the session ID value that is to be passed in the Session Query transaction. The
valid org_id values are:
11kue096
QA testing environment.
lbhqgx47
Production environment.
Below is an HTML sample of the profiling tags.
NOTE: Your site must replace in the sample code with a unique alphanumeric value each time you fingerprint a new customer.
File Type : PDF
File Type Extension : pdf
MIME Type : application/pdf
PDF Version : 1.4
Linearized : No
Page Count : 477
Page Mode : UseOutlines
Page Layout : SinglePage
Language : en-us
Producer : madbuild
Create Date : 2018:07:06 14:00:13-04:00
Modify Date : 2018:07:06 14:00:13-04:00
Title : My Document
Author : michael.pukin
Subject :
.
Page 319 of 477
Canada Only
July 2018
9.4 Encorporating All Available Fraud Tools
l
l
l
9.4.1 Implementation Options for TRMT
9.4.2 Implementation Checklist
9.4.3 Making a Decision
To minimize fraudulent activity in online transactions, Moneris recommends that you implement all of
the fraud tools available through the Moneris Gateway. These are explained below:
Address Verification Service (AVS)
Verifies the cardholder's billing address information.
Verified by Visa, MasterCard Secure Code and Amex SafeKey (VbV/MCSC/SafeKey)
Authenticates the cardholder at the time of an online transaction.
Card Validation Digit (CVD)
Validates that cardholder is in possession of a genuine credit card during the transaction.
Note that all responses that are returned from these verification methods are intended to provide added
security and fraud prevention. The response itself does not affect the completion of a transaction. Upon
receiving a response, the choice to proceed with a transaction is left entirely to the merchant.
9.4.1 Implementation Options for TRMT
Option A
Process a Transaction Risk Management Tool query and obtain the response. You can then decide
whether to continue with the transaction, abort the transaction, or use additional efraud features.
If you want to use additional efraud features, perform one or both of the following to help make your
decision about whether to continue with the transaction or abort it:
l
l
Process a VbV/MCSC/SafeKey transaction and obtain the response. The merchant then makes the
decision whether to continue with the transaction or to abort it.
Process a financial transaction including AVS/CVD details and obtain the response. The merchant
then makes a decision whether to continue with the transaction or to abort it.
Option B
1.
2.
3.
4.
Process a Transaction Risk Management Tool query and obtain the response.
Process a VbV/MCSC/SafeKey transaction and obtain the response.
Process a financial transaction including AVS/CVD details and obtain the response.
Merchant then makes a one-time decision based on the responses received from the eFraud
tools.
9.4.2 Implementation Checklist
The following checklists provide high-level tasks that are required as part of your implementation of the
Transaction Risk Management Tool. Because each organization has certain project requirements for
implementing system and process changes, this list is only a guideline, and does not cover all aspects of
your project.
July 2018
Page 320 of 477
Moneris Gateway API - Integration Guide
Download and review all of the applicable APIs and Integration Guides
Please review the sections outlined within this document that refers to the following feature
Table 94: API documentation
Document/API
Use the document if you are….
Transaction Risk Management Tool Integration
Guide (Section #)
Implementing or updating your integration for the
Transaction Risk Management Tool
Moneris MPI – Verified by Visa/MasterCard
SecureCode/American Express SafeKey – Java API
Integration Guide
Implementing or updating Verified by Visa, MasterCard SecureCode or American Express SafeKey
Basic transaction with VS and CVD (Section#)
Implementing or updating transaction processing,
AVS or CVD
Design your transaction flow and business processes
When designing your transaction flow, think about which scenarios you would like to have automated,
and which scenarios you would like to have handled manually by your employees.
The “Understand Transaction Risk Management Transaction Flow” and Handling Response Information
(page 306) sections can help you work through the design of your transaction and process flows.
Things to consider when designing your process flows:
l
l
l
Processes for notifying people within your organization when there is scheduled maintenance for
Moneris Gateway.
Handling refunds, canceled orders and so on.
Communicating with customers when you will not be shipping the goods because of suspected
fraud, back-ordered goods and so on.
Complete your development and testing
l
The Moneris Gateway API - Integration Guide provides the technical details required for the development and testing. Ensure that you follow the testing instructions and data provided.
If you are an integrator
l
l
l
Ensure that your solution meets the requirements for PCI-DSS/PA-DSS as applicable.
Send an email to eproducts@moneris.com with the subject line “Certification Request”.
Develop material to set up your customers as quickly as possible with your solution and a Moneris
account. Include information such as:
l Steps they must take to enter their store ID or API token information into your solution.
Page 321 of 477
July 2018
l
Any optional services that you support via Moneris Gateway (such as TRMT, AVS, CVD,
VBV/MCSC/SafeKey and so on) so that customers can request these features.
9.4.3 Making a Decision
Depending on your business policies and processes, the information obtained from the fraud tools (such
as AVS, CVD, VbV/MCSC/SafeKey and TRMT) can help you make an informed decision about whether to
accept a transaction or deny it because it is potentially fraudulent.
If you do not want to continue with a likely fraudulent transaction, you must inform the customer that
you are not proceeding with their transaction.
If you are attempting to do further authentication by using the available fraud tools, but you have
received an approval response instead, cancel the financial transaction by doing one of the following:
l
l
If the original transaction is a Purchase, use a Purchase Correction or Refund transaction. You will
need the original order ID and transaction number.
If the original transaction is a Pre-Authorization, use a Completion transaction for $0.00.
July 2018
Page 322 of 477
10 Apple Pay In-App and on the Web Integration
l
l
l
l
l
10.1 About Apple Pay In-App and on the Web Integration10.1 About Apple Pay In-App and on the
Web Integration
10.2 About API Integration of Apple Pay
10.3 Apple Pay In-App Process Flows10.3 Apple Pay In-App Process Flows
10.4 Cavv Purchase – Apple Pay In-App and on the Web10.4 Cavv Purchase – Apple Pay In-App and
on the Web
10.5 Cavv Pre-Authorization – Apple Pay
10.1 About Apple Pay In-App and on the Web Integration
The Moneris Gateway enables merchants to process in-app or on the web payment methods in mobile
applications and the Safari web browser on Apple devices via Apple Pay.
Moneris Solutions offers two processing and integration methods for Apple Pay. Merchants can choose
to use one of two methods:
l
l
Software Development Kit (SDK), or
API
While both methods provide the same basic payment features, there are differences in their implementations.
This guide only deals with the API method; for detailed information about the SDK method of integration, see the Moneris Developer Portal at https://developer.moneris.com.
10.2 About API Integration of Apple Pay
An API integration works to provide a communication link between the merchants’ server and Moneris’
server. APIs are required to complete any transaction, and therefore the APIs for Apple Pay are also
included within an SDK integration.
If the merchant chooses to use only an API integration, the merchant must decrypt payload information
themselves before sending the decrypted information to the Moneris Gateway to be processed. Because
this process is complicated, Apple recommend only businesses with expertise and a previously integrated payment processing system use APIs instead of SDKs.
10.2.1 Transaction Types That Use Apple Pay
In the Moneris Gateway API, there are two transaction types that allow you to process decrypted transaction payload information with Apple Pay:
l
l
10.4 Cavv Purchase – Apple Pay In-App and on the Web10.4 Cavv Purchase – Apple Pay In-App
and on the Web
10.5 Cavv Pre-Authorization – Apple Pay
July 2018
Page 323 of 477
Moneris Gateway API - Integration Guide
NOTE: INTERAC® e-Commerce functionality is currently available using the Cavv
Purchase transaction type only.
Once you have processed the initial transaction using Cavv Purchase or Cavv Pre-Authorization, if
required you can then process any of the following transactions:
l
l
l
Refund (page 33)
Pre-Authorization Completion (page 23)
Purchase Correction (page 31)
10.3 Apple Pay In-App Process Flows
For both API and SDK methods of mobile in-app integration, the merchant’s iOS app uses Apple’s PassKit
Framework to request and receive encrypted payment details from Apple. When payment details are
returned in their encrypted form, they can be decrypted and processed by the Moneris Gateway in one
of two ways: SDK or API.
Steps in the Apple Pay In-App and on the Web payment process
API
1. Merchant’s mobile application or web page requests and receives the encrypted payload.
2. Encrypted payload is sent to the merchant’s server, where it is decrypted.
Page 324 of 477
July 2018
10 Apple Pay In-App and on the Web Integration
3. Moneris Gateway receives the decrypted payload from the merchant’s server, and processes the
Cavv Purchase – Apple Pay In-App and on the Web (page 325)Cavv Purchase – Apple Pay In-App
and on the Web (page 325) or Cavv Pre-Authorization – Apple Pay (page 329)Cavv Pre-Authorization – Apple Pay (page 329) transaction.
a. Please ensure the wallet indicator is properly populated with the correct value (APP for
Apple Pay In-App or APW for Apple Pay on the Web).
SDK
1. Merchant's mobile application or web page requests and receives the encrypted payload.
2. Encrypted payload is sent from the merchant’s server to the Moneris Gateway, and the payload is
decrypted and processed.
This guide only deals with the API method; for detailed information about the SDK method of integration, see the Moneris Developer Portal at https://developer.moneris.com.
10.4 Cavv Purchase – Apple Pay In-App and on the Web
The Cavv Purchase for Apple Pay transaction follows a 3-D Secure model but it does not require an MPI.
Once the Apple Pay payload has been decrypted, this Purchase verifies funds on the customer’s card,
removes the funds and prepares them for deposit into the merchant’s account.
For Apple Pay processing, this transaction is only applicable if choosing to integrate directly to the Apple
Wallet (if not using the Moneris Apple Pay SDK). Please refer to 10 Apple Pay In-App and on the Web
Integration for more details on your integration options.
Refer to Apple's Developer Portal for details on integrating directly to Apple Wallet to retrieve the payload data.
CavvPurchase transaction object definition
CavvPurchase cavvPurchase = new CavvPurchase();
HttpsPostRequest object for Cavv Purchase transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(cavvPurchase);
Cavv Purchase transaction values
For a full description of mandatory and optional values, see Appendix A Definitions of Request Fields
July 2018
Page 325 of 477
Moneris Gateway API - Integration Guide
Table 95: Cavv Purchase transaction object mandatory values
Value
Type
Limits
Set method
Order ID
String
50-character alphanumeric
cavvPurchase.setOrderId
(order_id);
Amount
String
9-character decimal
cavvPurchase.setAmount
(amount);
Credit card number
String
20-character alphanumeric
cavvPurchase.setPan(pan);
Expiry date
String
4-character alphanumeric
cavvPurchase.setExpDate
(expiry_date);
YYMM format
CAVV
String
100-character alphanumeric
cavvPurchase.setCavv(cavv);
String
1-character alphanumeric
cavvPurchase.setCryptType
(crypt);
NOTE: For Apple Pay
Cavv Purchase and
Cavv Pre-Authorization
transactions, CAVV
field contains the
decrypted cryptogram.
For more, see
Appendix A Definitions
of Request Fields.
E-commerce indicator
NOTE: For Apple Pay
Cavv Purchase and
Cavv Pre-Authorization
transactions, the Ecommerce indicator is
a mandatory field containing the value
received from the
decrypted payload or a
default value of 5. If
you get a 2-character
value (e.g.,. 05 or 07)
from the payload,
remove the initial 0
and just send us the
2nd character. For
more, see Appendix A
Definitions of Request
Fields.
Page 326 of 477
July 2018
10 Apple Pay In-App and on the Web Integration
Table 1: CavvPurchase transaction object optional values
Value
Type
Limits
Set Method
Status Check
Boolean
true/false
mpgReq.setStatusCheck
(status_check);
Customer ID
String
50-character alphanumeric
cavvPurchase.setCustId(cust_
id);
Dynamic descriptor
String
20-character alphanumeric
cavvPurchase
.setDynamicDescriptor
(dynamic_descriptor);
Customer information
Object
N/A
CustInfo customer = new
CustInfo();
cavvPurchase.setCustInfo
(customer);
Network
String
alphabetical
cavvPurchase.SetNetwork
(network);
String
3-character alphanumeric
cavvPurchase.SetDataType
(data_type);
NOTE: This request
variable is mandatory
for INTERAC® e-Commerce transactions
conducted via Apple
Pay, and is not for use
with credit card transactions.
Data Type
NOTE: This request
variable is mandatory
for INTERAC® e-Commerce transactions
conducted via Apple
Pay, and is not for use
with credit card transactions.
Sample Cavv Purchase for Apple Pay
package Canada;
import JavaAPI.*;
public class TestCanadaCavvPurchase
{
July 2018
Page 327 of 477
Moneris Gateway API - Integration Guide
Sample Cavv Purchase for Apple Pay
public static void main(String[] args)
{
String store_id = "store5";
String api_token = "yesguy";
java.util.Date createDate = new java.util.Date();
String order_id = "Test"+createDate.getTime();
String cust_id = "CUS887H67";
String amount = "10.42";
String pan = "4242424242424242";
String expdate = "1901"; //YYMM
String cavv = "AAABBJg0VhI0VniQEjRWAAAAAAA=";
String dynamic_descriptor = "123456";
String processing_country_code = "CA";
String crypt_type = "5";
boolean status_check = false;
CavvPurchase cavvPurchase = new CavvPurchase();
cavvPurchase.setOrderId(order_id);
cavvPurchase.setCustId(cust_id);
cavvPurchase.setAmount(amount);
cavvPurchase.setPan(pan);
cavvPurchase.setExpdate(expdate);
cavvPurchase.setCavv(cavv);
cavvPurchase.setCryptType(crypt_type); //Mandatory for AMEX only
cavvPurchase.setDynamicDescriptor(dynamic_descriptor);
//cavvPurchase.setWalletIndicator("APP"); //set only for wallet transactions. e.g APPLE PAY
//cavvPurchase.setNetwork("Interac"); //set only for Interac e-commerce
//cavvPurchase.setDataType("3DSecure"); //set only for Interac e-commerce
//optional - Card on File details
CofInfo cof = new CofInfo();
cof.setPaymentIndicator("Z");
cof.setPaymentInformation("0");
cof.setIssurId("139X3130ASCXAS9");
cavvPurchase.setCofInfo(cof);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(cavvPurchase);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
Page 328 of 477
July 2018
10 Apple Pay In-App and on the Web Integration
Sample Cavv Purchase for Apple Pay
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
System.out.println("CavvResultCode = " + receipt.getCavvResultCode());
System.out.println("IssueId = " + receipt.getIssuerId());
}
catch (Exception e)
{
e.printStackTrace();
}
}
}
10.5 Cavv Pre-Authorization – Apple Pay
The Cavv Pre-Authorization for Apple Pay transaction follows a 3-D Secure model but it does not require
an MPI. Once the Apple Pay payload has been decrypted, this Pre-Authorization verifies funds on the customer’s card, and holds the funds. To prepare the funds for deposit into the merchant’s account please
process a Pre-Authorization Completion transaction.
For Apple Pay processing, this transaction is only applicable if choosing to integrate directly to the Apple
Wallet (if not using the Moneris Apple Pay SDK). Please refer to 10 Apple Pay In-App and on the Web
Integration for more details on your integration options.
Refer to Apple's Developer Portal for details on integrating directly to Apple Wallet to retrieve the payload data.
NOTE: INTERAC® e-Commerce functionality is currently available using the Cavv
Purchase transaction type only.
Cavv Pre-Authorization transaction object definition
CavvPreAuth cavvPreauth = new CavvPreAuth();
HttpsPostRequest object for Cavv Pre-Authorization transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(cavvPreauth);
July 2018
Page 329 of 477
Moneris Gateway API - Integration Guide
Cavv Pre-Authorization transaction values
Table 96: Cavv Pre-Authorization object mandatory values
Value
Type
Limits
Set method
Order ID
String
50-character alphanumeric
cavvPreauth.setOrderId
(order_id);
Amount
String
9-character decimal
cavvPreauth.setAmount
(amount);
Credit card number
String
20-character numeric
cavvPreauth.setPan(pan);
Cardholder Authentication Verification
Value (CAVV)
String
50-character alphanumeric
cavvPreauth.setCavv(cavv);
Expiry date
String
4-character numeric
cavvPreauth.setExpDate
(expiry_date);
E-commerce indicator
String
1-character alphanumeric
cavvPreauth.setCryptType
(crypt);
NOTE: For Apple Pay
Cavv Purchase and
Cavv Pre-Authorization
transactions, CAVV
field contains the
decrypted cryptogram.
For more, see
Appendix A Definitions
of Request Fields.
NOTE: For Apple Pay
Cavv Purchase and
Cavv Pre-Authorization
transactions, the Ecommerce indicator is
a mandatory field containing the value
received from the
decrypted payload or a
default value of 5. If
you get a 2-character
value (e.g.,. 05 or 07)
from the payload,
remove the initial 0
and just send us the
2nd character. For
more, see Appendix A
Definitions of Request
Fields.
Page 330 of 477
July 2018
10 Apple Pay In-App and on the Web Integration
Table 1: Cavv Pre-Authorization object optional values
Value
Type
Limits
Set method
Status Check
Boolean
true/false
mpgReq.setStatusCheck
(status_check);
Customer ID
String
50-character alphanumeric
cavvPreauth.setCustId(cust_
id);
Dynamic descriptor
String
20-character alphanumeric
cavvPreauth
.setDynamicDescriptor
(dynamic_descriptor);
Network
String
alphabetical
cavvPurchase.SetNetwork
(network);
String
3-character alphanumeric
cavvPurchase.SetDataType
(data_type);
NOTE: This request
variable is mandatory
for INTERAC® e-Commerce transactions
conducted via Apple
Pay, and is not for use
with credit card transactions.
Data Type
NOTE: This request
variable is mandatory
for INTERAC® e-Commerce transactions
conducted via Apple
Pay, and is not for use
with credit card transactions.
Sample Cavv Pre-Authorization for Apple Pay
package Canada;
import JavaAPI.*;
public class TestCanadaCavvPreauth
{
public static void main(String[] args)
{
String store_id = "store5";
String api_token = "yesguy";
java.util.Date createDate = new java.util.Date();
String order_id = "Test"+createDate.getTime();
String cust_id = "CUS887H67";
July 2018
Page 331 of 477
Moneris Gateway API - Integration Guide
Sample Cavv Pre-Authorization for Apple Pay
String amount = "10.42";
String pan = "4242424242424242";
String expdate = "1911"; //YYMM format
String cavv = "AAABBJg0VhI0VniQEjRWAAAAAAA=";
String dynamic_descriptor = "123456";
String processing_country_code = "CA";
String crypt_type = "5";
boolean status_check = false;
CavvPreAuth cavvPreauth = new CavvPreAuth();
cavvPreauth.setOrderId(order_id);
cavvPreauth.setCustId(cust_id);
cavvPreauth.setAmount(amount);
cavvPreauth.setPan(pan);
cavvPreauth.setExpdate(expdate);
cavvPreauth.setCavv(cavv);
cavvPreauth.setCryptType(crypt_type); //Mandatory for AMEX only
cavvPreauth.setDynamicDescriptor(dynamic_descriptor);
//cavvPreauth.setWalletIndicator("APP"); //set only for wallet transactions. e.g APPLE PAY
//optional - Card on File details
CofInfo cof = new CofInfo();
cof.setPaymentIndicator("Z");
cof.setPaymentInformation("0");
cof.setIssurId("139X3130ASCXAS9");
cavvPreauth.setCofInfo(cof);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(cavvPreauth);
mpgReq.setStatusCheck(status_check);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
System.out.println("CavvResultCode = " + receipt.getCavvResultCode());
System.out.println("IssueId = " + receipt.getIssuerId());
}
catch (Exception e)
{
e.printStackTrace();
Page 332 of 477
July 2018
10 Apple Pay In-App and on the Web Integration
Sample Cavv Pre-Authorization for Apple Pay
}
}
}
July 2018
Page 333 of 477
11 Convenience Fee
l
l
l
l
11.1
11.2
11.3
11.4
About Convenience Fee
Purchase with Convenience Fee
Convenience Fee Purchase w/ Customer Information
Convenience Fee Purchase with VbV, MCSC and Amex SafeKey
11.1 About Convenience Fee
The Convenience Fee program was designed to allow merchants to offer the convenience of an alternative payment channel to the cardholder at a charge. This applies only when providing a true "convenience" in the form of an alternative payment channel outside the merchant's customary face-to-face
payment channels. The convenience fee will be a separate charge on top of what the consumer is paying
for the goods and/or services they were given, and this charge will appear as a separate line item on the
consumer’s statement.
NOTE: The Convenience Fee program is only offered to certain supported Merchant Category Codes (MCCs). Please speak to your account manager for further details.
11.2 Purchase with Convenience Fee
NOTE: Convenience Fee Purchase with Customer Information is also supported.
Convenience Fee Purchase transaction object definition
Purchase purchase = new Purchase();
HttpsPostRequest object for Convenience Fee Purchase transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(purchase);
Convenience Fee Purchase transaction object values
For a full description of mandatory and optional values, see Appendix A Definitions of Request Fields
July 2018
Page 334 of 477
Moneris Gateway API - Integration Guide
Table 1: Convenience Fee Purchase transaction object mandatory values
Value
Type
Convenience Fee
Object
Limits
Set Method
ConvFeeInfo convFeeInfo = new
ConvFeeInfo();
n/a
purchase.setConvenienceFee
(convFeeInfo);
Order ID
String
50-character alphanumeric
purchase.setOrderId(order_
id);
Amount
String
9-character decimal
purchase.setAmount(amount);
Credit card number
String
20-character numeric
purchase.setPan(pan);
Expiry date
String
4-character numeric
YYMM format
purchase.setExpDate(expiry_
date);
E-commerce indicator
String
1-character alphanumeric
purchase.setCryptType(crypt);
Convenience fee
amount
String
9-character decimal
convFeeInfo.setConvenienceFee
(convfee_amount);
Table 2: Convenience Fee Purchase transaction object optional values
Value
Type
Limits
Set Method
Customer ID
String
50-character alphanumeric
purchase.setCustId(cust_id);
Dynamic descriptor
String
20-character alphanumeric
purchase
.setDynamicDescriptor
(dynamic_descriptor);
AVS information
Object
AvsInfo avsCheck = new
AvsInfo();
purchase.setAvsInfo
(avsCheck);
CVD information
Object
CvdInfo cvdCheck = new
CvdInfo();
purchase.setCvdInfo
(cvdCheck);
Page 335 of 477
July 2018
11 Convenience Fee
Sample Purchase with Convenience Fee
package Canada;
import JavaAPI.*;
public class TestCanadaConvFeePurchase
{
public static void main(String args[])
{
String store_id = "monca00392";
String api_token = "qYdISUhHiOdfTr1CLNpN";
String processing_country_code = "CA";
java.util.Date createDate = new java.util.Date();
String order_id = "Test"+createDate.getTime();
String amount = "10.00";
String pan = "4242424242424242";
String expdate = "1911";
String crypt = "7";
ConvFeeInfo convFeeInfo = new ConvFeeInfo();
convFeeInfo.setConvenienceFee("1.00");
Purchase purchase = new Purchase();
purchase.setOrderId(order_id);
purchase.setAmount(amount);
purchase.setPan(pan);
purchase.setExpdate(expdate);
purchase.setCryptType(crypt);
purchase.setConvFeeInfo(convFeeInfo);
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setProcCountryCode(processing_country_code);
mpgReq.setTestMode(true); //false or comment out this line for production transactions
mpgReq.setStoreId(store_id);
mpgReq.setApiToken(api_token);
mpgReq.setTransaction(purchase);
mpgReq.send();
try
{
Receipt receipt = mpgReq.getReceipt();
System.out.println("CardType = " + receipt.getCardType());
System.out.println("TransAmount = " + receipt.getTransAmount());
System.out.println("TxnNumber = " + receipt.getTxnNumber());
System.out.println("ReceiptId = " + receipt.getReceiptId());
System.out.println("TransType = " + receipt.getTransType());
System.out.println("ReferenceNum = " + receipt.getReferenceNum());
System.out.println("ResponseCode = " + receipt.getResponseCode());
System.out.println("ISO = " + receipt.getISO());
System.out.println("BankTotals = " + receipt.getBankTotals());
System.out.println("Message = " + receipt.getMessage());
System.out.println("AuthCode = " + receipt.getAuthCode());
System.out.println("Complete = " + receipt.getComplete());
System.out.println("TransDate = " + receipt.getTransDate());
System.out.println("TransTime = " + receipt.getTransTime());
System.out.println("Ticket = " + receipt.getTicket());
System.out.println("TimedOut = " + receipt.getTimedOut());
System.out.println("CfSuccess = " + receipt.getCfSuccess());
System.out.println("CfStatus = " + receipt.getCfStatus());
System.out.println("FeeAmount = " + receipt.getFeeAmount());
System.out.println("FeeRate = " + receipt.getFeeRate());
System.out.println("FeeType = " + receipt.getFeeType());
}
catch (Exception e)
July 2018
Page 336 of 477
Moneris Gateway API - Integration Guide
Sample Purchase with Convenience Fee
{
e.printStackTrace();
}
}
}
11.3 Convenience Fee Purchase w/ Customer Information
Convenience Fee Purchase with Customer information transaction object definition
Purchase purchase = new Purchase();
HttpsPostRequest object for Convenience Fee Purchase with Customer Info transaction
HttpsPostRequest mpgReq = new HttpsPostRequest();
mpgReq.setTransaction(purchase);
Convenience Fee Purchase with Customer information transaction object values
For a full description of mandatory and optional values, see Appendix A Definitions of Request Fields
Table 1: Convenience Fee Purchase w/ Customer Info transaction object mandatory values
Value
Convenience Fee
Type
Object
Limits
n/a
Set Method
ConvFeeInfo convFeeInfo = new
ConvFeeInfo();
purchase.setConvenienceFee
(convFeeInfo);
Order ID
String
50-character alphanumeric
purchase.setOrderId(order_
id);
Amount
String
9-character decimal
purchase.setAmount(amount);
Credit card number
String
20-character numeric
purchase.setPan(pan);
Page 337 of 477
July 2018
11 Convenience Fee
Table 1: Convenience Fee Purchase w/ Customer Info transaction object mandatory values (continued)
Value
Type
Limits
Set Method
Expiry date
String
4-character numeric
YYMM format
purchase.setExpDate(expiry_
date);
E-commerce indicator
String
1-character alphanumeric
purchase.setCryptType(crypt);
Convenience fee
amount
String
9-character decimal
purchase
convFeeInfo.setConvenienceFee
(convfee_amount);
Table 2: Convenience Fee Purchase w/ Customer Info transaction object optional values
Value
Type
Limits
Set Method
Customer ID
String
50-character alphanumeric
purchase.setCustId(cust_id);
Dynamic descriptor
String
20-character alphanumeric
purchase
.setDynamicDescriptor
(dynamic_descriptor);
Customer information
Object
n/a
CustInfo customer = new
CustInfo();
purchase.setCustInfo
(customer);
AVS information
Object
n/a
AvsInfo avsCheck = new
AvsInfo();
purchase.setAvsInfo
(avsCheck);
CVD information
Object
n/a
CvdInfo cvdCheck = new
CvdInfo();
purchase.setCvdInfo
(cvdCheck);
Sample Convenience Fee Purchase with Customer Information
package Canada;
July 2018
Page 338 of 477
Moneris Gateway API - Integration Guide
Sample Convenience Fee Purchase with Customer Information
import java.util.*;
import JavaAPI.*;
public class TestCanadaConvFeePurchaseCustInfo
{
public static void main(String[] args)
{
String store_id = "monca00392";
String api_token = "qYdISUhHiOdfTr1CLNpN";
java.util.Date createDate = new java.util.Date();
String order_id = "Test"+createDate.getTime();
String amount = "10.00";
String pan = "4242424242424242";
String expdate = "1901"; //YYMM format
String crypt = "7";
String processing_country_code = "CA";
boolean status_check = false;
/********************* Billing/Shipping Variables ****************************/
String first_name = "Bob";
String last_name = "Smith";
String company_name = "ProLine Inc.";
String address = "623 Bears Ave";
String city = "Chicago";
String province = "Illinois";
String postal_code = "M1M2M1";
String country = "Canada";
String phone = "777-999-7777";
String fax = "777-999-7778";
String tax1 = "10.00";
String tax2 = "5.78";
String tax3 = "4.56";
String shipping_cost = "10.00";
/********************* Order Line Item Variables *****************************/
String[] item_description = new String[] { "Chicago Bears Helmet", "Soldier Field Poster" };
String[] item_quantity = new String[] { "1", "1" };
String[] item_product_code = new String[] { "CB3450", "SF998S" };
String[] item_extended_amount = new String[] { "150.00", "19.79" };
/********* ************************************* *******************************/
/* */
/* Customer Information Option 1 */
/* */
/********** ************************************ *******************************/
/********************** Customer Information Object **************************/
CustInfo customer = new CustInfo();
/********************** Set Customer Billing Information **********************/
customer.setBilling(first_name, last_name, company_name, address, city,
province, postal_code, country, phone, fax, tax1, tax2,
tax3, shipping_cost);
/******************** Set Customer Shipping Information ***********************/
customer.setShipping(first_name, last_name, company_name, address, city,
province, postal_code, country, phone, fax, tax1, tax2,
tax3, shipping_cost);
/***************************** Order Line Items ******************************/
customer.setItem(item_description[0], item_quantity[0],
item_product_code[0], item_extended_amount[0]);
customer.setItem(item_description[1], item_quantity[1],
item_product_code[1], item_extended_amount[1]);
/********* ************************************** ******************************/
/* */
/* Customer Information Option 2 */
Page 339 of 477
July 2018
11 Convenience Fee
Sample Convenience Fee Purchase with Customer Information
/* */
/********* *************************************** *****************************/
/********************** Customer Information Object **************************/
CustInfo customer2 = new CustInfo();
/******************************* Billing Hashtable ***************************/
Hashtable