Payment System API

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.

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'

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

Order Parameters

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

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

These are the details about the vendor account on the payment system

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:

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

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

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.

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

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 );

$IPN->paymentStatus = 249;

break;

}//endswitch

Sidebar

Joomla

Mobile Apps

Templates

Web Hosting Bundle

Simple, smart and Secure.