The Moneris eCanada gateway
- Michael Kalnicki
- Sam Louk
This document only discusses the requirements for the Moneris product eSelectPlus.
Using the Moneris Canada gateway, we can currently support donations by Visa, Mastercard, American Express, and Diners cards. Transactions through the Moneris Canada gateway are always in Canadian dollars or US dollars, subject to what you have agreed and set up with Moneris. It is therefore not necessary to include a currency form field in your default supporter record, or on your donation pages. It is possible to take single and recurring payments through the same page by including the ‘Recurring payment’ field as a dropdown, radio button, or check box.
Before creating Moneris donation pages, you will need to have arranged your merchant account with Moneris.
Recurring payments are supported, but they are managed by the gateway. On page submission, Engaging Networks sends the amount and schedule details to the gateway. You will be unable to view, change, or stop the recurring payments details in Engaging Networks – you’ll need to do it in the gateway or use Moneris Vault.
Setting up the gateway
It is recommended that you create and keep two separate gateway records in your account, one for testing and one linked to your live gateway. Donation pages should be linked to a test gateway initially, and then switched to a live gateway before launch. To create each one:
Go to Hello YOURNAME > Account settings > Gateways
Click ‘New payment gateway’ to create a new entry
The fields for a live Moneris eSelect gateway are set up as follows:
Field | Description |
|---|---|
Reference name | A unique name for the gateway. It is a good idea for the name to include the type of gateway (e.g. Moneris Canada), and whether it is a live or test gateway. |
Select gateway | Select the Moneris Canada gateway. |
Store ID | This ID, along with the associated API Key, is obtained from Moneris. Details to use for a test gateway follow later in this document. |
API key | See above. |
Currency | This field determines the currency that will be recorded in the transactional data record in Engaging Networks – it is for reporting purposes and it does not allow you to change the currency accepted by the Moneris gateway. It should always be set to the currency you have set up with Moneris. |
Test mode | Should be checked for a test gateway, but must be unchecked for a gateway that will accept live donations. |
Form fields
The following fields should be set up in the default supporter record with the appropriate field ‘tag’ and added to your donation form.
Standard fields – required for every Moneris eSelect donation page
Field | Mandatory | Field type | Description |
|---|---|---|---|
Email address | Mandatory | Alphanumeric | Supporter’s email address. |
Donation amount | Mandatory | Numeric | May be entered as a whole number, or with two decimal places. E.g. Twelve dollars may be entered as ’12’ or ‘12.00’. You may want to consider using the ‘select with input’ or ‘radio with input’ field types – see below. |
Cardholder name | Mandatory | Alphanumeric | The name on the supporter’s card. |
First name | Mandatory | Alphanumeric | The supporter’s first name. |
Last name | Mandatory | Alphanumeric | The supporter’s last name. |
Address 1 | Mandatory | Alphanumeric | First line of the address of the card/account holder. This should be set up as a split text field, with building number in the first part and street name in the second part. (see below). Used in anti-fraud checks. |
Postal code | Mandatory | Alphanumeric | Canada post code. Used in anti-fraud checks. |
Moneris processes credit card payments, so you will also need these fields:
Field | Mandatory | Field type | Description |
|---|---|---|---|
Credit card number | Mandatory | Token | Credit card/debit account number w/o spaces |
Credit card verification value (CVV2 or CVC2) | Mandatory | Token | The additional card verification value printed on the card, used for fraud checks. No specific field format requirements. |
Credit card expiration | Mandatory | Date | Format must be MMYY. It is strongly recommended that you use the ‘split select’ field type for this form field. See below for details. Unlike some other gateways, Moneris does not require a ‘/’ between the month and year. |
Additional required fields for recurring payments
Recurring payments are supported, but they are managed by the gateway. On page submission, Engaging Networks sends the amount and schedule details to the gateway. You will be unable to view, change, or stop the recurring payments details in Engaging Networks – you’ll need to do it in the gateway or use Moneris Vault.
If you want to accept recurring payments and have confirmed with Moneris that you have this option enabled for your account, in addition to the credit card fields you will need to add the following:
Field type | Field type | Description |
|---|---|---|
Recurring payment | Alpha | Submitting ‘Y’ will flag the transaction as a recurring payment. Any other value will result in a single payment. |
Recurring frequency | Alpha | Must be ‘day’ ‘week’ or ‘month’ in lower case. This is used in combination with the recurring period to determine how often a payment is made. |
Recurring period | Numeric | This is the interval between payments, based on the recurring frequency. For example, if Recurring frequency = ‘month’ and Recurring period = ‘6’, the payments will be made every 6 months. If Recurring frequency = ‘week’ and Recurring period = ‘2’, the payment will be made every 2 weeks. *Recurring Period = ‘1’ will be every month.* |
Recurring count | Numeric | The number of payments to be made (at the specified interval) before the arrangement expires. *Should be 1 to 999. 1 would equal 1 more recurring donation after initial donation. 999 is approximately ‘ongoing’. |
Recurring start date | Date | Optional: A date to begin the payments, in the format YYYY/MM/DD. An initial payment of the recurring amount will be made right away, even if the start date is in the future. |
Note: The currency field is not required for Moneris and need not be included on donation pages – the currency for donations is defined when you set up your Moneris Canada gateway – either Canadian or US dollars.
Note: Unlike other gateways, Moneris Canada does not require users to specify their card type, because it will be derived from the card number.
Testing Moneris eSelect donation pages
In order to test Moneris donation pages, you will need to have set up a test gateway in your Engaging Networks account which uses a test Store Id and API key.
Valid details are shown below:
Store ID | API token | Username (for logging in only) | Password (for logging in only) |
|---|---|---|---|
store1 | yesguy | demouser | password |
store2 | yesguy | demouser | password |
store3 | yesguy | demouser | password |
store5 | yesguy | demouser | password |
Once your test configuration is set up and you have a donation page pointing to the test gateway, you can submit test transactions using the following details:
Credit/debit cards (Any expiry date in the future may be used, and you may use any CVV with the correct number of digits for the card)
Card type | Test card number |
|---|---|
Mastercard | 5454545454545454 |
Amex | 373599005095005 |
Visa | 4242424242424242 |
Diners | 36462462742008 |
Note: The test gateway will sometimes reject payments based on the donation amount for testing purposes. Use a value of 1 or 1.00 for testing to avoid errors that would not appear in a live gateway.
Note: You must not submit real credit card or bank account details to a test configuration – Moneris’s test merchant accounts are shared, and anyone with the test login details will be able to see transactions.
You can use this URL ‘https://esqa.moneris.com/mpg’ to log into the Moneris Test Environment, using the details from the above table corresponding to what you have used in your test gateway, to verify your test transactions in the ‘Reports’ section. You can match the transactions in the gateway to transactional data in the system with the ‘order ID’. This code should match the first part of the value of the column ‘campaign data 2’ when you do a transactional export of a donation page.
Managing recurring payments
Once a Moneris eSelect recurring payment has been initiated, it will only be possible to view the scheduled payment on an individual basis through your client dashboard.
The functionality is accessed through Data & Reports > Lookup supporter
Once you have loaded the relevant supporter, a list of the actions the supporter has taken part in will appear in the Recurring donations gadget.
Viewing the scheduled payment will allow you to see the donation amount, recurring date, recurring frequency and recurring status. You will not be able to change these details in the Engaging Networks system, because eSelect payments are managed within Moneris (unlike Moneris Vault and some other gateways).