Moneris Gateway Guide

Moneris fact sheet

Quick Start

New to integrating Moneris with Spreedly? Here's your setup guide:

Retrieve your Moneris credentials
1. Contact the Moneris support team to obtain API credentials
Get familiar with the Spreedly API
1. Review Spreedly API basics
2. Understand the core concepts: Gateways, Payment Methods, and Transactions
Add Moneris gateway to Spreedly in sandbox mode

📘
Review this documentation to understand more about how to test transactions.

Additional notes

Additional notes
Visa and Mastercard cards retained with Spreedly are subject to Stored Credentials regulations. Some merchant accounts require an additional parameter to send CVV. Set `cvv_enabled` when creating the gateway if your account requires CVV to be passed. Moneris’s legacy eSelect Plus API requires a unique `order_id` for every purchase or pre-authorization. To safely retry after a timeout, resend the identical request with the same `order_id` and payload, and set `status_check` to `true`. Moneris supports the `general_credit` transaction type for processing credit transactions without a prior purchase reference.

Visa and Mastercard cards retained with Spreedly are subject to Stored Credentials regulations.

Some merchant accounts require an additional parameter to send CVV. Set cvv_enabled when creating the gateway if your account requires CVV to be passed.

Moneris’s legacy eSelect Plus API requires a unique order_id for every purchase or pre-authorization. To safely retry after a timeout, resend the identical request with the same order_id and payload, and set status_check to true.

Moneris supports the general_credit transaction type for processing credit transactions without a prior purchase reference.

Adding a Moneris gateway

Required Credentials

store_id: Your Moneris Store ID
api_token: Your Moneris API Token

Optional Gateway Settings

cvv_enabled: Set true if your Moneris account requires CVV to be passed. Set false to never send CVV. If omitted, the value remains nil.
avs_enabled: Set true to enable AVS checking for accounts configured for AVS.

REQUEST

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
  <gateway_type>moneris</gateway_type>
  <store_id>your_store_id</store_id>
  <api_token>your_api_token</api_token>
</gateway>'

RESPONSE

<gateway>
  <token>3piqSh8nzBCYkjeim91QUVGrxyz</token>
  <gateway_type>moneris</gateway_type>
  <name>Moneris</name>
  <description nil="true"/>
  <merchant_profile_key nil="true"/>
  <sub_merchant_key nil="true"/>
  <store_id>your_store_id</store_id>
  <characteristics>
    <supports_purchase type="boolean">true</supports_purchase>
    <supports_authorize type="boolean">true</supports_authorize>
    <supports_capture type="boolean">true</supports_capture>
    <supports_partial_capture type="boolean">true</supports_partial_capture>
    <supports_credit type="boolean">true</supports_credit>
    <supports_partial_credit type="boolean">true</supports_partial_credit>
    <supports_general_credit type="boolean">true</supports_general_credit>
    <supports_void type="boolean">true</supports_void>
    <supports_adjust type="boolean">false</supports_adjust>
    <supports_verify type="boolean">true</supports_verify>
    <supports_3dsecure_2_mpi_purchase type="boolean">true</supports_3dsecure_2_mpi_purchase>
    <supports_3dsecure_2_mpi_authorize type="boolean">true</supports_3dsecure_2_mpi_authorize>
    <supports_store type="boolean">true</supports_store>
    <supports_remove type="boolean">true</supports_remove>
    <supports_fraud_review type="boolean">false</supports_fraud_review>
    <supports_network_tokenization type="boolean">true</supports_network_tokenization>
    <supports_stored_credentials type="boolean">true</supports_stored_credentials>
  </characteristics>
  <credentials>
    <credential>
      <name>store_id</name>
      <value>your_store_id</value>
    </credential>
  </credentials>
  <gateway_settings>
    <cvv_enabled nil="true"/>
    <avs_enabled nil="true"/>
  </gateway_settings>
  <gateway_specific_fields>
    <gateway_specific_field>issuer_id</gateway_specific_field>
    <gateway_specific_field>payment_indicator</gateway_specific_field>
    <gateway_specific_field>payment_information</gateway_specific_field>
    <gateway_specific_field>cust_id</gateway_specific_field>
    <gateway_specific_field>crypt_type</gateway_specific_field>
    <gateway_specific_field>note</gateway_specific_field>
    <gateway_specific_field>dynamic_descriptor</gateway_specific_field>
    <gateway_specific_field>status_check</gateway_specific_field>
    <gateway_specific_field>ship_indicator</gateway_specific_field>
  </gateway_specific_fields>
  <payment_methods>
    <payment_method>credit_card</payment_method>
    <payment_method>apple_pay</payment_method>
    <payment_method>google_pay</payment_method>
    <payment_method>third_party_token</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <sandbox type="boolean">true</sandbox>
