SupportBlog
Guides

Moneris REST gateway guide

Moneris fact sheet

Quick Start

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

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

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

Additional notes

Required credentials: client_id, client_secret, and merchant_id.

Endpoints: Test https://api.sb.moneris.io · Live https://api.moneris.io.

API version: 2025-08-14 (sent as the Api-Version header).

Region / country: North America, Canada (CA).

Default currency: CAD; amounts are sent in cents.

Supported card brands: Visa, Mastercard, American Express, Diners Club, Discover.

Supported payment methods: credit card, third-party token (Moneris Vault), Apple Pay, Google Pay.

purchase sends automaticCapture = true; authorize sends automaticCapture = false.

Capture completes an authorization via POST /payments/{id}/complete and supports partial capture (amount) and finalCompletion (via the final_completion gateway specific field).

Void cancels an authorization/purchase via POST /payments/{id}/cancel and accepts an optional reason.

Refund (credit) and general credit (unreferenced refund) post to /refunds; partial refunds are supported.

Verify performs a 0-amount validation via /validations (the card is not stored: storePaymentMethod = DO_NOT_STORE).

Store / Remove vault a card via /validations and delete it via DELETE /payment-methods/{id}.

Inquire re-syncs a transaction's status via inquire_by_gateway_transaction_id

Apple Pay / Google Pay are supported as decrypted wallet payloads (device token + 3DS cryptogram, or PAN_ONLY for Google Pay).

Adding a Moneris REST Gateway

REQUEST

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
  <gateway_type>moneris_rest</gateway_type>
  <client_id>your_client_id</client_id>
  <client_secret>your_client_secret</client_secret>
  <merchant_id>your_merchant_id</merchant_id>
</gateway>'

RESPONSE

<gateway>
    <token>XXXXXXXXXXXXXXXXXXXXXXXXXX</token>
    <gateway_type>moneris_rest</gateway_type>
    <name>Moneris REST</name>
    <description nil="true"/>
    <merchant_id>your_merchant_id</merchant_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_verify type="boolean">true</supports_verify>
        <supports_store type="boolean">true</supports_store>
        <supports_remove type="boolean">true</supports_remove>
        <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_inquire_by_gateway_transaction_id type="boolean">true</supports_inquire_by_gateway_transaction_id>
    </characteristics>
    <credentials>
        <credential>
            <name>client_id</name>
            <value>your_client_id</value>
        </credential>
        <credential>
            <name>merchant_id</name>
            <value>your_merchant_id</value>
        </credential>
    </credentials>
    <gateway_specific_fields>
        <gateway_specific_field>idempotency_key</gateway_specific_field>
        <gateway_specific_field>invoice_number</gateway_specific_field>
        <gateway_specific_field>dynamic_descriptor</gateway_specific_field>
        <gateway_specific_field>ecommerce_indicator</gateway_specific_field>
        <gateway_specific_field>cust_id</gateway_specific_field>
        <gateway_specific_field>reason</gateway_specific_field>
        <gateway_specific_field>store_payment_method</gateway_specific_field>
        <gateway_specific_field>payment_indicator</gateway_specific_field>
        <gateway_specific_field>payment_information</gateway_specific_field>
        <gateway_specific_field>network_transaction_id</gateway_specific_field>
        <gateway_specific_field>wallet_indicator</gateway_specific_field>
        <gateway_specific_field>final_completion</gateway_specific_field>
    </gateway_specific_fields>
    <payment_methods>
        <payment_method>credit_card</payment_method>
        <payment_method>third_party_token</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">true</sandbox>
</gateway>

Required Credentials

client_id: OAuth2 client id for the client-credentials grant.
client_secret: OAuth2 client secret (stored encrypted).
merchant_id: Your Moneris merchant id, sent as the X-Merchant-Id header on every request.

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",
    "order_id": "ABC123",
    "retain_on_success": true,
    "gateway_specific_fields": {
      "moneris_rest": {
        "cust_id": "test1234",
        "invoice_number": "INV001"
      }
    }
  }
}'
📘

