Table of Contents
Besides core modules, you can also add shipping and payment modules into VM. The concept of both - shipping and payment modules is to provide an API with a defined specification (similar to an interface), where the modules can plug themselves in. The modules implement the required functions and thus can communicate with the Shop and give their services.
VirtueMart has a lot of predefined payment methods. Some of these payment methods are controlled by special "payment modules", which are class files.
Example:
Payment Method: “Credit Card”, Payment Module: ps_authorize (Class File: ps_authorize.php)
Handles credit card authentication with the authrize.net server.
Payment Method “Cash on delivery”, Payment Module: ps_payment (ps_payment is an empty payment module)
No business logic needed for this kind of payment.
Virtuemart knows the following general payment method types:
- Payment Processor
Asks the Customer for Credit Card Details and processes the payment before the order is placed. Automatic Credit Card Processors do a server-to-server communication before the order is placed (e.g. authorize.net AIM).
- Credit Card
Just asks the customer for the credit card details. The details are securely stored in the database for capturing the payment manually afterwards.
- Bank Debit
Asks the customer for his/her bank account details, so you can get the money from the customer’s bank account afterwards.
- Address only/Cash on delivery
No payment processing by the module.
- HTML form-based
Transfers the customer to another server where he/she can pay. This is done after the order has been placed (examples: PayPal, Worldpay, 2Checkout)
If you have form code for a form-based payment method (most payment providers use this way), you just need to select "Store" ⇒ "Add Payment Method" from the VirtueMart admin drop-down menu.
An empty payment method form opens. Now fill in the details of your payment method like this:
Note
Be sure that you have NOT selected "credit cart payment" or "automatic processor".
On the second tab you must fill your form code (you can use HTML and PHP!) into the text area called "Payment Extra Info":
Caution
The code inside this form MUST BE VALID! If you use PHP code, check if you have written correct code that can be parsed!
Important
The information in this section only applies to situations when you want to implement a new payment method of the type “Payment Processor” or “HTML-form-based” (simliar to PayPal). All other payment methods can be created by just adding a new payment method in the shop administration! Then you don’t need to create a new payment module.
A payment module implements a technique to either
communicate with a remote server to authenticate the credit card of a user or
create a HTML Form to send the user to the pages of the payment provider where he/she can pay and return to your shop afterwards.
All payment modules are located in the directory
/administrator/components/com_virtuemart/classes/payment/
and provide two files: the class file and the configuration file.
Example: Module "mynewpayment"
You must have two files called
ps_mynewpayment.php(including the class ps_mynewpayment)ps_mynewpayment.cfg.php(containing all necessary configuration constant definitions)
ps_mynewpayment.php
will be included on checkout and its functions will be used to process
the payment details, regardless of the implementation.The following is a list of all methods that must be implemented in a payment module's class file.
- string show_configuration( void )
Shows the configuration form for this payment module in the payment method form.
- boolean has_configuration( void )
returns true if the payment module can be configured,
false if not
- boolean configfile_writeable( void )
returns true if the configuration file for that payment module is writeable,
false if not
- boolean configfile_readable( void )
returns true if the configuration file for that payment module is readable,
false if not
- void write_configuration( Array )
Stores all configuration values for this payment module in the configuration file.
- boolean process_payment(String $order_number, Float $order_total, Array &$d)
This is the main function for all payment modules that use direct connections to a payment gateway (like authorize.net or eWay XML). This is the place, where the payment details are validated and captured on success.
Returns true on sucess, false on failure.
- float get_payment_rate(Float $subtotal)
This is the function to calculate the fee / discount for this special payment module (so you can calculate a fee, depending on the order total amount).
Note
IF you are about to change configuration variables: do this in both functions: show_configuration and write_configuration!
Since there's no real installer for payment modules, you must
copy the two files ps_mynewpayment.php and
ps_mynewpayment.cfg.php into the directory
/administrator/components/com_virtuemart/classes/payment/
first.
After you have done that, you can add a new payment method ("Store" ⇒ "Add Payment Method"). It's important to fill in the correct name for Payment Class Name (in this case: ps_mynewpayment) - here's the reason why you must give the class file the same name as the class inside the file: the Shop now tries to include a file called "ps_mynewpayment.php" on Saving the payment method.
When you now re-open the newly created payment method, you have access to the configuration form.