</gateway>

Sending CVV

Some Moneris accounts do not allow a CVV unless cvv_enabled is set to true.

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>moneris</gateway_type>
        <store_id>MyStoreId</store_id>
        <api_token>MyApiToken</api_token>
        <cvv_enabled>true</cvv_enabled>
      </gateway>'

<gateway>
  <token>T625Ln9dox07cH2pKghIEjeOxyz</token>
  <gateway_type>moneris</gateway_type>
  <name>Moneris</name>
  <description nil="true"/>
  <merchant_profile_key nil="true"/>
  <sub_merchant_key nil="true"/>
  <store_id>MyStoreId</store_id>
  <characteristics>
    <supports_purchase type="boolean">true</supports_purchase>
    <supports_authorize type="boolean">true</supports_authorize>
    <supports_capture type="boolean">true</supports_capture>
    <supports_credit type="boolean">true</supports_credit>
    <supports_general_credit type="boolean">false</supports_general_credit>
    <supports_void type="boolean">true</supports_void>
    <supports_adjust type="boolean">false</supports_adjust>
    <supports_verify type="boolean">true</supports_verify>
    <supports_reference_purchase type="boolean">false</supports_reference_purchase>
    <supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
    <supports_offsite_purchase type="boolean">false</supports_offsite_purchase>
    <supports_offsite_authorize type="boolean">false</supports_offsite_authorize>
    <supports_offsite_synchronous_purchase type="boolean">false</supports_offsite_synchronous_purchase>
    <supports_offsite_synchronous_authorize type="boolean">false</supports_offsite_synchronous_authorize>
    <supports_3dsecure_purchase type="boolean">false</supports_3dsecure_purchase>
    <supports_3dsecure_authorize type="boolean">false</supports_3dsecure_authorize>
    <supports_3dsecure_2_mpi_purchase type="boolean">true</supports_3dsecure_2_mpi_purchase>
    <supports_3dsecure_2_mpi_authorize type="boolean">true</supports_3dsecure_2_mpi_authorize>
    <supports_store type="boolean">false</supports_store>
    <supports_remove type="boolean">false</supports_remove>
    <supports_fraud_review type="boolean">false</supports_fraud_review>
    <supports_network_tokenization type="boolean">false</supports_network_tokenization>
    <supports_inquire_by_gateway_transaction_id type="boolean">false</supports_inquire_by_gateway_transaction_id>
    <supports_inquire_by_order_id type="boolean">false</supports_inquire_by_order_id>
    <supports_transaction_retry type="boolean">false</supports_transaction_retry>
    <supports_stored_stored_credentials type="boolean">false</supports_stored_stored_credentials>
    <supports_stored_credentials type="boolean">true</supports_stored_credentials>
  </characteristics>
  <credentials>
    <credential>
      <name>store_id</name>
      <value>MyStoreId</value>
    </credential>
  </credentials>
  <gateway_settings>
    <cvv_enabled nil="true"/>
    <avs_enabled>true</avs_enabled>
  </gateway_settings>
  <gateway_specific_fields>
    <gateway_specific_field>issuer_id</gateway_specific_field>
    <gateway_specific_field>payment_indicator</gateway_specific_field>
    <gateway_specific_field>payment_information</gateway_specific_field>
    <gateway_specific_field>crypt_type</gateway_specific_field>
    <gateway_specific_field>note</gateway_specific_field>
    <gateway_specific_field>ship_indicator</gateway_specific_field>
  </gateway_specific_fields>
  <payment_methods>
    <payment_method>credit_card</payment_method>
    <payment_method>apple_pay</payment_method>
    <payment_method>google_pay</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <sandbox type="boolean">false</sandbox>
  <mode>default</mode>
  <created_at type="dateTime">2023-06-06T17:11:12Z</created_at>
  <updated_at type="dateTime">2023-06-06T17:11:12Z</updated_at>
