How to Create a Miva Merchant Payment Processing Module
Revision 1.0
This document and the software described by this document are copyright 2000 by Miva Merchant Corporation. All rights reserved. Use of the software described herein may only be done in accordance with the License Agreement provided with the software. This document may not be reproduced in full or partial form except for the purpose of using the software described herein in accordance with the License Agreement provided with the software. Information in this document is subject to change without notice. Companies, names and data used in the examples herein are fictitious unless otherwise noted.
Miva Merchant is s registered trademark of Miva Merchant Corporation. Miva Merchant Order, Miva Merchant, Miva Merchant Mia, Miva Merchant Empresa, the Miva Merchant "blades" logo, and the Miva Merchant Engine are trademarks of Miva Merchant Corporation. Windows is the registered trademark of Microsoft Corporation. All other trademarks are the property of their respective owners. This document was developed and produced in San Diego, CA, USA.
MIVA MERCHANT CORPORATION WILL NOT BE LIABLE FOR (A) ANY BUG, ERROR, OMISSION, DEFECT, DEFICIENCY, OR NONCONFORMITY IN MERCHANT OR THIS DOCUMENTATION; (B) IMPLIED MERCHANTIBILITY OF FITNESS FOR A PARTICULAR PURPOSE; (C) IMPLIED WARRANTY RELATING TO COURSE OF DEALING, OR USAGE OF TRADE OR ANY OTHER IMPLIED WARRANTY WHATSOEVER; (D) CLAIM OF INFRINGEMENT; (E) CLAIM IN TORT, WHETHER OR NOT ARISING IN WHOLE OR PART FROM MIVA CORPORATION'S FAULT, NEGLIGENCE, STRICT LIABILITY, OR PRODUCT LIABILITY, OR (F) CLAIM FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES, OR LOSS OF DATA, REVENUE, LICENSEES GOODWILL, OR USE. IN NO CASE SHALL MIVA MERCHANT CORPORATION'S LIABILITY EXCEED THE PRICE THAT LICENSEE PAID FOR MERCHANT.
MM1032-01, Rev. 1.0 (Miva Merchant version 3.0x)
How to Create a Miva Merchant Payment Processing Module
Contents
Introduction
A module is a file that contains MivaScript functions that are called by the core Miva Merchant program to accomplish a task. This document identifies the functions for the Miva Merchant Payment Processing Module.
A Payment Processing Module provides a method for Miva Merchant to receive payment for the offered products, for example:
- Check payment
- Manual credit card processing
- Real-time credit card processing
- Electronic funds transfer
In instances where an exchange of data between Miva Merchant and a payment processing vendor occurs, a communications link is required. This link is a commerce library or a CGI gateway. These communications links are discussed in this guide.
Preparation
Refer to the document, HOW TO Prepare to Create a Miva Merchant Module at http://www.miva.com/support/docs/api/ to review the steps in creating any module, including the phases of module development. Taking a little time up front, can save you time later. It includes the following phases:
- Planning
- Implementation
- Design
Required Functions
A set of functions are required for a Miva Merchant module. Certain API functions apply to all modules, some to a few, and others to the specific module type. Refer to the Miva Merchant Module Functions Reference Manual for a list and description of these required functions
Note: Different versions of Miva Merchant require different API Module functions.
Payment processing modules require:
- Functions for All Modules
- All modules must contain certain functions to adhere to the Miva Merchant API standards. These standards ensure that both the module and the store properly perform upgrades, installations, and other operations.
- Store Configuration Functions
- The store functions are required for any module that can be installed or uninstalled at the store level.
- Payment Module Functions
- In addition to the functions required for all modules and store modules, a payment processing module must contain certain functions. Refer to the section "Payment Module Functions" later in this guide or to the Miva Merchant Module Functions Reference Manual for a list and descriptions of the functions.
Communications Links to Payment Processor
In order for Miva Merchant to communicate with an outside vendor or entity, there must be a link between Miva Merchant and that entity. Many modules use a commerce library as the link, however, a CGI-gateway may also be used.
Commerce Library
A commerce library is an extension of the MivaScript language. It allows a MivaScript application to connect with another entity outside of its own environment to perform a commerce related task. It is the communication link between an outside vendor and a MivaScript application, such as your payment module. The commerce library also converts the vendor's variables to Miva Merchant's field names, and vice-versa. A commerce library is written in the C programming language.
The major steps to create a commerce library include:
- Define the data that must be sent to the payment processing vendor, as defined by that vendor.
- Define the data that will be returned from the payment processing vendor.
- When the commerce library is functioning correctly, create your Miva Merchant payment processing module.
The payment processing module takes input from the customer and exports it to the commerce library, receives the returned variables from the commerce library, and completes the transaction. The Miva Merchant Engine API provides commerce library functions for communicating and passing data between your payment module and the library, and between the commerce library and the payment processor.
Refer to the "MivaScript Commerce Library Reference Manual" to create your commerce library.
CGI-Gateway
The payment processing vendor can pass information through the CGI gateway and receive data back. When a commerce library is not used, you must take into account:
- Required Miva Merchant module functions for the CGI Gateway
- Whether or not a translation script will be needed
Required Payment Module Functions for the CGI Gateway
Two of the Payment Module functions apply when you use a CGI gateway instead of a commerce library:
- PaymentModule_Payment_URL
- This is the destination link for the payment page.
- PaymentModule_Payment_Hide_Additional_Fields
- Allows CGI gateways to output any additional hidden HTML fields that are required to pass state information to the CGI gateway payment processor.
Translation Script from Payment Processing Vendor to Miva Merchant
The field names the payment processing vendor uses may be different from the ones miva Merchant uses, therefore a script which converts them from the vendor's field names to Miva Merchant's field names (and vice-versa) must be used.
For example, upon returning data, the payment processing vendor may use the name "USER1" referring to the session_id, in which case a line like this must appear in your translation script:
<MvASSIGN NAME = "g.Session_ID" VALUE = "{ g.USER1 }"
Note: The translation script must be installed into the Merchant2 directory, and when the module is uninstalled, the translation script must be deleted.
Miva Merchant Translation Script Requirements
- Session id
- <MvASSIGN NAME = "g.Session_ID" VALUE = "{ g.VendorField1 }">
- Store code
- <MvASSIGN NAME = "g.Store_Code" VALUE = "{ g.VendorField2 }">
- Payment method
- <MvASSIGN NAME = "g.PaymentMethod" VALUE = "{ g.VendorField3 }">
- Action function
- <MvASSIGN NAME = "g.Action" VALUE = "AUTH">
- Screen function
- <MvASSIGN NAME = "g.Screen" VALUE = "INVC">
- MvDO
- <MvDO FILE = "merchant.mv">
Payment Module Functions
| Function |
Description |
Typical Use |
| PaymentModule_Payment_Methods |
Returns a list of the payment method(s) available to the module. The data is returned in the following format:
data:description[,data:description,-]
Reads the available payment methods from the database that lists the Payment Methods, and other information (such as a code or abbreviation for the payment method). Other payment module functions use the "data" element. |
Store's first payment page ("Pay With") |
| PaymentModule_Payment_URL |
Used for CGI gateways. Returns either the destination link for the payment page (if a CGI gateway), or NULL if not a CGI gateway. |
Store's Payment Information page |
| PaymentModule_Payment Description |
Receives the "data" element from PaymentModule_Payment_Methods. The element is used to access the database and read the record for a selected payment method.
Returns a textual description of a payment method that is used as a heading on the payment screen. |
Store's Payment Information page |
| PaymentModule_Payment_Message |
Returns an optional text message which is displayed before the payment fields on the payment page when an order is being placed. The text message may be a text string in the function, or it can use the "data" element from PaymentModule_Payment_Methods to read a stored message for a particular payment method.
This optional text message could be included in the Payment Configuration page for the Store Administrator to modify. |
Store's Payment Information page |
| PaymentModule_Payment_Hide_
Additional_Fields |
Receives the "data" element of the selected payment method from PaymentModule_Payment_Methods.
Allows CGI gateways to output any additional hidden HTML fields that the payment processing vendor requires. Generally not used for non-CGI gateway modules.
When a translation script is used, the returnlink value must point to the translation script. |
Store's Payment Information page |
| PaymentModule_Payment_Fields |
Receives the "data" element of the selected payment method from PaymentModule_Payment_Methods.
Returns a comma-separated list of field identifiers. The list takes the following format: id[,id,id,id-] (For example; cc-name, cc-num, cc-name, etc.) |
Store's Payment Information page. |
| PaymentModule_Payment_Prompt |
Receives the "data" element of the selected payment method from PaymentModule_Payment_Methods and the "field_id" identifier from the list returned by PaymentModule_Payment_Fields().
Returns the textual prompt for the corresponding field received from PaymentModule_Payment_Fields. (For example, "Name on Card," "Card Number" and "Expiration.") |
Store's Payment Information page |
| PaymentModule_Payment_Invalid |
Receives "data" element of the selected payment method from PaymentModule_Payment_Methods and the "field_id" identifier from the list returned by PaymentModule_Payment_Fields().
Returns a boolean value indicating whether invalid data was entered by the customer for the field specified by "field_id."
Returns a boolean value to indicate whether or not invalid data was entered for the field_id. |
Store's Payment Information page |
| PaymentModule_Payment_Field |
Receives "data" element of the selected payment method from PaymentModule_Payment_Methods and the "field_id" identifier from the list returned by PaymentModule_Payment_Fields().
Outputs the HTML code to display the field received from PaymentModule_Payment_Fields. |
Store's Payment Information page |
| PaymentModule_Payment_Validate |
Called to validate the user entry for the payment fields. Receives the "data" element of the selected payment method from PaymentModule_Payment_Methods. Returns 1 if all fields are valid, or 0 if a field is invalid. If a field is invalid, PaymentModule_Payment_Invalid is called for all fields to determine which field is invalid.
For example, can check for properly entered expiration data, required fields are not null, and too few or too many digits entered for a credit card number. |
Store's Payment Information page |
| PaymentModule_Report_Description |
Returns a textual description of the payment processing method (payment processing method or vendor). |
Batch/Process Order In Administrative Interface Batch Modules |
| PaymentModule_Report_Fields |
Receives the "data" element of the selected payment method from PaymentModule_Payment_Methods.
Returns a comma-separated list of field identifiers, which takes the following format: id[,id,id,id-]
The data for these fields could include the authorization data, such as authorization code, bank name, credit card number, etc. |
Batch Reporting in Administrative Interface
Batch Modules
|
| PaymentModule_Report_Label |
Receives the "field_id" element of the selected payment method from PaymentModule_Report_Fields.
Returns a value (text label) for the corresponding field_id. (For example: Name on Card, Expiration Date, etc.) |
Batch Reporting in Administrative Interface
Standard Report Processing
Batch Modules |
| PaymentModule_Report_Value |
Receives the "field_id" identifier from the list returned by PaymentModule_Payment_Fields().
Returns the value of the field identified by "field_id". |
Batch Reporting in Administrative Interface |
| PaymentModule_Manipulate_Shipping |
May be used to add an additional charge to shipping, based on the payment method. (For example, COD.) |
Store's Payment Information page |
| PaymentModule_Authorize |
Receives the "data" element of the selected payment method from PaymentModule_Payment_Methods and the total amount of the order and uses the information to authorize payment.
Typically used to verify payment when a call to the payment processing vendor will occur during order placement.
Returns 1 if successful, 0 on failure. |
Store's Payment Information page |
| PaymentModule_Process |
Processes the payment data. Called during order processing when the store administrator processes the order.
Typically used to verify payment after order placement (known as "post-authorization").
Returns 1 on success, 0 on failure. |
Order Processing in Administrative Interface
|
| PaymentModule_Order_Validate |
Called to validate fields when the update button is pressed on the Edit Order page.
Returns 1 if all fields are valid, or 0 if there are invalid fields. |
Edit Order page in Administrative Interface |
| PaymentModule_Order_Delete |
Deletes a specified order from the database. Called when an order is deleted by a Store Administrator. Typically used to clean up any module-specific records for the order.
Returns 1 on success, 0 on error. |
Edit Order page in Administrative Interface |
| PaymentModule_Order_Update |
Called when an order is updated. Typically used to update any module-specific records for the order.
Returns 1 on success, 0 on error. |
Edit Order page in Administrative Interface |
| PaymentModule_Order_Tabs |
Returns a tab list for the Edit Order screen. The tab list takes the following format: code:text[,code:text,code:text]
Codes must be unique across modules, so it is recommended that the codes somehow include the module code. |
Edit Order page in Administrative Interface |
| PaymentModule_Order_Content |
Called to display screens during order edit. Functionally similar to Module_Product_Content, Module_Category_Content, etc.
Receives the "tab" code of the currently displayed tab. Also receives the "load_fields" element as follows:
1 - Load fields from database 0 - Do not load fields
Must display or hide fields depending on the value of "tab." If "tab" equals the current payment method, display the fields. If "tab" does not equal the current payment method, hide fields (using the Input typde="hidden" function), so the selections can be maintained until the Store Administrator clicks the Update button. |
Edit Order page in Administrative Interface |
