My Profile_


Introduction

Introduction

This documentation contains the instructions for integrating Apple Pay on the Web using the Moneris Gateway. It contains specifications for transaction requests and responses.

System and Skill Requirements

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

For Apple Pay on the Web

  1. Safari browser on compatible Apple devices only
  2. Knowledge of Javascript

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.
  • Please refer to https://developer.apple.com/apple-pay/ for details.
  • 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.

Transaction Types

  • Moneris Gateway Apple Pay SDK supports the following transactions:
  • Apple Pay Token Purchase (AppleTokenPurchase)
  • Apple Pay Token Pre-Authorization (AppleTokenPreauth)

NOTE: INTERAC® e-Commerce transaction functionality is currently available only when processing a Purchase transaction.


In addition, the Moneris Gateway Apple Pay SDK also supports optional features, such as Customer Information and recurring transactions.


Once you have processed the initial transaction using AppleTokenPurchase or AppleTokenPreauth, you can use the Moneris Gateway standard API set available on the Developer Portal at https://developer.moneris.com


to process one of the following supplemental transactions:

Apple Pay Token Purchase

The Apple Pay Token Purchase transaction verifies funds on the customer’s card, removes the funds and readies them for deposit into the merchant’s account.

Required transaction objects – Apple Pay Token Purchase
Object Apple Pay On the Web
Order Id orderId:document.getElementById('order-id').value
ApplePayPaymentToken payment:event.payment

Apple Pay Token Pre-Authorization

The Apple Pay Token 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. A subsequent 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.

Required transaction objects – Apple Pay Token Purchase
Object Apple Pay On the Web
Order Id orderId:document.getElementById('order-id').value
ApplePayPaymentToken payment:event.payment

Integrating Your Demo App - Apple Pay on the Web

To build an Apple Pay on the Web demo app example, follow the steps at: https://developer.apple.com/library/content/samplecode/EmporiumWeb/Introduction/Intro.html

To integrate your demo payment application for Apple Pay on the Web with the Moneris Gateway, do the following:

  1. Go to Apple's developer portal to download the code for the EmporiumWeb app at:

    https://developer.apple.com/library/content/samplecode/EmporiumWeb/Introduction/Intro.html
  2. In the index.html file, add the following code in the head section: <script type="text/javascript" src="https://esqa.moneris.com/applepayjs/applepay-api.js"></script>"

  3. In the body of index.html, insert the following <div> to enable the library to communicate: <div id="moneris-apple-pay" store-id="store 1" merchantidentifier=" merchant.com.moneris.apwebtest1" display-name="your-display-name"></div>

In session.onpaymentauthorized, insert the following code:


/**
* Payment Authorization
* Here you receive the encrypted payment data. You would then send it
* on to your payment provider for processing, and return an appropriate
* status in session.completePayment()
*/
session.onpaymentauthorized = (event) => {
// Send payment for processing...
const payment = event.payment;
const paymentJson = JSON.stringify(payment);
const paymentPre = document.createElement("pre");
const respDiv = document.getElementById("resp");
const uiDiv = document.getElementById("apple-pay-ui");
paymentPre.innerText = paymentJson;
respDiv.appendChild(paymentPre);
uiDiv.classList.remove("visible");
uiDiv.classList.add("none");
const buttons = document.getElementsByClassName("apple-pay-button");
for (let button of buttons) {
button.classList.remove("visible");
}
var request = {
orderId:document.getElementById('order-id').value,
payment:event.payment
}
var transType = "purchase";
if (typeof(window.MonerisApplePay[transType]) === "function")
{ window.MonerisApplePay[transType](request, function(receipt) {
console.log(receipt);
if (receipt.receipt.ResponseCode && !isNaN(receipt.receipt.ResponseCode) && parseInt
(receipt.receipt.ResponseCode) < 50)
{ session.completePayment(ApplePaySession.STATUS_SUCCESS);
} else
{ session.completePayment(ApplePaySession.STATUS_FAILURE);
} updateReceipt(receipt);
printReceipt(receipt);
});
}
}

Testing Your Solution - Apple Pay on the Web

Test Credentials

For testing purposes, you can either use the pre-existing test stores, or you can create your own unique test store where you will only see your own transactions. If you want to use the pre-existing stores, use

Store Id API Token MRC Username MRC Password
store1 yesguy demouser password
store2 yesguy demouser password
store3 yesguy demouser password
store4 yesguy demouser password
store5 yesguy demouser password

Configuring for testing– Apple Pay on the Web

  1. In the index.html file, change the code in the head section to: <script type="text/javascript" src=" https://esqa.moneris.com/applepayjs/applepay-api.js"></script>
  2. In the body of index.html, change the div to: <div id="moneris-apple-pay" store-id="store 1" merchant-identifier=" merchant.com.moneris.apwebtest1" display-name="your-displayname">

Getting a Production Store ID and API Token

In production, you use the Store ID that was given in your activation letter from Moneris. You obtain the production API token from the production Merchant Resource Center.

NOTE: The API token method is not used in the Apple Pay on the Web solution. To get your production API token:

  1. If you have not already done so, activate your production account at https://www.moneris.com/activate
  2. The activation process provides you with your first administrator user for the Merchant Resource Center.
  3. Once activated, log in to the production Merchant Resource Center at https://www3.moneris.com/mpg
  4. Select the Admin menu and choose

Configuring for Production – Apple Pay on the Web

  1. In the index.html file, change the code in the head section to: <script type="text/javascript" src=" https://www3.moneris.com/applepayjs/applepay-api.js"></script>

  2. In the body of index.html, change the div to: <div id="moneris-apple-pay" store-id="store 1" merchant-identifier=" merchant.com.moneris.apwebtest1" display-name="your-displayname"></ div>

Security Requirements


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 3.2 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) 3.2. 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 www.pcisecuritystandards.org.
For more information on how to get your application PCI-DSS compliant, please contact our Integration

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 10 - 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 9999999.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 10-character decimal 0.01-9999999.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