</gateway>

Turning on AVS

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>moneris</gateway_type>
        <store_id>MyStoreId</store_id>
        <api_token>MyApiToken</api_token>
        <avs_enabled>true</avs_enabled>
      </gateway>'

<gateway>
  <token>T625Ln9dox07cH2pKghIEjeOxyz</token>
  <gateway_type>moneris</gateway_type>
  <name>Moneris</name>
  <description nil="true"/>
  <merchant_profile_key nil="true"/>
  <sub_merchant_key nil="true"/>
  <store_id>MyStoreId</store_id>
  <characteristics>
    <supports_purchase type="boolean">true</supports_purchase>
    <supports_authorize type="boolean">true</supports_authorize>
    <supports_capture type="boolean">true</supports_capture>
    <supports_credit type="boolean">true</supports_credit>
    <supports_general_credit type="boolean">false</supports_general_credit>
    <supports_void type="boolean">true</supports_void>
    <supports_adjust type="boolean">false</supports_adjust>
    <supports_verify type="boolean">true</supports_verify>
    <supports_reference_purchase type="boolean">false</supports_reference_purchase>
    <supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
    <supports_offsite_purchase type="boolean">false</supports_offsite_purchase>
    <supports_offsite_authorize type="boolean">false</supports_offsite_authorize>
    <supports_offsite_synchronous_purchase type="boolean">false</supports_offsite_synchronous_purchase>
    <supports_offsite_synchronous_authorize type="boolean">false</supports_offsite_synchronous_authorize>
    <supports_3dsecure_purchase type="boolean">false</supports_3dsecure_purchase>
    <supports_3dsecure_authorize type="boolean">false</supports_3dsecure_authorize>
    <supports_3dsecure_2_mpi_purchase type="boolean">true</supports_3dsecure_2_mpi_purchase>
    <supports_3dsecure_2_mpi_authorize type="boolean">true</supports_3dsecure_2_mpi_authorize>
    <supports_store type="boolean">false</supports_store>
    <supports_remove type="boolean">false</supports_remove>
    <supports_fraud_review type="boolean">false</supports_fraud_review>
    <supports_network_tokenization type="boolean">false</supports_network_tokenization>
    <supports_inquire_by_gateway_transaction_id type="boolean">false</supports_inquire_by_gateway_transaction_id>
    <supports_inquire_by_order_id type="boolean">false</supports_inquire_by_order_id>
    <supports_transaction_retry type="boolean">false</supports_transaction_retry>
    <supports_stored_stored_credentials type="boolean">false</supports_stored_stored_credentials>
    <supports_stored_credentials type="boolean">true</supports_stored_credentials>
  </characteristics>
  <credentials>
    <credential>
      <name>store_id</name>
      <value>MyStoreId</value>
    </credential>
  </credentials>
  <gateway_settings>
    <cvv_enabled nil="true"/>
    <avs_enabled>true</avs_enabled>
  </gateway_settings>
  <gateway_specific_fields>
    <gateway_specific_field>issuer_id</gateway_specific_field>
    <gateway_specific_field>payment_indicator</gateway_specific_field>
    <gateway_specific_field>payment_information</gateway_specific_field>
    <gateway_specific_field>crypt_type</gateway_specific_field>
    <gateway_specific_field>note</gateway_specific_field>
    <gateway_specific_field>ship_indicator</gateway_specific_field>
  </gateway_specific_fields>
  <payment_methods>
    <payment_method>credit_card</payment_method>
    <payment_method>apple_pay</payment_method>
    <payment_method>google_pay</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <sandbox type="boolean">false</sandbox>
  <mode>default</mode>
  <created_at type="dateTime">2023-06-06T17:11:12Z</created_at>
  <updated_at type="dateTime">2023-06-06T17:11:12Z</updated_at>