Note

order_id is mapped to Moneris's orderId. amount is sent in cents under amount.amount with amount.currency = CAD.

Gateway Specific Fields

<gateway_specific_fields>
  <moneris_rest>
    <gateway_specific_field>idempotency_key</gateway_specific_field>
    <gateway_specific_field>invoice_number</gateway_specific_field>
    <gateway_specific_field>dynamic_descriptor</gateway_specific_field>
    <gateway_specific_field>ecommerce_indicator</gateway_specific_field>
    <gateway_specific_field>cust_id</gateway_specific_field>
    <gateway_specific_field>reason</gateway_specific_field>
    <gateway_specific_field>store_payment_method</gateway_specific_field>
    <gateway_specific_field>payment_indicator</gateway_specific_field>
    <gateway_specific_field>payment_information</gateway_specific_field>
    <gateway_specific_field>network_transaction_id</gateway_specific_field>
    <gateway_specific_field>wallet_indicator</gateway_specific_field>
    <gateway_specific_field>final_completion</gateway_specific_field>
  </moneris_rest>
</gateway_specific_fields>
  • payment_indicator / payment_information / network_transaction_id: credential-on-file fields, used together to chain a stored credential (see Stored Credentials (via Gateway Specific Fields)). Only forwarded when transacting against a stored (vault) token.
  • store_payment_method: controls how the card is vaulted on a store (defaults to MERCHANT_INITIATED).
  • idempotency_key: safe-retry key; Spreedly auto-generates one when omitted.
  • wallet_indicator: Apple Pay / Google Pay channel (IN_APPLICATION or IN_BROWSER).
  • final_completion: on a partial capture, marks the final capture of a multi-capture authorization (finalCompletion).

The Moneris request field each maps to is shown in parentheses.

Field NameTypeRequiredApplies ToDescriptionExample Value
idempotency_keyStringNoAllMerchant-supplied idempotency key (idempotencyKey). Spreedly auto-generates one when omitted.abc-123
invoice_numberStringNoPurchase, Authorize, CaptureMerchant invoice number (invoiceNumber).INV001
dynamic_descriptorStringNoPurchase, Authorize, VerifyDescriptor shown on the cardholder statement (dynamicDescriptor).Booking1
ecommerce_indicatorStringNoPurchase, Authorize, VerifyE-commerce indicator enum (ecommerceIndicator), e.g. SSL_MERCHANT. For 3DS transactions Spreedly derives this automatically.SSL_MERCHANT
cust_idStringNoPurchase, Authorize, StoreMerchant customer id (customerId).test1234
reasonStringNoVoid, Refund, CreditReason code for the operation (reason), typically used on void/refund.CUSTOMER_CANCELLATION
store_payment_methodStringNoStoreVault storage intent (paymentMethod.storePaymentMethod); defaults to MERCHANT_INITIATED.CARDHOLDER_INITIATED
payment_indicatorStringNoAllCredential-on-file indicator (credentialOnFileInformation.paymentIndicator), e.g. MERCHANT_INITIATED, UNSCHEDULED_CREDENTIAL_ON_FILE.MERCHANT_INITIATED
payment_informationStringNoAllCredential-on-file sequence (credentialOnFileInformation.paymentInformation), e.g. FIRST, SUBSEQUENT.SUBSEQUENT
network_transaction_idStringNoAllNetwork transaction id / issuer id from the initial credential-on-file transaction (credentialOnFileInformation.issuerId).306224132220497
wallet_indicatorStringNoApple Pay / Google PayWallet channel (walletIndicator): IN_APPLICATION or IN_BROWSER (default IN_BROWSER).IN_BROWSER
final_completionBooleanNoCaptureMarks the final capture of a multi-capture authorization (finalCompletion).true

