Add New Gateway
Overview
Enables the adding of new payment gateway. Note that this feature is experimental and ONLY for advanced users. You
will require an advanced knowledge of PHP (as custom programming is needed) and the payment gateway API to continue. For a payment gateway to work it must support the hosted method
and have a callback API that uses POST or GET. If you aren't sure of this, ask your payment provider. If nothing makes sense below, you will need assistance.
Gateway Name
Display name for gateway. Max 100 chars.
Live Payment Server POST Url
This is the live server POST url as determined by the gateway. This url accepts the POST parameters from the music system. If not required, enter any url.
Select the correct protocol from the drop down. The value in the box should NOT include 'http://' or 'https://'.
Select the correct protocol from the drop down. The value in the box should NOT include 'http://' or 'https://'.
Sandbox Payment Server POST Url
This is the sandbox callback url as determined by the gateway if applicable. Can be used for other operations if necessary. If not required, enter any url.
Select the correct protocol from the drop down. The value in the box should NOT include 'http://' or 'https://'.
Select the correct protocol from the drop down. The value in the box should NOT include 'http://' or 'https://'.
Website
Webpage for gateway. Select the correct protocol from the drop down. The value in the box should NOT include 'http://' or 'https://'.
Enabled
Yes to enable, No to disable
Class to Load
Each gateway has 2 files, these must be named and exist as follows ("gateway" should be a unique identifier):
control/callback/gateway.php
control/classes/gateways/class.gateway.php
control/classes/gateways/class.gateway.php
Display Image
For cosmetics only, should exist in the following locations:
admin/content/images/gateways/
content/**THEME**/images/gateways/
content/**THEME**/images/gateways/
Document Page
The corresponding document page for this gateway. Located in the "docs" folder. Gateway docs file must start "gw-" for the
system to pick it up. See existing files for examples. This is optional, if there is no docs file, leave blank.
Parameters
Key/Value pairs that can contain data to be sent to the gateway or used to validate a response from the
gateway. By default no parameters are used unless created in the relevant class files. You can add more parameters if you want to
pass additional info to the gateway.
Note that the values must be entered on the right, the left values are the parameter names and MUST not be changed.
Depending on the gateway, parameter names are sent as either $_POST or $_GET values.
To add/remove parameter lines use the +/- buttons.
Note that if you prefer the values to be hidden, enable the "Always Hide Gateway Parameter Values" in your settings via the Payment tab.
Note that the values must be entered on the right, the left values are the parameter names and MUST not be changed.
Depending on the gateway, parameter names are sent as either $_POST or $_GET values.
To add/remove parameter lines use the +/- buttons.
Note that if you prefer the values to be hidden, enable the "Always Hide Gateway Parameter Values" in your settings via the Payment tab.
Setup - Class File
Firstly, make a copy of 'control/classes/gateways/class.new.php' and rename it to something else. Save in same folder. You can refer to
any other payment gateway file for reference.
This class has 4 functions:
This is done via the 'fields()' function. Refer to the payment gateway API to see what post vars should be sent. Add key => value pairs, the key being the post field name, the value is the field value. The gateway must support a custom field, where you can send any data and this field MUST contain the buy code, sale id and 'mswmusic' value separated with a dash. See file for reference.
To get any data from the sale or from gateway parameters created in admin, you can use the following:
After a payment has occurred you need to verify it was valid, this is done via the 'validate()' and 'callback()' functions.
First you should assign the POST vars returned for further processing in the 'callback()' function. The field that held the custom data MUST be assigned to the 'code-id' parameter in the 'callback()' function. Only 'trans-id,amount,currency,pay-status & code-id' are required values, the rest ONLY if you are doing further processing afterwards in the processing file (see below)
It is important the 'pay-status' value is one of the following:
The 'validate()' function determines if the sale was valid and you should refer to the payment gateway API to see how they require validation to be done. Payment gateways vary. You should add your own code. You may use the above functions to get any sale or parameter data.
Note that this function should ONLY return one of the following values:
This class has 4 functions:
validate() = Validates successful postback. Returns 'ok' or 'err'.
callback() = Assigns callback parameters to standard variables.
fields() = Assigns the POST data to send TO the payment gateway.
mailtemplates() = The preferred mail templates for this gateway. You can leave this as it is.
1 Sending POST Data to Payment Gatewaycallback() = Assigns callback parameters to standard variables.
fields() = Assigns the POST data to send TO the payment gateway.
mailtemplates() = The preferred mail templates for this gateway. You can leave this as it is.
This is done via the 'fields()' function. Refer to the payment gateway API to see what post vars should be sent. Add key => value pairs, the key being the post field name, the value is the field value. The gateway must support a custom field, where you can send any data and this field MUST contain the buy code, sale id and 'mswmusic' value separated with a dash. See file for reference.
To get any data from the sale or from gateway parameters created in admin, you can use the following:
$order = $this->getsale($this->order['id'],$this->order['code']);
print_r($order);
$params = $this->params();
print_r($params);
The $this->order['id'] & $this->order['code'] vars are created at runtime and contain the buycode and sale ID respectively.
Parameters will be key => value pairs as created in admin, so if you created a var called 'name' and it's value was 'joe bloggs', you would us the following to reference the value:
$params['name'];
2 Validating Payment from Payment Gatewayprint_r($order);
$params = $this->params();
print_r($params);
The $this->order['id'] & $this->order['code'] vars are created at runtime and contain the buycode and sale ID respectively.
Parameters will be key => value pairs as created in admin, so if you created a var called 'name' and it's value was 'joe bloggs', you would us the following to reference the value:
$params['name'];
After a payment has occurred you need to verify it was valid, this is done via the 'validate()' and 'callback()' functions.
First you should assign the POST vars returned for further processing in the 'callback()' function. The field that held the custom data MUST be assigned to the 'code-id' parameter in the 'callback()' function. Only 'trans-id,amount,currency,pay-status & code-id' are required values, the rest ONLY if you are doing further processing afterwards in the processing file (see below)
It is important the 'pay-status' value is one of the following:
completed = completed payment
refund = refunded payment
pending = pending payment
Not all gateways support refunded and pending payments.refund = refunded payment
pending = pending payment
The 'validate()' function determines if the sale was valid and you should refer to the payment gateway API to see how they require validation to be done. Payment gateways vary. You should add your own code. You may use the above functions to get any sale or parameter data.
Note that this function should ONLY return one of the following values:
ok = valid payment
err = invalid payment
Please refer to other payment gateway files for reference and to see how data is assigned. Not all gateways behave in the same way and you'll
see differing code in many of the gateway files. Some only require the 'validate()' function to return 'ok' because validation is confirmed elsewhere.
err = invalid payment
Setup - Processing File
Firstly, make a copy of 'control/callback/new.php' and rename it to something else. Save in same folder. You can refer to
any other payment gateway file for reference.
The processing file completes all operations, such as updating sale in database, sending emails and performing custom operations. It relies on the data assigned in the 'callback()' function. Unless you need to do some custom tweaks, this file shouldn't need changing.
The processing file completes all operations, such as updating sale in database, sending emails and performing custom operations. It relies on the data assigned in the 'callback()' function. Unless you need to do some custom tweaks, this file shouldn't need changing.
Custom Callback Operations
If you are using 3rd party software you may need to perform other actions after a successful payment. You
can add custom code in the following file:
control/callback/ops/custom.php
Refer to the notes in that file for reference.
Feedback
If you have implemented an additional gateway, let us know how you got on with the instructions. They aren't
too detailed, but for an advanced programmer they should highlight the changes required.