</gateway>

Purchase

curl https://core.spreedly.com/v1/gateways/[gateway_token]/purchase.json \
-u 'EnvironmentKey:AccessSecret' \
-H "Content-Type: application/json" \
-d '{
  "transaction": {
    "payment_method_token": "payment_method_token",
    "amount": 1000,
    "currency_code": "CAD",
    "retain_on_success": true
  }
}'

General Credit

Moneris supports the general_credit transaction type, allowing credit transactions to be processed without a prior purchase or authorization reference.

curl https://core.spreedly.com/v1/gateways/[gateway_token]/general_credit.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>payment_method_token</payment_method_token>
        <amount>1000</amount>
        <currency_code>CAD</currency_code>
      </transaction>'

The general_credit request is mapped to the corresponding Moneris API operation. A successful transaction returns the expected response fields including transaction ID, status, and response code.

Partial Capture and Partial Refund

Moneris supports partial capture and partial refund. Pass an explicit amount on capture when the amount is less than the authorized total, or on credit/refund when the amount is less than the captured total. Multiple partial refunds are allowed as long as the cumulative refunded amount does not exceed the original captured amount.

For multi-capture of the same authorization, send ship_indicator on capture: P for partial captures and F for the final capture. See the trans_amount gateway specific response field for the partial captured amount.

curl https://core.spreedly.com/v1/transactions/[authorize_transaction_token]/capture.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <amount>500</amount>
        <currency_code>CAD</currency_code>
        <gateway_specific_fields>
          <moneris>
            <ship_indicator>P</ship_indicator>
          </moneris>
        </gateway_specific_fields>
      </transaction>'

Third-Party Vaulting (Store / Remove)

Moneris supports Spreedly store and remove, which create and delete a ThirdPartyToken payment method vaulted at Moneris using a data_key.

crypt_type: Optional on store. Moneris e-commerce indicator. When omitted, Moneris uses the gateway or account configuration.
note: Optional on store. A note associated with the vaulted profile.

Network Tokenization

Moneris accepts Spreedly network tokens. See Spreedly’s network tokenization guide for provisioning and payment flows.

3D Secure Global (3DS) authentication

Moneris supports Spreedly Global 3DS for purchase and authorize through third-party / MPI flows. Gateway-specific 3DS2 is not supported. Review Spreedly’s 3DS2 Global guide.

Gateway Specific Fields

<gateway_specific_fields>
  <moneris>
    <issuer_id>123</issuer_id>
    <payment_indicator>C</payment_indicator>
    <payment_information>0</payment_information>
    <cust_id>12345</cust_id>
    <ship_indicator>P</ship_indicator>
    <dynamic_descriptor>ORDER123</dynamic_descriptor>
    <status_check>true</status_check>
    <crypt_type>7</crypt_type>
    <note>vault note</note>
  </moneris>
</gateway_specific_fields>

issuer_id, payment_indicator, and payment_information: Stored credential overrides.
cust_id: Optional customer identifier sent to Moneris.
ship_indicator: Required for multi-capture of the same authorization. Use P for a partial capture and F for the final capture.
dynamic_descriptor: Optional per-transaction billing descriptor up to 20 alphanumeric characters. Moneris enforces that business name + / + descriptor cannot exceed 22 characters.
status_check: Set to true when retrying an identical timed-out purchase or pre-authorization with the same order_id.
crypt_type and note: Primarily used with store and vaulting operations.