Gateway Specific Response Fields

<gateway_specific_response_fields>
  <moneris_rest>
    <auth_code>180294</auth_code>
    <response_code>027</response_code>
    <network_transaction_id>306224132220000</network_transaction_id>
  </moneris_rest>
</gateway_specific_response_fields>
  • auth_code: issuer authorization code returned on an approved transaction.
  • response_code: issuer / host response code.
  • network_transaction_id: store this value and pass it back as the network_transaction_id gateway specific field on subsequent credential-on-file transactions.
Field NameTypeDescriptionExample Value
auth_codestringIssuer authorization code (transactionDetails.authorizationCode).180294
response_codestringIssuer / host response code (transactionDetails.responseCode).027
network_transaction_idstringNetwork transaction id (credentialOnFileResponse.issuerId) to store and reuse for subsequent credential-on-file transactions.306224132220497
📘

Note

Spreedly's gateway_transaction_id is the Moneris paymentId / refundId / validationId / stored paymentMethodId returned on the response (authorization).

Stored Credentials (via Gateway Specific Fields)

📘

Moneris REST does not use Spreedly's first-class stored credential fields (stored_credential_initiator / stored_credential_reason_type). Credential-on-file (Card on File) is driven entirely by the gateway specific fields payment_indicator, payment_information, and network_transaction_id.

The typical flow is: store the card (cardholder-initiated), capture network_transaction_id from the store response, then send it back on subsequent merchant-initiated transactions against the stored payment method token.

ScenarioFields to send (gateway specific fields)
Initial - cardholder-initiated (store)store transaction; Spreedly applies paymentIndicator = UNSCHEDULED_CREDENTIAL_ON_FILE, paymentInformation = FIRST. Optionally set store_payment_method (e.g. CARDHOLDER_INITIATED).
Subsequent - merchant-initiatedTransact against the stored token with payment_indicator = MERCHANT_INITIATED, payment_information = SUBSEQUENT, network_transaction_id = <issuerId from the initial response>.
📘

Credential-on-file data is only forwarded when transacting against a stored payment method (a vault token).

Transaction Sync (Inquire)

Spreedly can re-query a transaction's current status at Moneris via inquire_by_gateway_transaction_id. Inquire is supported for purchase, authorize, refund (credit), and general_credit.

3DS2 (Global)

Moneris REST supports Spreedly 3DS2 Global for purchase and authorize (3dsecure_2_mpi_purchase / 3dsecure_2_mpi_authorize; implemented via MPI / externally-authenticated pass-through). Spreedly forwards the authentication result as Moneris's threeDSecureData object and maps the ECI to Moneris's ecommerceIndicator enum:

Spreedly 3DS fieldMoneris fieldExample Value
authentication_value (cavv)threeDSecureAuthenticationValueAAABCZIhcQAAAABZlyFxAAAAAAA
three_ds_versionthreeDSecureVersion2.2.0
three_ds_server_trans_idthreeDSecureServerTransactionId9f3a2b1c-4d5e-4f6a-8b7c-0d1e2f3a4b5c
directory_server_transaction_idthreeDSecureDirectoryServerTransactionIdf38e6948-5388-41a6-bca4-b49723c19437
ecommerce_indicator (eci)ecommerceIndicatorAUTHENTICATED_ECOMMERCE

ECI mapping: 2/02/5/05 -> AUTHENTICATED_ECOMMERCE; 1/01/6/06 -> NON_AUTHENTICATED_ECOMMERCE; otherwise SSL_MERCHANT.

Additional resources

📘

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

📘

Moneris Unified API Developer Portal: https://developer.moneris.com/

Homepage: https://www.moneris.com/

API Endpoint (Production): https://api.moneris.io

API Endpoint (Test/Sandbox): https://api.sb.moneris.io

API Version: 2025-08-14 (Api-Version header)

Updated about 2 hours ago

Did this page help you?