My Profile_


Introduction

This documentation contains the basic information for using the Moneris Card Present Android SDK.  It contains specifications for transaction requests and responses.   

This documentation is intended for use with the Ingenico iCMP PINpad.   

This device allows for:

  • Swiped transactions
  • Keyed transactions
  • EMV Chip transactions
  • Contactless (tapped) transactions

System and Skill Requirements

  1. Android Development toolkit
  2. Knowledge of Java and Android Development
  3. Moneris test iCMP Pinpad & test cards

Essential Integration Tasks

  1. To use the Android library, you as an integrator will need to have a copy of all the files from the libs folder into your $ANDROID_PROJECT/libs folder. Make sure the files in the armeabi are also included.


  2. Add the below permissions in the AndroidManifest.xml

    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    <uses-permission android:name="android.permission.BLUETOOTH"/>
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
    <uses-permission android:name="android.permission.READ_PHONE_STATE"/>


  3. To start the development process, the integrator will have to use the TerminalService, and then bind to it. Once the terminal service is binded. The integrator will have an instance of a terminal object which you can interact with.

Merchant Payment Application Request Flow

Below is a diagram with explanations about the interaction between the merchant’s payment application and the iCMP PINpad.

  1. Merchant Application initiates a transaction request to the Terminal Android Service
  2. The Terminal Android Service performs all the interaction between the PINpad and the Moneris Gateway.
  3. The Terminal Android Service provides methods for merchant application to retrieve PINpad response and build receipt.
  4. The Terminal Android Service sends transaction to the Moneris Gateway.
  5. The Moneris Gateway sends transaction to the authorizing host.
  6. The authorizing host returns response to the Moneris Gateway.
  7. The Moneris Gateway returns response to Terminal Android Service.
  8. The terminal Android Service sends the response to merchant application to generate receipt.

Function Types

Moneris Gateway Card Present supports a wide variety of transactions through the Terminal iOS library. Below is a list of all supported functions. The functions are grouped into 3 categories, the Administrative Tasks required to communicate with the PINpad, the Financial Transactions required to secure and settle funds, and the delegate methods required to manage the response and create a receipt.

Function Description Method Name | Parameters
Administrative Tasks
Initialization Initialize function allows your merchant application to connect to the PINpad. This function is required:
  • on start-up of the application with the PINpad connected and fully booted up
  • on swap out of the PINpad
  • in the event that the PINpad prompts for initialization
 
initialize();
Batch Close When a Batch Close transaction is performed, it settles the funds from all Purchase, Completion, and Refund transactions so they will be deposited or debited on the following business day.  For funds to be deposited the following business day the batch must close before 11pm Eastern time.  If the merchant account is configured for automated batch-close, then this function is not required.   batchClose();
Connect The bluetooth connects to the allocated bluetooth address connect();
Disconnect Bluetooth disconnects from the allocated address. void disconnect();  
Bluetooth address Allocates the address the Bluetooth address that the device is connected on. void setBluetoothAddress(address);  
Tip This is a method called to set tip void setTip(bool askForTip);  
Financial Transactions
Purchase The Purchase transaction verifies funds on the customer’s card, removes the funds and readies them for deposit into the merchant’s account. -purchase
orderId,
amount,
cc_num,
cc_exp,
cust_id,
ecom,
card_type
 
Authorization The 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.  A Completion transaction must be performed for the funds to settle into the merchant’s account.  This transaction can only be performed on a credit card. -creditPreauth
orderId,
amount,
cc_num,
cc_expdate,
cust_id,
ecom
 
Completion The Completion follow-on transaction retrieves the locked funds and readies them for deposit into merchant’s account.  Completion transactions should be sent using the original Authorization transaction’s Order ID, Transaction Number returned in the Authorization response, and the amount.  The options to send the track2 or the credit card number with expiry date should not be used as a Completion transaction. This transaction can only be performed on aTerminal credit card.   -creditPreauthCompletion
orderId,
TxnNumber,
amount,
cc_num,
cc_expdate,  
ecom
 
Purchase Correction Purchases and Completions can be voided the same day that they occur (priori to batch close). When using the automated closing feature, batch-close occurs daily between 10 – 11 pm Eastern Time. A Purchase Correction transaction amount must be the same as the original transaction. Purchase Correction transactions should be sent using the original transaction’s Order ID and the Transaction Number returned in the original transaction response.  The option to send the track2 or the credit card number with expiry date should not be used in a Purchase Correction transaction.   -purchaseCorrection
orderId,
amount,
TxnNumber,
cc_num,
cc_expdate, 
ecom
 
