My Profile_


Introduction

This documentation contains the basic information for using the Moneris Card Present iOS 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. XCode 5.1 or higher
  2. Knowledge of Objective C
  3. Moneris test iCMP PINpad & test cards

    Merchant Payment Application Request Flow

    Below is a diagram with explanations about the interaction between the merchant’s payment application and the Terminal iOS library.

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

    Function Types

    Moneris 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 Type 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
    (void)initialization
    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.   (void)Batchclose
    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. (void)purchase

    NSString order_id, NSString amount, NSString cc_num, NSString cc_exp, NSString track2, NSString cust_id, NSString ecom, NSString 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. (void)preauth

    NSString order_id, NSString amount, NSString cc_num, NSString cc_exp, NSString track2, NSString cust_id, NSString ecom, NSString card_type
    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.   (void)Completion

    NSString order_id, NSString txn_no, NSString amount, NSString cc_num, NSString cc_exp, NSString track2, NSString ecom, NSString card_type
    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.   (void)purchaseCorrection

    NSString order_id, NSString amount, NSString cc_num, NSString cc_exp, NSString track2, NSString auth_code, NSString ecom, NSString card_type
    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. (void)refund

    NSString order_id, NSString amount, NSString cc_num, NSString cc_exp, NSString track2, NSString auth_code, NSString ecom, NSString card_type
    Delegate Methods
    Receipt Ready A call-back function defined to be called up when the PINpad is ready to send the response of an administrative or a financial transaction back to the merchant application. The PINpad will also pass along the response variables for the merchant application to generate the receipt.  Any tasks defined in this handler should only be used to strictly capture receipt response variables.  Other types of post-processing tasks such as writing to database, logging, or printing should be handled outside of this handler function.    (void)receiptReady
    Terminal Became Ready A call-back function defined to be called up whenever the PINpad is ready to process another transaction.  This function could be used to perform tasks such as database read/write, logging, printing receipts, or displaying error messages. (void)terminalBecameReady
    Terminal Became Busy A call-back function defined, when called the application interface should be disabled and should not be available for user input until the terminal becomes available.      (void)terminalBecameBusy
    Optional Delegate Methods
    pospadDid Connect A call-back function defined to be called when a PINpad is connected, this function could be used to notify the app if the PINpad is connected or not. (void)pospadDidConnect
    pospadDid
    Disconnect
    A call-back function defined to be called when a PINpad disconnects, this function could be used to notify the app if the PINpad did disconnect. (void)pospadDidDisconnect

    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 US
    self.terminal.storeId = “store_icmp“;
    self.terminal.apiToken =” icmpguy”
    self.terminal.eSelectHost = @"esqa.moneris.com";
    self.terminal.storeId = “cpi_icmp”;
    self.terminal.apiToken =” I9icmpguy”;
    self.terminal.eSelectHost = @"esqa.moneris.com";
    self.terminal.ecrNo = “”;

    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
    US esplus.moneris.com esplusqa.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

    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

    US

    esplus.moneris.com

    esplusqa.moneris.com

    NSString Host


    Request Fields

    Request Fields
    Variable Name Size/Type 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.
    pan 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.
    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 / num 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
    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.
    P – Debit
    V – Visa
    M – MasterCard
    AX – American Express
    DC – Diners
    NO – Discover/Novus
    C1 – Japan Credit Bureau

    Response Fields

    Variable

    Limits

    Description

    OrderId

    20 – character alphanumeric (a-zA-Z0-9)

    The order id specified in the request will be echoed back in the response.  This field is recommended to be displayed on the receipt for tracking and troubleshooting purposes.

    AuthCode

    8 – character alphanumeric (variable length)

    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 (variable length)

    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)

    Approved

    50 – 999 (inclusive)

    Declined

    null

    Incomplete

     

    For a full list of response codes and the associated message please refer to the Financial Response Codes.

    TransactionNo

    20 – character alphanumeric (variable length)

    The transaction number is an identifier used by 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 (variable length)

    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 (variable length)

    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 (Sale, Refund, . . . ).

                00 – Sale

                01 – Authorization (Credit Cards only)

                02 – Completion (Credit Cards only)

                04 – Refund / Independent Refund

                11 – Void

    AccountType

    2 – character alphanumeric (variable length)

    Account type defines the card type used and what type of account was used for a transaction.  See below for definitions. 

    0 – Default Account

    1 – Checking Account

    2 – Savings Account

    4 – Credit Card

    CardType

    2 – character alphanumeric (variable length)

    CardType defines the card type used for a transaction.  See below for definitions.  On the transaction receipt the Card Type field must be displayed as “Account” and 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 (variable length)

    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 (variable length)

    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 “.”.

    N = always returned

    n = returned when required  

    Message

    100 – character alphanumeric (variable length)

    The response message indicating in details whether the transaction was Approved or Declined.

    ErrorMessage

    string (variable length)

    The error message indicating the message associated with the ErrorCode. Please refer to the full list of ErrorCode and their corresponding ErrorMessage below.

    ErrorCode

    3 – character numeric (variable length)

    The Error Code indicating the numeric value associated with the error.  Please refer to the full list of ErrorCode 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 (variable length)

    The Application Preferred Name is the name of the card 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 (variable length)

    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 (variable length)

    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 (variable length)

    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 (variable length)

    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 with the exception of PanEntry = T. 

    ServiceCode

    3 – character numeric (variable length)

    Indicates the type of card within the track2 fields on the customer’s card.

    PanEntry

    1 – character alphabetical

    The PAN entry mode characters (S, M, C, F, G, T, or H).  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

    ARQC

    16 – character alphanumeric (variable length)

    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 (variable length)

    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 (variable length)

    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 (variable length)

    The final Terminal Verification Results (TVR). 


    Error Codes

    Error Code Number

    ErrorCode

    ErrorMessage

    0

    NoError

    “No Error.”

    1

    BadSwipe

    “Bad Card Swipe.”

    2

    Cancelled

    “Transaction Cancelled.”

    3

    NoSped

    “Sped is not connected.”

    4

    SpedAlreadyConnected

    “Sped is already connected.”

    5

    UnverifiedAmount

    “Amount not verified.”

    6

    NoSessionKeys

    “No Session Keys.”

    7

    HostError

    “Host could not process request.”

    8

    BadRequest

    “Gateway could not process request.”

    9

    ResponseNotVerified

    “Message Authentication Failed on response.”

    10

    NetworkError

    “Problem connecting to Gateway.”

    11

    CardTypeMismatch

    "Card type mismatch."

    12

    UnknownError

    “Unknown Error”

    123

    “a” or  “PospadError”

    “Pospad Error Code:” (error number – refer to POSPAD Error Codes table below)

    Ex. “Pospad Error Code: 150”

    999

    Null

     

    POSPAD Error Codes

    POSPAD Error Number

    Description

    Comments

    150 / 151 / 160 / 613

    Transaction not allowed.

    PINpad requires KeyExchange method to be called to obtain the most up-to-date configuration. 

    52

    Response received, initialization requested.

    Initialization request while port is being used.

    99

    EMV card removed during user interaction.

    Insert EMV card and re-attempt transaction.

    101

    Invalid transaction request parameter such as Amount.

    This error code applies to all amount field types.

    103

    Invalid Track2 data.

    This error code also applies when the optional debit/credit indicator is invalid.

    152

    Refund Limit exceeded: Transaction not allowed.

    The amount used in the Refund transaction exceeded the refund limit for the card used.

    162

    PINpad is still processing last request.

    The merchant application sent a new transaction request or command, while another transaction/command has not yet completed.

    190

    A card swiped using an external MSR and should be using the PINpad instead. 

    This error code only applies when EMV is active in the PINpad configuration.  If not EMV, then cards with these service codes are to be processed normally.

    400

    The PINpad has timed out while waiting for the cardholder to respond to a displayed prompt.

    The transaction, in progress, is cancelled.
    The timers used vary, depending upon the particular prompt.  Not all prompts are timed.

    401

    The CANCEL key was pressed in response to a cardholder prompt on the PINPAD.

    The transaction, in progress, is cancelled.
    This error code only applies to the Moneris host transactions.  It is not issued when the CANCEL key is used for the PINPAD setup prompts.

    450

    One or more master keys have been corrupted.

    The PINPAD needs to be re-injected with new keys.

    620

    No stored MasterCard EMV data is available in PINPAD to be passed.