MIVA Merchant 5 Module API Feature payment

What MIVA Says

Modules including this feature provide methods for MIVA Merchant stores to receive payment for the products offered. The methods could be from among the following:

* Check payment mailed before shipment

* COD

* Credit card processing manually

* Credit card processing in real time

* Electronic Funds Transfer (ETF) for total of purchase

Required function: PaymentModule_LeftNavigation [back]

Parameters:

module var
indent

Return Type:

What MIVA Says

Admin calls this function when it expands the store’s Order Processing link in Admin’s left navigation menu.

It allows one to enter a link into the admin tool’s left navigation menu, if desired.

Default Return: NULL

Required function: PaymentModule_Payment_Methods [back]

Parameters:

module var
methods var

Return Type:acount

The method parameter is expected to be populated with an array of methods. The structure of the array is two fields, code and name. With code being the unique to the module method code that allows it to tell one method from another, and the name being the visible text that appears in the drop down list or wherever the UI renders it.

What MIVA Says

The UI calls this function when displaying a list of payment methods available for use in checkout.

It loads the l.methods structure with information about available shipping methods offered via this module, such as name and code.

It must return the number of methods added.

Default Return: NULL

Example 1:

Required function: PaymentModule_Payment_URL [back]

Parameters:

module var

Return Type:string

What MIVA Says

MIVA Merchant calls this function before displaying the OPAY screen.

If the function returns a value, MIVA Merchant knows it needs to deal with a CGI gateway for payment authorization and it forms the OPAY page appropriately, i.e. it sets the action of the main form to the payment url.

The module should return NULL for non CGI gateways.

Required function: PaymentModule_Payment_Description [back]

Parameters:

module var
data

Return Type:string

What MIVA Says

MIVA Merchant calls this function before displaying the OPAY screen.

It returns a textual description of the module, for display as a heading above the payment information input fields on the OPAY screen.

Default Return: NULL

Required function: PaymentModule_Payment_Message [back]

Parameters:

module var
data

Return Type:string

What MIVA Says

MIVA Merchant calls this function before displaying the OPAY screen.

It returns a textual description of the module, for display above the payment information input fields and below the heading from PaymentModule_Payment_Descrioption.

Default Return: NULL

Required function: PaymentModule_Payment_Hide_Additional_Fields [back]

Parameters:

module var
data

Return Type:bool

What MIVA Says

MIVA Merchant calls this function when displaying the OPAY screen.

It allows a module to insert hidden input fields on the OPAY form, such as might be required to pass state information to the CGI gateway processor.

Default Return: 1

Required function: PaymentModule_Payment_Fields [back]

Parameters:

module var
data

Return Type:cslist

What MIVA Says

MIVA Merchant calls this function before displaying the OPAY screen.

It returns comma separated list of field identifiers, of the form id[,id,id,id-]. MIVA Merchant will display the fields during the checkout process (usually on OPAY screen).

Default Return: NULL (i.e. no fields to diplay)

Required function: PaymentModule_Payment_Prompt [back]

Parameters:

module var
data
field_id

Return Type:string

What MIVA Says

MIVA Merchant calls this function before displaying the OPAY screen.

It returns a prompt (i.e. text) for the field named in the field_id parameter originally named in PaymentModule_Payment_Fields.

Default Return: NULL

Required function: PaymentModule_Payment_Invalid [back]

Parameters:

module var
data
field_id

Return Type:boolinv

What MIVA Says

The UI calls this function when displaying the OPAY screen.

It is a boolean flag to indicate whether or not the customer entered invalid data for the field specified by field_id.

The UI uses this flag so as to know whether to turn prompt red on screen (i.e. visually signal to the user that the valued entered in the field is invalid). The function may check flags set in PaymentModule_Payment_Field (e.g. g.Check_Number_Invalid) in order to determine whether the field is invalid or not.

Default Return: NULL

Required function: PaymentModule_Payment_Field [back]

Parameters:

module var
data
field_id

Return Type:bool

What MIVA Says

MIVA Merchant calls this function when displaying the payment information input fields on the OPAY screen.

It 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().

It outputs the HTML code required to display the field specified by field_id, for the method specified in data.

Default Return: 1

Required function: PaymentModule_Payment_Validate [back]

Parameters:

module var
pay_data

Return Type:bool

What MIVA Says

MIVA Merchant uses this function to determine whether to proceed with PaymentModule_Authorize.

One can insert here logic to determine whether or not to continue or to ask the shopper to re-enter data, for instance if the shopper failed to input a credit card expiration date.

Default Return: 1

Required function: PaymentModule_Report_Description [back]

Parameters:

module var
data

Return Type:string

What MIVA Says

It returns a textual description of the payment processing method, for use by MIVA Merchant during display during order processing and by batchreport modules.

Default Return: NULL

Required function: PaymentModule_Report_Fields [back]

Parameters:

module var
data
secure_data

Return Type:cslist

What MIVA Says

This function is an analog of PaymentModule_Payment_Fields, but for batchreport display.

It returns a comma-separated list of field identifiers

Default Return: NULL

Required function: PaymentModule_Report_Label [back]

Parameters:

module var
field_id

Return Type:string

What MIVA Says

This function is an analog of PaymentModule_Payment_Prompt.