Refund A Refund follow-on transaction can be performed against a Purchase or a Completion to refund any part, or all of the transaction.  Refund can only be performed on the same card used in the original Purchase or Completion transaction.  Refund transactions should be sent using the original transaction’s Order ID, the Transaction Number returned in the original transaction response, and the amount.  The option to send the track2 or the credit card number with expiry date should not be used as a Refund transaction.  An Independent Refund transaction is available to process a refund on a different card.   -refund
OrderId,
amount,
TxnNumber,
cc_num,
cc_expdate,
ecom)    
Events
Terminal Service public void processStatus(int status)
public void processTransactionCompleted()
public void processReceipt(TerminalReceipt receipt)  // See the processReceipt method for all the getters in the TerminalReceipt
public void processDisplay(String msg)
public void terminalConnected()
public void terminalDisconnected()  
 

Steps for Processing a Transaction

Step 1 Download Configuration From Moneris Host Initialization

Required once upon setup to download the configuration from the Moneris host to the PINpad.



Step 2 Process a transaction Purchase

Send any of the financial transactions to secure funds and settle funds.

Test the Solution

Test Credentials:

To request a personal account be setup for PINpad testing please refer to the Custom QA Account Request form.

When testing your code populate the following fields with your personal Store ID or API Token. You may also use one of the following pre-created test accounts:

Canada
self.terminal.storeId = @"store_icmp";
self.terminal.apiToken = @"icmpguy";
self.terminal.eSelectHost= @"esqa.moneris.com";

Test Cards:

Please contact our Client Integration team to request test cards. Client Integration contact information may be found in How Do I Get Help? Due to security and compliance reasons, the use of live credit and debit card numbers for testing is strictly prohibited. Only test credit and debit card numbers are to be utilized.

Simulator Host:

The test environment has been designed to replicate our production environment as closely as possible. One major difference is that we are unable to send test transactions onto the production authorization network and thus Issuer responses are simulated. The test environment will approve and decline transactions based on the penny value of the amount sent. For example, a transaction made for the amount of $9.00 or $1.00 will approve since the .00 penny value is set to approve in the test environment. Transactions in the test environment should not exceed $11.00. For a list of all current test environment responses for various penny values, please see the Penny Value Simulator Response Table.

NOTE: These responses may change without notice. Moneris Solutions recommends you regularly refer to our website to check for possible changes.

Transaction Receipt Requirements

Production of the physical receipt must begin when the appropriate response to the transaction request is received by the terminal. The transaction may be any of the following:

  • Sale (Purchase)
  • Authorization (PreAuth)
  • Authorization Completion (Completion)
  • Offline Sale (Force Post)
  • Sale Void (Purchase Correction)
  • Refund

NOTE: The terms listed above are the names for transactions as they are to be displayed on receipts. Other terms used for the transaction type are indicated in brackets.

Receipts must comply with the standards outlined within Receipt Requirements. Receipts are required to complete certification.

Certification Requirements

Once you have completed the development and testing, your application must undergo a certification process where all the applicable transaction types must be demonstrated and the corresponding receipts properly generated.

Please contact a Client Integration Specialist for the Certification Test checklist that must be completed and returned to us for verification.

Please refer to How Do I Get Help? for contact details. Be sure to include the application version of your product. Any further changes to the product after certification would require a new re-certification. Once all the certification requirements are met, we will provide you with an official certification letter.

Configure Your Application For Production

Once you have completed your testing you are ready to point your store to the production host, you will need to change the “Host”. You will also need to change the store_id to reflect your production store ID and the api_token must be changed to your production token to reflect the token that you received during activation.

Host URLs
Production Development / QA
Canada www3.moneris.com esqa.moneris.com

Example

Production Development
self.terminal.storeId = @"monxxxxxxx"; //Provided by Moneris
self.terminal.apiToken = @"xxxxxxx"; //Provided by Moneris
self.terminal.eSelectHost=@"www3.moneris.com";
self.terminal.storeId = @"store_icmp";
self.terminal.apiToken = @"icmpguy";
self.terminal.eSelectHost=@"esqa.moneris.com";

