##How to manually add a payment gateway?
If you decided to create the payment gateway by yourself and are willing to share it with others, please send it to us via ticket system so we can add it to the core release.
####To add your payment system in the list of gateways.
Open the following file with FTP:
/joobi/node/apps/controller/apps-mycode_myclass.php
Add the following code:
$paymentInstallC = WClass::get( 'payment.install' ); $paymentInstallC->publishPaymentType( 'MyPaymentSystem', 'payment.mypaymentsystem', 'https://mypaymentsystem.com' );
The first parameter is simply the name will be appear in the list. The second specify the location where you will place the file with the code it has to be:
/joobi/node/payment/payment/mypaymentsystem/mypaymentsystem.php
##Payment API file
This will describe the different function available in your payment system. We recommend you copy an existing one and then make the appropriate changes. Paypal could be a good one to copy has it is very complete. You will need to put your file in the following location
/joobi/node/payment/payment/mypaymentsystem/mypaymentsystem.php
The class should be named in this format " _ _payment" which also extends to "Payment_System_class." i.e. class Paypal_Paypal_payment extends Payment_System_class { ... }
It is because the first payment name is used as the name of the main Joobi sub-folder name. And the second name is used as the name of the class file. Lastly, the "_payment" describes the type of Joobi extension used.
i.e. ../joobi/node/paypal/payment/paypal.php
Refer to below file to learn how each payment system is done.
Paypal: /joobi/node/paypal/payment/paypal.php
You can find all other payment gateway folder from below path;
/joobi/node/payment/payment/
Paypal has it own folder because it is a very complete payment gateway, however we highly recommend that you use the default folder
/joobi/node/payment/payment/
This is how the class file would be placed when the installation of the payment widget is completed.
Class Parameters:
These parameters are to be defined as global parameters of the Payment System class.
Parameter | Type | Description | Example |
---|---|---|---|
paymentName |
String |
Payment unique name of the payment system |
'Paypal' |
acceptAddress |
Boolean | This indicates that the payment system will receive the billing address when the order is submitted. |
True
False |
demoMode | Boolean | Boolean indicator that the payment is in demo mode |
True
False |
tokenField | String | This is the name used for the security token used by your site in the payment transaction records. This is different from the token/secret key/hashing used in the communication between APIs of your site and the payment system. | 'custom' |
submitURL | String | The payment system URL receiving the order forms. This is the location of the payment system API. | 'https://www.paypal.com/cgi-bin/webscr' |
formMethod | String | The type of form submission of the payment system will be receiving | Post, Get |
successURLName | String | This the form parameter name of the payment system where the value is the URL of the site will be redirected, once a completed transaction is made. | 'return' |
cancelURLName | String | This is the form parameter name of the payment system where the value is the URL of the site which will be redirected , once a cancelled transaction is made. | 'cancel_return' |
confirmationURLName | String | This is the form parameter name of the payment system where the value is the URL of the site which will be redirected, once a confirmation of the transaction needs to be performed. This URL is used when both the API systems communicates in the background. | 'notify_url' |
successURLExtra | String | This is the extra action/task wherein the site will execute if the transaction is successful. | '&action=succes' |
cancelURLExtra | String | This is the extra action/task wherein the site will execute if the transaction is cancelled. | '&action=cancel' |
confirmationURLExtra | String | This is the extra action/task wherein the site will execute if the transaction is being confirmed. | '&action=ipn' |
These are the functions which need to be coded for the API integration between Joobi payment system and the payment system you wanted to use.
Function Name | Description |
---|---|
orderGeneral( $order ) | This is where the order parameters are set on the form which will be sent to the payment system. |
orderDetails( $products ) | This is where the order products parameters are set on the form sent to the payment system. |
paymentConfirmation($object) |
This is where the response of the payment system which is assigned to object parameters. |
close( $status ) | This is where any extra processes are executed when the transaction is finished or ended. |
protected function orderGeneral( $order ) is used when the payment is placed on the website to compute the order and connect to the payment gateway. It will send all the proper information through a form. It the communication is not done through a form then the implementation of the communication can be done in that function.
Parameter Name | Type | Description |
---|---|---|
orederID | String | This is the Order Number of the customer's cart. |
orderName | String | This is the text 'Order:' plus the Order Number of the customer's cart. |
issueDate |
Integer | This is the time of the creation of the cart order in seconds. |
currencyID | String | This is the currency ID of the order when the checkout was done. |
currencyCode | String | This is the currency code of the order when the checkout was done. |
totalPrice | Decimal | This is the entire value of the order with the discounts. |
totalDiscount | Decimal | This is the entire value of the discounts of the products and coupon of the order. |
languageISO2 | String | This is the language ID from the customer's profile. |
image | String |
This is the url location of the payment image. |
firstName |
String | The customer's first name taken from his profile. |
lastName | String | The customer's last name taken from his profile. |
fullName | String | The customer's full name from taken his profile. |
String | The customer's email taken from his profile. |
|
ip | String | The customer's IP taken from his profile. |
Parameter Name | Type | Description |
---|---|---|
addressName | String | The name of the receiver who is addressed to. |
address1 | String | The first address value among the submitted addresses wherein the customer used. |
address2 | String | The second address value among the submitted addresses wherein the customer used. |
address3 | String | The third address among the submitted addresses wherein the customer used. |
city | String | The city address value of the submitted addresses wherein the customer used. |
state | String | The state value of the submitted addresses wherein the customer used. |
zip | String | The zip code value of the submitted addresses wherein the customer used. |
country | String | The customer's profile country name. |
countryISO2 | String | The customer's profile country code in 2-letter format. |
countryISO3 | String | The customer's profile country code in 3-letter format. |
Parameter Name | Type | Description |
---|---|---|
vendorid | String | The vendor's account email on the payment system. |
securekey | String | The vendor's account Secret Word on the payment system. |
##### Example:## **Order Details/Products Parameters:**$this->addField('cmd', '_cart'); //for shopping cart purchases
$this->addField('business', $order->vendorPayID );
$this->addField('charset', 'utf-8');
$this->addField('rm', '2');
$this->addField('upload', '1');
$this->addField('no_shipping', '1');
$this->addField('no_note', '0');
//top image of the paypal form
if ( isset($order->image) ) $this->addField('image_url', $order->image );
//This is only added when doing a testing on the payment system
//if ( $this->demoMode ) $this->addField('demo', 'y');$this->addField('first_name', $order->firstName );
$this->addField('last_name', $order->lastName );
$this->addField('email', $order->email );
$this->addField('item_name', $order->orderName );
$this->addField('item_number', $order->orderID );
$this->addField('currency_code', $order->currencyCode );
$this->addField('mc_gross', $order->totalPrice );//overriding the address
if ( !empty($order->addressName)&& !empty($order->address1) && !empty($order->country))$this->addField( 'address_override', 1 );
//address fields
if ( !empty($order->addressName) )
$this->addField( 'address_name', $order->addressName );$this->addField( 'address1', $order->address1 );
if ( !empty($order->address2) ) $this->addField( 'address2', $order->address2 );$this->addField( 'city', $order->city );
if ( !empty($order->zip) ) $this->addField( 'zip', $order->zip );
if ( !empty($order->state) ) $this->addField( 'state', $order->state );$this->addField( 'country', $order->countryISO2 );
//passtrought variables
$this->addField( 'invoice', $order->orderID );
This is where the order products details parameters are set on the form sent to the payment system. This function is optional.
Parameter Name | Type | Description |
---|---|---|
productID | String | The product's identification number. |
productName | String | The product's name. |
taxRate | Decimal | The product tax. |
discount | Decimal | The product summary of discounts from all that is applied (coupon, product and/or volume discounts). |
quantity | Integer | The quantity of the product ordered. |
basePrice | Decimal | The product base price in the currency of the cart checkout. |
unitPrice | Decimal | The product unit price in the currency of the cart checkout with the options total price. |
price | Decimal | The product price is the total of the unit price multiplied by the quantity in the currency of the cart checkout. |
curid | Integer | The product's base currency ID, which may differ from the checkout currency ID. |
## **Product Options Parameters**Example:
foreach ($products as $product) {//if disount is > 0 we need to check if the discount calculation will workif ( $product->discount > 0 ) {$real = $product->price - $product->discount;$real = Joobi::format( $real , 'price', $product->curid );$calculatedUnitPrice = ( $product->unitPrice –( $product->discount/$product->quantity ) );$calculatedUnitPrice =
Joobi::format( $calculatedUnitPrice , 'price', $product->curid );$calculatedPrice = $calculatedUnitPrice * $product->quantity;if ( $real==$calculatedPrice ) {
$quantity = $product->quantity;$unitPrice = $calculatedUnitPrice;} else {
$quantity = 1;$unitPrice = $real;}//endif
} else {$quantity = $product->quantity;$unitPrice = $product->unitPrice;}//endif
$this->addField('amount_' . $i, $unitPrice );$this->addField('item_name_' . $i, $product->productName );$this->addField('item_number_'.$i, $product->productID );$this->addField('quantity_' . $i, $quantity );
}//endforeach
Parameter | Type | Description |
---|---|---|
name | String | This is the option name available to the product. |
value | String | This is the option value chosen when the product option is available. |
type | Integer [ 1-fixed, 2-percent] |
This determines whether the product option value is in percent or fixed pricing. |
price | Decimal | This is the option price from the chosen option value; this may contain a negative value. |
## **Transaction Confirmation Parameters:**Example:
//Checking the product options
if( isset( $product->Options ) && !empty( $product->Options ) ) {//Creating the product optionsforeach( $product->Options as $id => $option ) {$this->addField( 'on' . $id . '_' . $i, $option->name );$this->addField( 'os' . $id . '_' . $i, $option->value );}//endforeach}//endif
protected function processConfirmation( &$IPN ). This function is used to confirm, cancel, or change status of the order. This function is called automatically with all the right parameters when the confirmation URL is triggered. The confirmation URL is created automatically and passed to the form automatically as well based on the property: $confirmationURLName These parameters are used in the confirmation of the response given from the payment system used. They need to be assigned with the parameter values that were passed and returned from the used payment system. The method object is commonly called IPN (Instant Payment Notification) or INS (Instant Notification System), as used by our examples using Paypal's parameters.
Parameter Name | Type | Description |
---|---|---|
paymentSystem | String | This is the name of the payment being used. |
transactionID |
String | This ID is given by the payment system of the transaction that occured on their system. It is sometimes referred to as the invoice ID. |
payerID | String | The ID of the customer's account record who made the transaction with them. |
receiverName | String | The name of the user on the payment system who is being paid. |
receiverID |
String | The ID of the user on the payment system who is being paid. |
receiverEmail | String | The email of the user on the payment system who is being paid. |
token | String | The token that was sent to indicate that the transaction came from us. |
payment |
String | The type of payment that was processed. |
addressStatus | String | The indicator whether the addresses were provided during the transaction. |
paymentStatus | String | The transaction status of the payment. |
payerStatus | String | The status of the account of the customer. |
reason | String | The reason / comment on the transaction which is mostly used to indicate the communication errors of the payment system's API. |
payerEmail | String | The customer's email address used on his account. |
payerName | String | The customer's name used on his account. |
firstName | String | The customer's first name which was passed before; the same if not modified during the transaction. |
lastName | String | The customer's last name which was passed before; the same if not modified during the transaction. |
addressName | String | The customer's address name which was passed before; the same if not modified during the transaction. |
addressStreet | String | The customer's street name which was passed before; the same if not modified during the transaction. |
addressZip | String | The customer's zip code which was passed before; the same if not modified during the transaction. |
addressCity | String | The customer's city address which was passed before; the same if not modified during the transaction. |
addressState | String | The customer's state address which was passed before; the same if not modified during the transaction. |
country | String | The customer's country address which was passed before; the same if not modified during the transaction. |
countryISO2 | String | The customer's country address in 2-letter format which was passed before; the same if not modified during the transaction. |
paymentDate | String | The transaction date. |
currencyCode | String | The currency of the transaction. |
shipping | String | The shipping charges if the order will be shipped. |
tax | String | The tax included during the transaction. |
totalPrice | String | The transaction's total cart price. |
fee | String | The fee using that payment system. |
comments | String | Other comment messages about the transaction. |
Commonly all parameters are received as string during the response from the payment system.
Example:
//This is used this way to make uniformity for the name format
$IPN->paymentSystem = $this->paymentName;
//IDs transaction / payer
$IPN->transactionID = WGlobals::getVar( 'txn_id', '', 'string' );
$IPN->payerID = WGlobals::getVar( 'payer_id', '', 'string' );
$IPN->receiverName = WGlobals::getVar( 'business', '', 'string' );
$IPN->receiverID = WGlobals::getVar( 'receiver_id', '', 'string' );
$IPN->receiverEmail = WGlobals::getVar( 'receiver_email', '', 'string' );
$IPN->token = WGlobals::getVar( 'custom', '', 'string' );
$IPN->paymentType = WGlobals::getVar( 'payment_type', '', 'string' );
$IPN->transactionType = WGlobals::getVar( 'txn_type', '', 'string' );
$IPN->parentID = WGlobals::getVar( 'parent_txn_id', '', 'string' );//load the status
$IPN->addressStatus = WGlobals::getVar( 'address_status', '', 'string' );
$IPN->paymentStatus = WGlobals::getVar( 'payment_status', '', 'string' );
$IPN->payerStatus = WGlobals::getVar( 'payer_status', '', 'string' );
$pending_reason = WGlobals::getVar( 'pending_reason', '', 'string' );
$reason_code = WGlobals::getVar( 'reason_code', '', 'string' );
$IPN->reason = $pending_reason . $reason_code;//payer information
$IPN->payerEmail = WGlobals::getVar( 'payer_email', '', 'string' );
$IPN->payerName = WGlobals::getVar( 'payer_business_name', '', 'string' );
$IPN->firstName = WGlobals::getVar( 'first_name', '', 'string' );
$IPN->lastName = WGlobals::getVar( 'last_name', '', 'string' );
$IPN->addressName = WGlobals::getVar( 'address_name', '', 'string' );
$IPN->addressStreet = WGlobals::getVar( 'address_street', '', 'string' );
$IPN->addressZip = WGlobals::getVar( 'address_zip', '', 'string' );
$IPN->addressCity = WGlobals::getVar( 'address_city', '', 'string' );
$IPN->addressState = WGlobals::getVar( 'address_state', '', 'string' );
$IPN->country = WGlobals::getVar( 'residence_country', '', 'string' );
$IPN->countryISO2 = WGlobals::getVar( 'residence_country_code', '', 'string' );//information about the order
$IPN->numberOfProducts = WGlobals::getVar( 'num_cart_items', 0, 'int' );
$IPN->paymentDate = WGlobals::getVar( 'payment_date', '', 'string' );
$IPN->currencyCode = WGlobals::getVar( 'mc_currency', '', 'string' );//total and fees
$IPN->shipping = WGlobals::getVar( 'mc_shipping', '', 'string' );
$IPN->handling = WGlobals::getVar( 'mc_handling', '', 'string' );
$IPN->tax = WGlobals::getVar( 'tax', '', 'string' );
$IPN->totalPrice = WGlobals::getVar( 'mc_gross', '', 'string' );
$IPN->fee = WGlobals::getVar( 'mc_fee', '', 'string' );
$IPN->comments = WGlobals::getVar( 'memo', '', 'string' );
Payment Status
These are the possible values used in converting the transaction payment status from the payment system to our order payment status. The status are stored into the picklist "order_status" Although those status can be change or even add new one it is not recommended as the value of the status is used in the core functionality of the eCommerce Apps.
Value | Status |
---|---|
5 | wait for payment |
10 | pending |
15 | In-Progress |
20 | Completed |
25 | Processed |
50 | Refunded |
60 | Refund requested |
80 | Charged back |
97 | Automatically cancelled |
98 | Canceled-reversal |
99 | Canceled |
110 | Voided |
115 | Expired |
120 | Denied |
150 | Failed |
249 | Type not defined yet |
230 | Dispute filed |
Example:
$statusLower = strtolower($IPN->paymentStatus);
switch ( $statusLower ) {case 'completed':$IPN->paymentStatus = 20;break;case 'processed':$IPN->paymentStatus = 25;break;case 'refunded':$IPN->paymentStatus = 50;break;case 'canceled':$IPN->paymentStatus = 99;break;case 'canceled-reversal':case 'canceled_reversal':$IPN->paymentStatus = 98;break;case 'reversed':$IPN->paymentStatus = 80;break;case 'voided':$IPN->paymentStatus = 110;break;case 'expired':$IPN->paymentStatus = 110;break;case 'denied':$IPN->paymentStatus = 120;break;case 'pending':$IPN->paymentStatus = 10;break;case 'in-progress':$IPN->paymentStatus = 15;break;case 'failed':$IPN->paymentStatus = 150;break;case 'new_case':$IPN->paymentStatus = 230;break;default://the default case should not be corvered.//However if it is the case it means that the status//return a value which was not planed.//the typeNotDefined function send an email to the admin//so we can improve the system.//send an email because not yet defined$paymentHelperC = WGet::classes('payment.helper');$paymentHelperC->typeNotDefined( $this->paymentName,'paymentStatus', $IPN->paymentStatus );}//endswitch$IPN->paymentStatus = 249;break;
How to change some of the fields of the payment form?
There are several fields which can be used into the payment form to cater to the need of the payment system. Those field can be used to provide credentials or other specific information for the payment gateway.
You can use the following function to add, remove or change the name of fields:
public function paymentElementToRemove(): use this function to remove fields
public function paymentElementToAdd(): use this function add fields which dont appear by default
public function paymentChangeElements(){
$this->changeElements( 'payment_form_payment_vendorid', 'name', 'Login Id' );
$this->changeElements( 'payment_form_payment_vendorid', 'description', 'Provide the login ID from the payment gateway' );
}//endfct
Use paymentChangeElements function to change the name or description of fields