It returns text for display beside the field identified by field_id (generated by PaymentModule_Report_Fields).

Default Return: NULL.

Required function: PaymentModule_Report_Value [back]

Parameters:

module var
field_id
data
secure_data

Return Type:string

What MIVA Says

This function returns the value corresponding to the field identified in field_id, e.g. the check number for field check.

Default Return: NULL

Required function: PaymentModule_Manipulate_Shipping [back]

Parameters:

module var
data

Return Type:bool

What MIVA Says

MIVA Merchant runs this function upon receiving the form submission from the OSEL screen.

The function provide an opportunity for a payment module to introduce extra charges for shipping, as may be the case with COD for example.

Default Return: 1

Required function: PaymentModule_Authorize [back]

Parameters:

module var
module_data
total
data var
secure_data var

Return Type:bool

What MIVA Says

This function provides a place for the code for determining whether to authorize a charge of l.total given the information in l.data. This is typically where the call to the payment processor resides, for use during order placement.

It The module should return 1 if successful, 0 on failure.

Default Return: 1

Required function: PaymentModule_Process [back]

Parameters:

module var
data var
secure_data var
order var

Return Type:bool

What MIVA Says

Admin calls this function during order processing in admin when one clicks Process Order.

This function exists for processing the payment data, typically for a post authorization.

It should It The module should return 1 on success, 0 on failure.

Default Return: 1

Required function: PaymentModule_Order_Validate [back]

Parameters:

module var

Return Type:bool

What MIVA Says

Admin calls this function to validate fields when one clicks Update on the Edit Order configuration screen.

It returns 1 if all fields are valid, 0 on failure.

Default Return: 1

Required function: PaymentModule_Order_Update [back]

Parameters:

module var
data var
secure_data var

Return Type:bool

What MIVA Says

Admin calls this function to validate fields when one clicks Update on the Edit Order configuration screen. One typically uses it to update any module-specific records for the order.

It The module should return 1 on success, 0 on error.

Default Return: 1

Required function: PaymentModule_Order_Delete [back]

Parameters:

module var
data
secure_data

Return Type:bool

What MIVA Says

Admin calls this function when one clicks Delete on the Edit Order screen. One typically uses it to clean up any module specific records for the order.

It The module should return 1 on success, 0 on error.

Default Return: 1

Required function: PaymentModule_Order_Tabs [back]

Parameters:

module var

Return Type:cclist

What MIVA Says

Admin calls this function when displaying the Edit Order configuration screen.

It returns a tab list for the Edit Order configuration screen.

Default Return: {toupper(l.module:code) $ ‘:’ $ l.module:name}

Required function: PaymentModule_Order_Content [back]

Parameters:

module var
tab
load_fields
data
secure_data

Return Type:bool

What MIVA Says

Admin calls this function to know what to display on the Edit Order configuration screen. This is similar to the other vis content functions.

Default Return: 1

Return Types [back]

Return Types are expressed in the document by the following codes:

string: A string return type is any string you wish though normally it is a string that has a specific intent such as the formatted version of a decimal number as you might use in a currency module.
cslist: This is a comma separated list values. Most commonly used to return a list of codes for fields.
cclist: This is a comma separated list of colon separated values. Most commonly used as a return from tab functions so that you might have a value like "NVALS:Normal Values,SPECVALS:Special Values,OVALS:Other Values" and the system would be treating each comma separated pair as a tab and using the value on the right of the colon as the label for the tab and the value on the left of the colon as the code for the tab.
bool: A boolean "true/false" return value, normally a "1" represents a true value and a "0" represents false. Because of the way the MIVA script language treats strings and numbers any string other than a space, and any number other than a 0 will be treated as a true return value whereas a false value can be expressed by a null value like "" or an expression that evaluates to null or zero like "{ 1 - 1 }" or the absence of the "VALUE" attribute entirely.
boolinv: An inverted boolean "true/false" return value. This is when the value returned is a boolean value just like the type "bool" but that the normal default return is a false rather than a true value and that you only return true if some special case is true. In the MIVA Merchant API Most functions that are boolean expect a return of true unless something has gone wrong or some special condition occurs, but in this case it is "normal" to return a false value and you only return a true value if something unusual happens. A specific example would be the TaxModule_Order_Invalid function which only returns a true value if one of the fields is invalid.
tristate: Acts like a boolean except that a negative value, usually -1 by convention, indicates an unusual but non error state. In most cases this will be used to cause the normal operations to not be completed without causing an error to be output in order to interrupt something that the system was about to do. This is used for example in system extension interrupts to stop a normal action like adding a product to the basket from taking place so the module can take on the role of adding the item to the basket itself, or preventing it from happening without causing the system to throw the normal errors.
acount: This is a numeric value that represents a count of the size of an array passed back by reference. A null or 0 return value acts the same as for a bool return type, meaning nothing happens, but a value of 1 indicates only one array index point exists whereas a return of 3 indicates 3 array index points returned. This is used for example in the shipping and payment method functions that have a method parameter passed in by reference and the return indicates the size of the method array being set in the l.method variable.

This document is copyright 2005-2006 4TheBest eCommerce Solutions and was last generated using Serade on 01/13/2006 23:04:54. It is permissible to place a copy of this document in it's current or altered form on your website as long as you leave the copyright notice along with the links to the websites referenced intact.