Moving into Production

When moving your merchant/account to production you will be required to configure/pass transaction credentials assigned to your merchant/account by Moneris. The credentials known as Store Id and API Token are assigned when merchants complete the store activation process as described in the Welcome letter.

In cases where you are enabling multiple physical locations for a given merchant/account, it is important that this is a coordinated effort between you and/or your merchant customer in order to minimize input errors and to ensure that the correct payment credentials are assigned to each Moneris account/store.

By default batch-close is set to occur automatically on a daily basis between 10 and 11 pm Eastern Time. If your system requires the merchant account’s batch-close to be controlled by your system, please specify this requirement in your certification test results. In addition, your product documentation should describe the batch-close processes and instruct merchants to contact Moneris to have their batch-close set to manual.

Terminal Properties

Request Parameters

Variable

Limits

Description

Terminal Class Properties

StoreId

10 – character alphanumeric

This is defined and provided by Moneris Solutions and is used to identify the merchant.

NSString StoreId {get,set}

ApiToken

20 – character alphanumeric

This is defined and provided by Moneris Solutions and is used in conjunction with the Store ID to uniquely identify your store.

NSString ApiToken

Host

alphanumeric

 

Production

Development / QA

Canada

www3.moneris.com

esqa.moneris.com

NSString Host


Request Fields

Variable

Limits

Description

orderId

20 / an

(variable length)

Merchant defined unique transaction identifier - must be unique for every Purchase, Authorization and Independent Refund attempts, regardless if they approved or declined.  Must also be unique per merchant account, regardless of the number of lanes/PINpads.  For a follow-on transaction (Refunds, Completions, and Purchase Corrections) the order_id must reference the original transaction.

cc_num

20 / num

(variable length)

Credit Card Number - no spaces or dashes. Most credit card numbers today are between 14 and 16 digits in length. This field has been intentionally expanded to 20 digits in consideration for future expansion and/or potential support of private label card ranges.

Only required when manually entering the credit card.

Note:  Passing a value of M in the cc_num will allow to enter a manually keyed transaction through the PINpad.

cc_expdate

4 / num

Expiry Date - format YYMM no spaces or slashes.

Only required when manually entering the credit card.

amount

9 / decimal

(variable length)

Amount of the transaction. This must contain at least 3 digits with two penny values. The minimum value passed can be 0.01 and the maximum 999999.99

ecom

2 – character numeric

Face-to-face Installation:
00 – Should be set for this value for both swiped, contactless and keyed-in transactions
Unattended PINpad Installation:
27 – Should be set to this value for both swiped, contactless and keyed-in transactions

Mail Order / Telephone Order (MOTO)
10 – Should be set for this value in the event where the card number is obtained over telephone order or mail order and card number will be manually keyed on the device.

txnNumber

20 / varchar

Used when performing follow-on transactions - this must be filled with the value that was returned as the transactionNo in the response of the original transaction.  When performing a Completion this must reference the Authorization.  When performing a Refund or a Purchase Correction, this must reference the Completion or Purchase.

cust_id

20 / an (variable length)

This field can be sent as part of a Purchase or Authorization request.  It is searchable from the Moneris Merchant Resource Center.  It is commonly used for policy number, membership number, student ID or invoice number.

Card_type

2 / an (variable length)

This field allows for a card type to be passed in to the transaction constructor (see card type table below for domain of values).  If the card type parameter does not match the card type of the input card, then Terminal.ErrorCodes.CardTypeMismatch ErrorCodes will be thrown.

M = MasterCard
V = Visa
AX = American Express
NO = Novus/Discover in (Canada only)
DS= Discover (US only)
C = JCB (US only)
C1 = JCB (Canada only)
SE = Sears (Canada only)
P = Pin Debit (US only)
D = Debit (Canada only)


Response Fields