Field Name	Type	Required	Use Case (Description)	Example Value
issuer_id	String	No	Stored credentials or network transaction identifier override. Send an empty string to receive `issuer_id` back in the response.	123
payment_indicator	String	No	Overrides Spreedly stored credential mapping for the Moneris payment indicator.	C
payment_information	String	No	Overrides Spreedly stored credential mapping for the Moneris payment information value.	0
cust_id	String	No	Customer identifier forwarded to Moneris.	12345
ship_indicator	String	No	Multi-capture indicator. Use `P` for partial and `F` for final. Required in multi-capture flows.	P
dynamic_descriptor	String	No	Per-transaction statement descriptor. Maximum 20 alphanumeric characters. Combined business name + `/` + descriptor must not exceed 22 characters in Moneris.	ORDER123
status_check	Boolean	No	Retry-after-timeout flag. Resubmit the identical request with `status_check=true` to retrieve the original result.	true
crypt_type	String	No	Moneris crypt type or e-commerce indicator, commonly used on store requests.	7
note	String	No	Optional note for store or vault requests.	vault note

Retrying after a timeout

Moneris’s legacy eSelect Plus API requires a unique order_id for every purchase or pre-authorization. Reusing an order_id by itself is not a safe retry strategy. If a request times out, resend the identical request with the same order_id, the same payload, and status_check set to true. Moneris returns the original transaction outcome instead of processing a new charge. This behavior is intended for retry-after-timeout only and should not be treated as general-purpose idempotency.

Gateway Specific Response Fields

<gateway_specific_response_fields>
  <moneris>
    <issuer_id>123</issuer_id>
    <auth_code>12AB12AB</auth_code>
    <trans_amount>2.00</trans_amount>
    <status_code>...</status_code>
    <status_message>...</status_message>
  </moneris>
</gateway_specific_response_fields>

issuer_id: Used for stored credentials. Returned when the request sends issuer_id as an empty string.
auth_code: Authorization code returned by Moneris.
trans_amount: Partial captured amount in multi-capture or partial capture flows.
status_code and status_message: Returned in status-check and retry flows.

Field Name	Type	Description
issuer_id	string	Issuer or network transaction identifier for stored credentials.
auth_code	string	Authorization code returned by Moneris.
trans_amount	string	Amount associated with a partial capture or completion.
status_code	string	Status code from Moneris status-check responses.
status_message	string	Status message from Moneris status-check responses.

Stored Credentials

Moneris supports Spreedly’s first-class stored credential fields. For authorize or purchase requests, include:

stored_credential_initiator

stored_credential_reason_type

You may override the default mapping with gateway specific fields issuer_id, payment_indicator, and payment_information. Each override applies independently.

Stored credential mapping

When required by your flow, provide issuer_id from the original transaction so Moneris can associate the subsequent transaction with the original credential storage event.

Spreedly field combination	Moneris payment_indicator	Moneris payment_information	Notes
Cardholder initiated + first	C	0	Initial customer-initiated transaction.
Merchant initiated + recurring	R	2	Recurring merchant-initiated follow-up transaction.
Merchant initiated + installment	R	1	Installment merchant-initiated follow-up transaction.
Merchant initiated + unscheduled	U	2	Unscheduled credential-on-file use.

📘
Learn more about how Spreedly enables use of stored credentials by reviewing our Stored Credentials guide

Additional resources

📘
If you need support with this gateway, please contact Support at [email protected].

📘
Moneris documentation: http://eselectplus.moneris.com
Production API: https://www3.moneris.com/gateway2/servlet/MpgRequest
Test API: https://esqa.moneris.com/gateway2/servlet/MpgRequest