##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.

ParameterTypeDescriptionExample

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'
## **Functions used:**

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 NameDescription
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.
## **Order Parameters**

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 NameTypeDescription
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.
email String The customer's email taken from his profile.
ip String The customer's IP taken from his profile.
### The following are available if acceptAddress is set to 'true'
Parameter NameTypeDescription
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.
### These are the details about the vendor account on the payment system
Parameter NameTypeDescription
vendorid String The vendor's account email on the payment system.
securekey String The vendor's account Secret Word on the payment system.
##### Example:
$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 );

## **Order Details/Products Parameters:**

This is where the order products details parameters are set on the form sent to the payment system. This function is optional.

Parameter NameTypeDescription
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.
Example:


foreach ($products as $product) {

//if disount is > 0 we need to check if the discount calculation will work
if ( $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
## **Product Options Parameters**
ParameterTypeDescription
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.
Example:

//Checking the product options
if( isset( $product->Options ) && !empty( $product->Options ) ) {

//Creating the product options
foreach( $product->Options as $id => $option ) {
$this->addField( 'on' . $id . '_' . $i, $option->name );
$this->addField( 'os' . $id . '_' . $i, $option->value );
}//endforeach
}//endif
## **Transaction Confirmation Parameters:**

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 NameTypeDescription
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.

ValueStatus
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 );
$IPN->paymentStatus = 249;
break;
}//endswitch

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