Variable Limits Description
orderId   20  – character alphanumeric (a-zA-Z0-9) Merchant defined unique transaction identifier - must be unique for every Purchase, Authorization and Independent Refund attempts, regardless if they approved or declined.  Must also be unique per merchant account, regardless of the number of lanes/Pinpads.  For a follow-on transaction (Refunds, Completions, and Purchase Corrections) the order_id must reference the original transaction.
AuthCode 8  – character alphanumeric The authorization code is returned by the issuer as part of the transaction response. This field must be displayed on the receipt.
ResponseCode 3  – character numeric The response code is used to determine whether the transaction was approved or declined. The receipt message is determined by the Response Code and the ISO code.
Response Code Result
0 – 49 (inclusive) 50 – 999 (inclusive) null Approved Declined Incomplete
  For a full list of response codes and the associated message please refer to the Financial Response Codes.
LastTxnNo 20 – character alphanumeric The transaction number is an identifier used by the Moneris Gateway to identify the transaction. This value is used for follow-on transactions (void, capture, refund). It does not need to be displayed on the receipt but should be stored in the application database.
Pan 4 – character numeric   The Pan returns the abbreviated card number to be displayed on the receipt. The Pan field will be comprised of digits forming part of the card number. The last 4 digit of the card number will be returned. 12 additional masking should be added in front of this value on the receipt.
TransType 2 – character numeric Transaction Type defines what type of transaction was performed. See below for definitions. A full description of the type of transaction performed must be displayed on the transaction receipt (Purchase, Refund, . . . ). 00 – Purchase 01 – Pre Authorization (Credit Cards only) 02 – Capture (Credit Cards only) 04 – Refund / Independent Refund 11 – Void
AccountType 2 – character numeric Account type defines the card type used and what type of account was used for a transaction. See below for definitions. On the transaction receipt an “Account Type” field must be present for a debit transaction with a full description of the account type (Checking, Savings). 1 – Checking 2 – Savings 4 – Credit Card
CardType 2 – character alphanumeric   Account type defines the card type used for a transaction. See below for definitions. On the transaction receipt a “Card Type” field must be displayed with the full description of the card (Visa, MasterCard . . .).
M = MasterCard 
V = Visa 
AX = American Express 
NO = Novus/Discover in (Canada only)
DS= Discover (US only)
C = JCB (US only)
C1 = JCB (Canada only)
SE = Sears (Canada only)
P = Pin Debit (US only)
D = Debit (Canada only)
Completed true/ false Indicates whether a transaction was completed or not.
TransDate 10 – character alphanumeric   Date of the transaction. Must be displayed on the transaction receipt. Format: YYYY-MM-DD  YYYY = 4 digit year  MM = 2 digit month (“0” left padded | Jan = 01)  DD = 2 digit day of month (“0” left padded)
TransTime 8 – character alphanumeric   Time of the transaction. Must be displayed on the transaction receipt. Format: HH:II:SS  HH = 2 digit hour, 24 hour clock (“0” left padded | 02 = 2am, 14 = 2pm)  II = 2 digit minute (“0” left padded)  SS = 2 digit seconds (“0” left padded)
RefNum 18 – character numeric   This is a bank transaction reference number.  The entire reference number must be displayed on the receipt.  The reference number should be followed by a “Swiped/Manual” indicator as defined under the response variable “Ecom”.  This information should also be stored by the merchant. The following illustrates the breakdown of this field where "210123450010690030” is the reference number returned in the message. Example: 210123450010690030
  • 21012345: Terminal ID
  • 001: Shift number
  • 069: Batch number
  • 003: Transaction number within the batch.
