The cl-moneris Reference Manual

Table of Contents

The cl-moneris Reference Manual

This is the cl-moneris Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Feb 19 19:53:13 2020 GMT+0.

1 Introduction

This is a Common Lisp library providing access to the Moneris payment
processing (http://www.moneris.com/) HTTPS POST API.

The basic use pattern is to create a merchant-token with your store's
information (API token, store ID, and the access URI you received from
Moneris), then call the 'process' function with the merchant-token and
a transaction (you can create transactions with the 'purchase,'
'correction,' and 'refund' functions provided - see their
documentation strings for details). 'process' returns multiple values:

txn-id           - transaction ID
code             - numeric response code
code-description - response code description
message          - message returned in response
response-xml     - parsed XML of response
response-string  - raw XML response string

response-xml contains all the information you need to generate a
client receipt/invoice; consult the Moneris API documentation
(https://www.eselectplus.ca/en/downloadable-content) to learn about
its format and fields.

The file test/moneris-test.lisp provides examples using the Moneris
API test server.

cl-moneris was originally authored by Wade Humeniuk. It was converted
and released by Vladimir Sedach 

cl-moneris is available under the ISC (BSD) license, except for the
unit tests, which are released into the public domain.

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 cl-moneris

Maintainer

Vladimir Sedach <vsedach@gmail.com>

License

ISC

Description

An interface to the Moneris payment processing service (HTTP).

Dependencies

• s-xml
• drakma

Source

cl-moneris.asd (file)

Components

• package.lisp (file)
• response-codes.lisp (file)
• moneris.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 cl-moneris.asd

Location

cl-moneris.asd

Systems

cl-moneris (system)

3.1.2 cl-moneris/package.lisp

Parent

cl-moneris (system)

Location

package.lisp

Packages

cl-moneris

3.1.3 cl-moneris/response-codes.lisp

Dependency

package.lisp (file)

Parent

cl-moneris (system)

Location

response-codes.lisp

Internal Definitions

• *response-codes* (special variable)
• is-error-code? (function)
• response-code-description (function)

3.1.4 cl-moneris/moneris.lisp

Dependency

response-codes.lisp (file)

Parent

cl-moneris (system)

Location

moneris.lisp

Exported Definitions

• code (method)
• (setf code) (method)
• code-description (method)
• (setf code-description) (method)
• correction (function)
• http-body (method)
• (setf http-body) (method)
• http-code (method)
• (setf http-code) (method)
• http-headers (method)
• (setf http-headers) (method)
• merchant-token (class)
• message (method)
• (setf message) (method)
• moneris-error (condition)
• moneris-post-error (condition)
• moneris-transaction-error (condition)
• parsed-xml (method)
• (setf parsed-xml) (method)
• process (function)
• purchase (function)
• raw-xml (method)
• (setf raw-xml) (method)
• reason-phrase (method)
• (setf reason-phrase) (method)
• refund (function)

Internal Definitions

• api-token (method)
• lispify-response (function)
• moneris-uri (method)
• store-id (method)

4 Packages

Packages are listed by definition order.

4.1 cl-moneris

Source

package.lisp (file)

Use List

• s-xml
• drakma
• common-lisp

Exported Definitions

• code (generic function)
• code (method)
• (setf code) (method)
• (setf code) (generic function)
• code-description (generic function)
• code-description (method)
• (setf code-description) (method)
• (setf code-description) (generic function)
• correction (function)
• http-body (generic function)
• http-body (method)
• (setf http-body) (method)
• (setf http-body) (generic function)
• http-code (generic function)
• http-code (method)
• (setf http-code) (method)
• (setf http-code) (generic function)
• http-headers (generic function)
• http-headers (method)
• (setf http-headers) (method)
• (setf http-headers) (generic function)
• merchant-token (class)
• message (generic function)
• message (method)
• (setf message) (method)
• (setf message) (generic function)
• moneris-error (condition)
• moneris-post-error (condition)
• moneris-transaction-error (condition)
• parsed-xml (generic function)
• parsed-xml (method)
• (setf parsed-xml) (method)
• (setf parsed-xml) (generic function)
• process (function)
• purchase (function)
• raw-xml (generic function)
• raw-xml (method)
• (setf raw-xml) (method)
• (setf raw-xml) (generic function)
• reason-phrase (generic function)
• reason-phrase (method)
• (setf reason-phrase) (method)
• (setf reason-phrase) (generic function)
• refund (function)

Internal Definitions

• *response-codes* (special variable)
• api-token (generic function)
• api-token (method)
• is-error-code? (function)
• lispify-response (function)
• moneris-uri (generic function)
• moneris-uri (method)
• response-code-description (function)
• store-id (generic function)
• store-id (method)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Functions

Function: correction &key ORDER-ID TXN-ID CRYPT-TYPE

Generate a transaction to void a same-day purchase. No purchase will appear on the customer’s credit card.

Description of input parameters:

order-id (string, 50 chars max, alphanumeric)
Merchant defined unique transaction identifier - must reference a
previously processed purchase transaction order-id.

txn-id (string, 255 chars max, alphanumeric)
This must be the value returned as the Txn_number in the
response to the original purchase.

crypt-type (string, 1 char, alphanumeric)
E-Commerce Indicator:
1 - Mail Order/Telephone Order - Single
2 - Mail Order/Telephone Order - Recurring
3 - Mail Order Telephone Order - Instalment
4 - Mail Order Telephone Order - Unknown Classification
5 - Authenticated E-commerce Transaction (VBV)
6 - Non Authenticated Ecommerce Transaction (VBV)
7 - SSL enabled merchant
8 - Non Secure Transaction (Web or Email Based)
9 - SET Non Authenticated transaction

Package

cl-moneris

Source

moneris.lisp (file)

Function: process MERCHANT-TOKEN TRANSACTION

Send a ’purchase’, ’correction’, or ’refund’ transaction for processing to Moneris merchant account specified by merchant-token.

If the Moneris mpg server returns an HTTP status code other than 200, raises a moneris-post-error

If transaction is declined, raises a moneris-transaction-error

If transaction is successfuly processed, returns (as multiple values):
txn-id - transaction ID
code - numeric response code
code-description - response code description
message - message returned in response
response-xml - parsed XML of response
response-string - raw XML response string

Package

cl-moneris

Source

moneris.lisp (file)

Function: purchase &key ORDER-ID CUST-ID AMOUNT PAN EXPDATE CRYPT-TYPE

Generate a purchase transaction for processing.

Description of input parameters:

order-id (string, 50 chars max, alphanumeric)
Merchant defined unique transaction identifier - must be uniquely generated by caller for every Purchase.

amount (string, 9 chars max, decimal)
Amount of the transaction. This must contain 3 digits with two penny values. The minimum value passed can be 0.01 and the maximum 9999999.99

pan (string, 20 chars max, numeric)
Credit Card Number - no spaces or dashes. Most credit card numbers today are 16 digits in length but some 13 digits are still accepted by some issuers. This field has been intentionally expanded to 20 digits in consideration for future expansion and/or potential support of private label card ranges.

expdate (string, 4 chars, numeric)
Expiry Date - format YYMM no spaces or slashes. PLEASE NOTE THAT THIS IS REVERSED FROM THE DATE DISPLAYED ON THE PHYSICAL CARD WHICH IS MMYY

cust-id (string, 50 chars max, alphanumeric)
This is an optional field that can be sent as part of a Purchase or PreAuth request. It is searchable in the Moneris Merchant Resource Centre. It is commonly used for policy number, membership number, student ID or invoice number.

Package

cl-moneris

Source

moneris.lisp (file)

Function: refund &key ORDER-ID TXN-ID AMOUNT CRYPT-TYPE

Generate a transaction to refund a purchase.

order-id (string, 50 chars max, alphanumeric)
Merchant defined unique transaction identifier. For Independent Refund attempts, must be uniquely generated by caller. For refunds of previous purchases, must reference a previously processed purchase transaction order-id.

txn-id (string, 255 chars max, alphanumeric)
Used when performing follow on transactions - this must be the value returned as the Txn_number in the response to the original purchase.

amount (string, 9 chars max, decimal)
Amount of the transaction. This must contain 3 digits with two penny values. The minimum value passed can be 0.01 and the maximum 9999999.99

crypt-type (string, 1 char, alphanumeric)
E-Commerce Indicator:
1 - Mail Order/Telephone Order - Single
2 - Mail Order/Telephone Order - Recurring
3 - Mail Order Telephone Order - Instalment
4 - Mail Order Telephone Order - Unknown Classification
5 - Authenticated E-commerce Transaction (VBV)
6 - Non Authenticated Ecommerce Transaction (VBV)
7 - SSL enabled merchant
8 - Non Secure Transaction (Web or Email Based)
9 - SET Non Authenticated transaction

Package

cl-moneris

Source

moneris.lisp (file)

5.1.2 Generic functions

Generic Function: code CONDITION

Generic Function: (setf code) NEW-VALUE CONDITION

Package

cl-moneris

Methods

Method: code (CONDITION moneris-transaction-error)

Method: (setf code) NEW-VALUE (CONDITION moneris-transaction-error)

Source

moneris.lisp (file)

Generic Function: code-description CONDITION

Generic Function: (setf code-description) NEW-VALUE CONDITION

Package

cl-moneris

Methods

Method: code-description (CONDITION moneris-transaction-error)

Method: (setf code-description) NEW-VALUE (CONDITION moneris-transaction-error)

Source

moneris.lisp (file)

Generic Function: http-body CONDITION

Generic Function: (setf http-body) NEW-VALUE CONDITION

Package

cl-moneris

Methods

Method: http-body (CONDITION moneris-post-error)

Method: (setf http-body) NEW-VALUE (CONDITION moneris-post-error)

Source

moneris.lisp (file)

Generic Function: http-code CONDITION

Generic Function: (setf http-code) NEW-VALUE CONDITION

Package

cl-moneris

Methods

Method: http-code (CONDITION moneris-post-error)

Method: (setf http-code) NEW-VALUE (CONDITION moneris-post-error)

Source

moneris.lisp (file)

Generic Function: http-headers CONDITION

Generic Function: (setf http-headers) NEW-VALUE CONDITION

Package

cl-moneris

Methods

Method: http-headers (CONDITION moneris-post-error)

Method: (setf http-headers) NEW-VALUE (CONDITION moneris-post-error)

Source

moneris.lisp (file)

Generic Function: message CONDITION

Generic Function: (setf message) NEW-VALUE CONDITION

Package

cl-moneris

Methods

Method: message (CONDITION moneris-transaction-error)

Method: (setf message) NEW-VALUE (CONDITION moneris-transaction-error)

Source

moneris.lisp (file)

Generic Function: parsed-xml CONDITION

Generic Function: (setf parsed-xml) NEW-VALUE CONDITION

Package

cl-moneris

Methods

Method: parsed-xml (CONDITION moneris-transaction-error)

Method: (setf parsed-xml) NEW-VALUE (CONDITION moneris-transaction-error)

Source

moneris.lisp (file)

Generic Function: raw-xml CONDITION

Generic Function: (setf raw-xml) NEW-VALUE CONDITION

Package

cl-moneris

Methods

Method: raw-xml (CONDITION moneris-transaction-error)

Method: (setf raw-xml) NEW-VALUE (CONDITION moneris-transaction-error)

Source

moneris.lisp (file)

Generic Function: reason-phrase CONDITION

Generic Function: (setf reason-phrase) NEW-VALUE CONDITION

Package

cl-moneris

Methods

Method: reason-phrase (CONDITION moneris-post-error)

Method: (setf reason-phrase) NEW-VALUE (CONDITION moneris-post-error)

Source

moneris.lisp (file)

5.1.3 Conditions

Condition: moneris-error ()

Superclass of network errors or
transaction-declined conditions. Handle this when you don’t care why your transaction failed to process.

Package

cl-moneris

Source

moneris.lisp (file)

Direct superclasses

error (condition)

Direct subclasses

• moneris-post-error (condition)
• moneris-transaction-error (condition)

Condition: moneris-post-error ()

Condition raised due to network error

Package

cl-moneris

Source

moneris.lisp (file)

Direct superclasses

moneris-error (condition)

Direct methods

• reason-phrase (method)
• reason-phrase (method)
• http-body (method)
• http-body (method)
• http-headers (method)
• http-headers (method)
• http-code (method)
• http-code (method)

Direct slots

Slot: http-code

Initargs

:http-code

Readers

http-code (generic function)

Writers

(setf http-code) (generic function)

Slot: http-headers

Initargs

:http-headers

Readers

http-headers (generic function)

Writers

(setf http-headers) (generic function)

Slot: http-body

Initargs

:http-body

Readers

http-body (generic function)

Writers

(setf http-body) (generic function)

Slot: reason-phrase

Reason phrase from HTTP header status line

Initargs

:reason-phrase

Readers

reason-phrase (generic function)

Writers

(setf reason-phrase) (generic function)

Condition: moneris-transaction-error ()

Condition raised when transaction is declined

Package

cl-moneris

Source

moneris.lisp (file)

Direct superclasses

moneris-error (condition)

Direct methods

• parsed-xml (method)
• parsed-xml (method)
• raw-xml (method)
• raw-xml (method)
• message (method)
• message (method)
• code-description (method)
• code-description (method)
• code (method)
• code (method)

Direct slots

Slot: code

Numeric Moneris response code

Initargs

:code

Readers

code (generic function)

Writers

(setf code) (generic function)

Slot: code-description

Text description of Moneris response code

Initargs

:code-description

Readers

code-description (generic function)

Writers

(setf code-description) (generic function)

Slot: message

Message returned by Moneris

Initargs

:message

Readers

message (generic function)

Writers

(setf message) (generic function)

Slot: raw-xml

XML string returned by Moneris

Initargs

:raw-xml

Readers

raw-xml (generic function)

Writers

(setf raw-xml) (generic function)

Slot: parsed-xml

Parsed XML returned by Moneris

Initargs

:parsed-xml

Readers

parsed-xml (generic function)

Writers

(setf parsed-xml) (generic function)

5.1.4 Classes

Class: merchant-token ()

Merchant-token objects specify your unique Moneris store information.

Package

cl-moneris

Source

moneris.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• store-id (method)
• api-token (method)
• moneris-uri (method)

Direct slots

Slot: moneris-uri

Full URI of the Moneris Server e.g. https://moneris.com/mpg

Initargs

:moneris-uri

Readers

moneris-uri (generic function)

Slot: api-token

Your api token issued during Moneris store creation.

Initargs

:api-token

Readers

api-token (generic function)

Slot: store-id

Your store-id issued during Moneris store creation.

Initargs

:store-id

Readers

store-id (generic function)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *response-codes*

Package

cl-moneris

Source

response-codes.lisp (file)

5.2.2 Functions

Function: is-error-code? CODE

Package

cl-moneris

Source

response-codes.lisp (file)

Function: lispify-response S-XML-RESPONSE

Package

cl-moneris

Source

moneris.lisp (file)

Function: response-code-description CODE

Package

cl-moneris

Source

response-codes.lisp (file)

5.2.3 Generic functions

Generic Function: api-token OBJECT

Package

cl-moneris

Methods

Method: api-token (MERCHANT-TOKEN merchant-token)

Your api token issued during Moneris store creation.

Source

moneris.lisp (file)

Generic Function: moneris-uri OBJECT

Package

cl-moneris

Methods

Method: moneris-uri (MERCHANT-TOKEN merchant-token)

Full URI of the Moneris Server e.g. https://moneris.com/mpg

Source

moneris.lisp (file)

Generic Function: store-id OBJECT

Package

cl-moneris

Methods

Method: store-id (MERCHANT-TOKEN merchant-token)

Your store-id issued during Moneris store creation.

Source

moneris.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types