My Profile_


Introduction

This documentation contains the instructions for integrating Apple Pay as an in-app purchase option using the Moneris Gateway iOS API for Canada. It contains specifications for transaction requests and responses.

Please ensure to also review the Integrating Apple Pay section to use this SDK.

System and Skill Requirements

  1. XCode 6.3 or higher
  2. Knowledge of Objective C
  3. iOS 8.0 or higher

    Essential Integration Tasks

    • In order to create an Apple Pay Merchant ID and obtain a Merchant certificate please review the Integrating Apple Pay section for instructions on setting up the certificate for use with this SDK.
    • Configurations and settings of Xcode in order for the code to compile:
      • Enable Apple Pay in Xcode by selecting designated project -> Capabilities pane -> Enable Apple Pay & in-App purchase -> Select the Merchant Id
    • To configure the payment sheet with additional information please refer to https://developer.apple.com/apple-pay/.
      • Apple Pay displays a payment sheet with the contact information, shipping, and payment related information to the customer before the customer authorizes the payment for processing.
    • The ‘buy with apple pay’ button can also be configured using the PassKit Framework Reference.

    Function Types

    Moneris Gateway's Apple Pay API supports the following types of transactions ApplePayTokenPreauth and ApplePayTokenPurchase.

    For any non-Apple Pay follow-on transaction please refer to the Moneris standard set of APIs. Below are the list of all the supported transactions in conjunction with any extra features such as Customer information, AVS information, CVD information and Recurring billing.

    Function Type Description Class Name | Parameters
    Financial Transactions
    AppleTokenPurchase The Purchase transaction verifies funds on the customer’s card, removes the funds and readies them for deposit into the merchant’s account. @interface ApplePayTokenPurchase

    NSString *orderId,
    PKPayment *payment
    AppleTokenPreauth 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. @interface ApplePayTokenPreauth

    NSString *orderId,
    PKPayment *payment
    Optional Methods
    Customer Information Customer details such as shipping, taxes etc can be sent with a financial transactions such as AppleTokenPurchase and AppleTokenPreauth. (void)setCustInfoWithPayment

    NSString *shippingAddress, NSString *instructions , NSString *shippingCost, NSString *tax1, NSString *tax2, NSString *tax3
    Recurring Billing Information Recurring Billing is feature which allows for a transaction information to be sent once and then rebilled on a specified interval for a certain number of times. (void)setRecur

    NSString *recurUnit, NSString *startNow, NSString *startDate, NSString *numRecurs, NSString *period, NSString *recurAmount
    CVD Information       Card validation digits (CVD) information can be passed with the Financial Transaction to be verified for a particular transaction.      (void)setCvdInfo

    NSString *cvdIndicator,
    NSString *cvdValue
    AVS Information Address Verification information can be passed with the Financial Transaction to be verified for a particular transaction   (void)setAvsInfo

    NSString *streetNumber,
    NSString *streetName,
    NSString *zipCode

    Test the Solution

    Test Credentials:

    To request a personal account be setup for Apple Pay testing please sign up for a Developer Portal profile and request an account on the preferences tab.

    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
    MpgRequest *req = [MpgRequest mpgRequestWithStoreId:@"moneris" ApiToken:@"hurgle" Transaction:transaction];
    [req setTestMode:YES];
    [req setProcCountry:@"CA"];

    Test Cards:

    Unfortunately we are unable to provide test cards for use with Apple Pay QA processing.

    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.

    Getting Help

    For help with your integration please reach out to our eProducts team. If you are just starting out, please also engage our Client Integrations team. Contact details are found in How Do I Get Help?

    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 Test Mode to NO. You will also be required to change the store Id and API Token.

    Production Development
    Canada MpgRequest*req=[MpgRequest mpgRequestWithStoreId:@"xxxxxx"ApiToken:@"xxxxx" Transaction:transaction];
    [req setTestMode:NO];
    [req setProcCountry:@"CA"];
    initWithHost:@"www3.moneris.com"
    MpgRequest*req=[MpgRequest mpgRequestWithStoreId:@"moneris"ApiToken:@"hurgle" Transaction:transaction];
    [req setTestMode:YES];
    [req setProcCountry:@"CA"];
    initWithHost:@"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 Gateway 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.

    MpgTransactionRequest 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

    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

    Mandatory Request Fields

    Variable Limits Description
    orderId   50 – character alphanumeric 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.  For a follow-on transaction (Refunds, Completions, and Purchase Corrections) the order_id must reference the original transaction.
    Amount 9 - decimal 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
    payment PassKit Payment Apple Pay payment object returned in the didAuthorizePayment method.  This is passed in the Apple Pay Purchase or Pre-authorization request.
     

    Optional AVS Request Fields

    The AVS information section is optional, but if included, all of the fields below are mandatory and must be populated, though they can be populated with a blank value.

    Variable Limits Description
    avs_street_number 19 – character alphanumeric Street Number & Street Name (max – 19 digit limit for street number and street name combined).  This must match the address that the issuing bank has on file.
    avs_street_name
    avs_zipcode 10 – character alphanumeric Zip or Postal Code – This must match what the issuing banks has on file.
     

    Optional CVD Request Fields

    The customer information section is optional, but if included, all of the fields below are mandatory and must be populated.

    Variable Limits Description
    cvd_value 4 – character numeric Credit Card CVD value – this number accommodates either 3 or 4 digit CVD values.   Note: The CVD value supplied by the cardholder should simply be passed to the Moneris Gateway.  Under no circumstances should it be stored for subsequent uses or displayed as part of the receipt information.
    cvd_indicator 1 – character numeric CVD presence indicator. Typically the value is 1. 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.

    Optional CustInfo Request Fields

    The customer information section is optional, but if included, all of the fields below are mandatory and must be populated, though they can be populated with a blank value.

    Shipping Information

    Field Name Size/Type Description
    first name 30-character alphanumeric Customer first name
    last name 30-character alphanumeric Customer last name
    company name 50-character alphanumeric Customer 's company name
    address 70-character alphanumeric Customer's address.  Not used for address verification.
    city 30-character alphanumeric Customer's city
    province 30-character alphanumeric Customer's province or state
    postal code 30-character alphanumeric Customer's postal or zip code
    country 30-character alphanumeric Customer's country
    phone 30-character alphanumeric Customer's phone number
    fax 30-character alphanumeric Customer's fax number
    tax1 10-character alphanumeric Federal tax amount. Amount is not used for calculating total amount.
    tax2 10-character alphanumeric Provincial or state tax amount. Amount is not used for calculating total amount.
    tax3 10-character alphanumeric County, local or specialty tax amount. Amount is not used for calculating total amount.
    shipping_cost 10-character alphanumeric Shipping cost. Amount is not used for calculating total amount.
    Extra Details  
    email 60-character alphanumeric Customer email address.
    instructions 100-character alphanumeric Instructions or notes.

    Optional Recurring Billing Fields

    The recurring billing section is optional, but if included, all of the fields below are mandatory and must be populated.

    Field Name Size/Type Description
    recur_unit day, week, month, eom The unit that you wish to use as a basis for the Interval.  This can be set as day, week, month or end of month.  Then using the “period” field you can configure how many days, weeks, months between billing cycles.  
    period numeric 1-999 This is the number of recur_units you wish to pass between billing cycles. Example : period = 45, recur_unit=day -> Card will be billed every 45 days. period = 4, recur_unit=weeks -> Card will be billed every 4 weeks. period = 3, recur_unit=month -> Card will be billed every 3 months. period = 3, recur_unit=eom -> Card will be billed every 3 months (on the last day of the month) Please note that the total duration of the recurring billing transaction should not exceed 5-10 years in the future.  
    start_date YYYY/MM/DD This is the date on which the first charge will be billed.  The value must be in the future.  It cannot be the day on which the transaction is being sent.  If the transaction is to be billed immediately the start_now feature must be set to true and the start_date should be set at the desired interval after today.  
    start_now true / false When a charge is to be made against the card immediately start_now should be set to ‘true’.  If the billing is to start in the future then this value is to be set to ‘false’.  When start_now is set to ‘true’ the amount to be billed immediately may differ from the recur amount billed on a regular basis thereafter.   
    recur_amount 9-character decimal 0.01-999999.99 Amount of the recurring transaction. This must contain 3 digits with two penny values. The minimum value passed can be 0.01 and the maximum 999999.99.  This is the amount that will be billed on the start_date and every interval thereafter.  
    num_recurs numeric 1-99 The number of times to recur the transaction.   
    amount 9-character decimal 0.01-999999.99 When start_now is set to ‘true’ the amount field in the transaction array becomes the amount to be billed immediately.  When start_now is set to ‘false’ the amount field in the transaction array should be the same as the recur_amount field.  

    Response Fields

    Variable Limits Description
    ReceiptId 50 – character alphanumeric  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.
    ReferenceNum 18 – character numeric This is a bank transaction reference number.  The entire reference number must be displayed on the receipt.  This information should also be stored by the merchant. The following illustrates the breakdown of this field where "660123450010690030” is the reference number returned in the message. Example: 660123450010690030
    • 66012345: Terminal ID
    • 001: Shift number
    • 069: Batch number
    • 003: Transaction number within the batch.
    Format: nnnnnnnnnnnnnnnnnn (18 digits)  
    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) Approved
    50 – 999 (inclusive) Declined
    null Incomplete


      Custom Apple Pay SDK Responses:
    ResponseCode Message Definition
    900 Global Error Unable to decrypt payload
      For a full list of response codes and the associated message please refer to the Financial Response Codes.
    ISO 2 – character numeric The ISO code is a bank issued response code.  The ISO code and the response code are used to determine the receipt message.
    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.
    TransTime ##:##:## Processing host time stamp. 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  
    TransDate YYYY-MM-DD Processing host date stamp. 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)  
    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  
    Complete true/false Transaction was sent to authorization host and a response was received
    Message 100 – character alphanumeric (variable length) Response description returned from issuing institution. The response message indicating in details whether the transaction was Approved or Declined.
    TransAmount 9 decimal (variable length) Returns the amount sent in request for processing. 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    
    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)  
    TxnNumber 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.
    TimedOut true/false Transaction failed due to a process timing out
    Ticket n/a reserved
    DeviceManufacturerIdentifier 12 – character alphanumeric Token requestor ID. Returned from decrypted payload. Hex-encoded device manufacturer identifier.
    CAVV 40 – character alphanumeric Decrypted CAVV value for the transaction. Returned for Apple Pay Purchase/Pre-Authorization transaction if payload is successfully decrypted.
    CorporateCard                    true/false Indicates whether the card is a corporate card or not
     RecurSucess true/false Indicates whether the transaction successfully registered.
     AvsResultCode 1 – character alphanumeric Indicates the address verification result: Please refer to the AVS Result Codes table for list of possible results.  
     CvdResultCode 2 – character alphanumeric The CVD response is an alphanumeric 2 byte variable. The first byte is the numeric CVD indicator; the second byte would be the response code. The CVD value is keyed on the PINpad when doing a manually keyed transaction.  Please refer to the CVD Result Codes table for list of possible results.
     IsVisaDebit true/false/null Indicates whether the card that the transaction was performed on is Visa debit.
    • true = Card is Visa Debit
    • false = Card is not Visa Debit
    • null = there was an error in identifying the card

    Error Messages

    Global Error Receipt – You are not connecting to our servers.  This can be caused by a firewall or your internet connection.  

    Response Code = NULL – The response code can be returned as null for a variety of reasons.   A majority of the time the explanation is contained within the Message field.   When a ‘NULL’ response is returned it can indicate that the Issuer, the credit card host, or the gateway is unavailable, either because they are offline or you are unable to connect to the internet.  A ‘NULL’ can also be returned when a transaction message is improperly formatted.

    Below are error messages that are returned in the Message field of the response.

    Message: XML Parse Error in Request: <System specific detail>
    Cause: For some reason an improper XML document was sent from the API to the servlet

    Message: XML Parse Error in Response: <System specific detail>
    Cause: For some reason an improper XML document was sent back from the servlet

    Message: Transaction Not Completed Timed Out
    Cause: Transaction times out before the host responds to the gateway

    Message: Request was not allowed at this time
    Cause: The host is disconnected

    Message: Could not establish connection with the gateway: <System specific detail>
    Cause: Gateway is not accepting transactions or server does not have proper access to internet

    Message: Input/Output Error: <System specific detail>
    Cause: Servlet is not running

    Message: The transaction was not sent to the host because of a duplicate order id
    Cause: Tried to use an order id which was already in use

    Message: The transaction was not sent to the host because of a duplicate order id
    Cause: Expiry Date was sent in the wrong format

    Custom Apple Pay SDK Responses:

    ResponseCode Message Definition
    900 Global Error Unable to decrypt payload

    Security Requirements

    It is important to note that all Merchants and Service Providers that store, process, or transmit cardholder data must comply with PCI DSS and the Card Association Compliance Programs. However, validation requirements vary by business and are contingent upon your "Merchant Level" or "Service Provider Level". Failure to comply with PCI DSS and the Card Association Compliance Programs 2.0 may result in a Merchant being subject to fines, fees or assessments and/or termination of processing services. Non-compliant solutions may prevent merchants boarding with Moneris Solutions.

    As a Moneris Solutions client or partner using this method of integration, your solution must demonstrate compliance to the Payment Card Industry Data Security Standard (PCI DSS) and/or the Payment Application Data Security Standard (PA DSS) 2.0. These standards are designed to help the cardholders and merchants in such ways as they ensure credit card numbers are encrypted when transmitted/stored in a database and that merchants have strong access control measures, logging, secure software updates, secure remote access and support.

    For further information on PCI DSS and PA DSS requirements, please visit http://www.pcisecuritystandards.org.

    For more information on how to get your application PCI-DSS compliant, please contact our Integration Specialists and download the PCI-DSS Implementation Guide.