Got a question?

We have compiled a list of articles and common questions that we hear from our customers. Ask or enter a search term below for quick results.

Note: If you can't find what you're looking for; try this custom search.

  1. Home
  2. Documentation
  3. Joomla
  4. jMarket
  5. Developer Zone
  6. Third Party Integration
Please visit our new and updated Developer Payment API.

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

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

These are the parameters that will be used to inform the payment system of the customer's order details.

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:

These parameters are available in supplying the payment system in which the information of the products are placed on the cart of the customer.

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:

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.

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