21 June 2007

Moneris API

by mo


The purpose of this document is to describe how to use the Moneris API in a .NET application written in C# to process credit card transactions. Further information on the Moneris API can be found at:

The Moneris .NET API is a wrapper to the HTTPS post to their site. Instead of having to embed hidden input fields on and HTML page, the API allows users to post directly to the page via C#. The way the data is transported to Moneris is the same as a direct post from the client using hidden input fields.

E.g. Direct Post

With a direct post the data is transmitted directly from the client browser to Moneris.

<input id="storeID" type="hidden" name="ps_store_id" value=""/>
<input id="hppKey" type="hidden" name="hpp_key" value=""/>
<input id="chargeTotal" type="hidden" name="charge_total" />


With the .NET API the client data is transmitted to our application, then we send the data to Moneris and a response back to the client. The client has no knowledge the payment was processed through Moneris.

HttpsPostRequest request = new HttpsPostRequest( host, storeId, apiToken, new Purchase(orderId,customerId,amount,pan,expiryDate,crypt));
Receipt receipt = request.GetReceipt();


Because the data is transmitted to us before being processed by Moneris we need an SSL certificate. When a customer is processing a payment, the data is sent to us through an encrypted channel which is then transported to Moneris for authorization through another encrypted channel.

Transaction Types

There are several different types of credit card transactions that we can process using the Moneris API. This document will focus on the Purchase transaction.

  • Purchase: Verifies funds are available on customers card and removes them.
  • Pre Authorization: Verifies that funds are available on the customer card then locks those funds.
  • Capture: Retrieves the captured funds that are locked on a customers card. (This implies that a Pre Auth for the capture amount has already been committed.)
  • Void: Will void a purchase or capture transaction on the day of the transaction.
  • Refund: Will return funds from a Purchase or Capture transaction. ( Can be any amount of the transaction.)
  • Batch Close: Closes all transactions so that all Purchase, Capture and Refund transactions will be credited or debited on the following business day.

API Types

To process a purchase transaction, I will focus on 3 key types from the API.

  • HttpsPostRequest: Used to send a request to Moneris and retrieve a response
  • Purchase: Type of transaction to process
  • Receipt: The response from Moneris.


This type is used to transport transaction information to Moneris through an SSL connection. Once the response stream is returned it is sent to the Receipt constructor where a reference to that stream is contained as a private data member. (This seems inefficient to store the stream rather than to immediately parse out the data from the stream then close it.)

The following call will connect to Moneris, process the transaction, and retrieve a receipt object which contains the details of the response from Moneris.

new HttpsPostRequest(order.Host, order.StoreId, order.Token, transaction).GetReceipt();


The purchase type is specialization of the base type Transaction. It contains the information necessary for Moneris to process the transaction.

It can be constructed like this:

  new Purchase( order.OrderId, order.Amount.ToString( "F" ), order.CardNumber, order.ExpirationDate, Indicator.SslEnabledMerchant);


This type contains the response from Moneris after a transaction has been processed. It can be retrieved by calling the “GetReceipt()” method on the HttpsPostRequest object.

  new HttpsPostRequest(order.Host, order.StoreId, order.Token, transaction).GetReceipt();

These 3 objects allow a user to process a transaction through the Moneris store. It is up to the user of the API to enforce validation, and transparency between the client and Moneris.

I was able to quickly process sample transactions through the Moneris test store.

The .NET API wrapper is very easy to use but there is some behavior that isn’t intuitive. For example, when you construct an instance of the HttpsPostRequest object, this immediately fires of a request to Moneris in the constructor. This is shown from a capture of the code viewed through Reflector.

public HttpsPostRequest(string host, string store, string apiTok, Transaction t)
  this.receiptObj = new Receipt();
  this.retry = false;
  this.storeId = store;
  this.apiToken = apiTok;
  this.transaction = t;
  this.url = "https://" + host + ":443/gateway2/servlet/MpgRequest";

Also, the type named “IDebitPurchase” suggests that it is an interface, however it is declared as a class.


Overall, the Moneris API is easy to use and allows the user to quickly process transactions, and seems to be a good solution for connecting to the Moneris store and processing transactions. The documentation provided with the API offers lots and lots of code samples, which is extremely helpful in learning and quickly understanding the API. There is also lots of other useful information such as the types of things that need to show up on a receipt.

Additional Notes/Observations

The API is very easy to use and it abstracts a lot of the tedious work for us.

The document attached with the API describes the response fields and tells the length of them but does not offer the actual values to be returned.

For example the card type is not specified. Through testing I found that the following return values are sent back for each card type, based on the card numbers supplied in the document.

Test Card Numbers:

  • Visa: 4242424242424242
  • MasterCard: 5454545454545454
  • American Express: 373599005095005
  • Diners Club: 36462462742008

  • Visa “V”
  • Master Card “M”
  • American Express “AX”
  • Diners “M”

I don’t know why the same value is getting returned for MasterCard and Diners, but the difference between the 2 transactions is that master cards have a 16 digit card number and Diners have a 14 digit card number.