Format: nnnnnnnnnnnnnnnnnn (18 digits)
Ecom 2 – character numeric   This field will echo back the value submitted by the merchant payment application in the Ecom request field.
IsoCode 2 – character alphanumeric The ISO code is a bank issued response code. The ISO code and the response code are used to determine the receipt message.
Amount 10 - decimal The amount represents the amount that the cardholder was charged/refunded. The amount must be displayed on the receipt. Format: nnnnnnN.NN   The amount will always contain one (1) dollar value and two (2) cent values separated by a period “.”.
Message 100 – character alphanumeric The response message indicating in details whether the transaction was Approved or Declined.
ErrorMessage alphanumeric (variable length) The error message indicating the message associated with the ErrorCode. Please refer to the full list of ErrorCodes and their corresponding ErrorMessage below.
ErrorCode 3 – character numeric The Error Code indicating the numeric value associated with the error.  Please refer to the full list of ErrorCodes and their corresponding ErrorMessage below.   Please make sure to use the named constant of the ErrorCodes enum as opposed to its integer value.  This will ensure a smooth transition of code should you need to update to a newer version of the API.  
AppPreferredName 16 – character alphanumeric The Application Preferred Name is the name of the hard application in the cardholder's local language and should be displayed to the cardholder during Application Selection. Although this is the preferred name to be displayed to the cardholder, it will not always be possible to do so as the name may use an 'issuer code table' that is not supported by the terminal. The Application Preferred Name should be printed as received.
AppLabel                   16 – character alphanumeric The Application Label contains only characters in the common character set that all EMV-capable terminals are required to support. This should ensure that there will always be a name that can be displayed to the cardholder. The Application Label should be printed as received.
CardPlan 16 – character alphanumeric The CardPlan is printed if neither the Application Preferred name nor the Application Label is available. E.g. Visa, MasterCard etc.  
Aid 32 – character alphanumeric The Application Identifier (Aid) field is a data label that identifies an application on the card or terminal. The Aid is used to determine which applications are supported as both the card and the terminal must support the same Aid to initiate a transaction.
TSI 4 ASCII hexadecimal   Indicates the functions performed in a transaction Receipt Requirement: If TSI is presented in the receipt, append TSI value after TvrARQC.
CvmIndicator 2 – character alphanumeric The Cardholder Verification Method (CVM) field. EMV transactions with successful PIN entry will include the phrase “VERIFIED BY PIN) on the merchant copy.  EMV transactions with unsuccessful PIN entry will include a signature line on the merchant copy rather than “VERIFIED BY PIN”. A signature line will also print if the initial CVM is Signature (returns “S”). Both “VERIFIED BY PIN” and a signature line will be included if the CVM is PIN & Signature (returns “B”). If the CVM indicator is returned with an empty response, a signature line is required for face-to-face transactions.  
ServiceCode 3 - character numeric Indicates the type of card within the track2 fields on the customer’s card.
PanEntry 1 – character alphanumeric   The PAN entry mode characters (S, M, C, F, G, T, H, or Q). On the transaction receipt a “Pan Entry” field must be displayed.
Entry mode Definition
S (swiped) The card is swiped, and, The card, as determined by the service code and bin range, is not a supported chip card, and, The swipe is not the result of fallback
M (manual entry) The card is manually entered, and, The card is manually entered, and, The manual entry is not the result of fallback          
C (chip transaction) The card is inserted, and, The card, as determined by its aids, is a supported chip card, and, The transaction completes as an approved or declined EMV transaction or “non-EMV transaction using EMV functionality
F (fallback to swipe) The card is swiped at the fallback prompt, and, The card, as determined by the service code and bin range, is a supported chip card
G (fallback to manual entry) The card is manually entered at the fallback prompt, and, The card, as determined by a credit bin range, is a supported chip credit card.
T (contactless tab non EMV) Card is tapped and is a contactless MSD card
H (EMV contactless) Card is tapped and is a contactless EMV card

Q (chip card malfunction)

The message “Chip card malfunction” must be displayed; it must be in a smaller type face than the approved or declined response message. Please note that if the response code indicates that the transaction is approved, the approval is still valid despite the “malfunction”. When pan entry value is “Q” the swipe indicator should be printed as “C” on the receipt.

ARQC 16 – character alphanumeric   The Authorization Request Cryptogram (ARQC) is used for an Online Card Authentication process. This field is generated by the card for transactions that require online authorization. The issuer validates the ARQC to ensure the authenticity of the card.
TvrARQC 10 – character alphanumeric   To determine if it is safe for the merchant to approve the stand-in transaction, the values of the flags in the EMV Terminal Verification Results (TVR) must be examined to ensure that no unsafe conditions arose during the transaction. The transaction should be declined if checking of the TVR flags indicates an unsafe transaction.
TCACC 16 – character alphanumeric   Transaction Certificate (TC) and Application Authentication Cryptogram (ACC) are cryptograms generated by the card at the end of all offline and online approved transactions. Both provide information about the actual steps and processes executed by the card terminal and merchant during a given transaction and can be used during dispute processing.
TvrTCACC 10 – character alphanumeric The final Terminal Verification Results (TVR).

Error Codes

Error Code Number

ErrorMessage

0

“No Error.”

108

“Problem connecting to Gateway.”

2

“Transaction Cancelled.”

109

“Gateway could not process request”

4

“Initialization Required.”

123

“Transaction not completed.”