The Moneris eVault gateway – Canada and US
- Michael Kalnicki
- Sam Louk
Moneris Canada: eSelect credit/debit card single payments
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.
Before setting up
Before creating Moneris donation pages, you will need to have arranged your merchant account with Moneris.
You will also need to decide what base URL you would like to use for your donation pages, and ensure that a certificate exists for it on our load balancer.
Setting up a 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 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. See section 6 below for details to use for a test gateway. |
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. |
Standard fields – required for every 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 used on the supporter’s card. |
First name | Mandatory | Alphanumeric | The supporter’s last 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) | Optional | 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. |
Note: That 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.
Note: It is strongly recommended that you apply validators for specific fields (e.g. numeric validator, date validator). The validators will need to be created in ‘Account defaults > Manage form validations’ and then applied to specific form fields in ‘Build > Form’. In particular, the donation amount validator must be in place to successfully validate your donation page.
Additional required fields for recurring payments
Note: Recurring payments are supported, and can be managed by using Lookup Supporter’s Recurring Donation gadget.
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 | 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 count | Numeric | The number of payments to be made (at the specified interval) before the arrangement expires. |
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. |
Testing donation pages
In order to test Moneris donation pages, you will need to have set up a test gateway in your Engaging Networks account that 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 value with the correct number of digits for the card)
Card type | Test 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 and make amendments.