Implementing a new Payment Gateway (Developers Guide)

We designed the payment process to be as modular as possible in order to facilitate developers to integrate their own payment options.

Defining the processor in the backend

When setting up the processor in the backend the field Type holds the file name of the processor. The file name will be used to instantiate the processor. Make sure the value type of the type corresponds with the name of file. For example if your file name is paypal.php you will input in the type field PayPal. Also consider uppercase letters.

Creating the processor

All processors are located in the following location: site/classes/payment/processors. You need to create a new file with .php as an extension and name it with the processor name. Make sure it’s the same value as defined for the field type in the backend.

Each processor will implement the interface iPaymentProcessor in order to standardize the functions used in the payment process. Below is a summary of the required functions. We’ll explain each function in detail when going through the payment process.

interface iPaymentProcessor {

public function initialize($data); public function getHtmlFields(); public function getPaymentProcessorHtml(); public function getPaymentDetails($paymentDetails, $amount, $cost); public function processTransaction($data); public function getPaymentGatewayUrl();

}

The payment process

Each available payment processor is retrieved from the database and displayed as an option when the reservation process is in the payment options step.

Each processor is initialized with its own specific data, inputted in the backend when the processor is defined. The regular parameters as well as the extra fields can be accessed. For PayPal we have the following:

public function initialize($data)
{
    $this->type=  $data->type;
    $this->name=  $data->name;
    $this->mode = $data->mode;
    $this->paypal_email = $data->fields['paypal_email'];
}

You notice that the processor extra fields are set in the object fields as an array. When initializing the processor you can assign the processor parameters to local variables in order to use them in other functions.

In the payment option step the function getPaymentProcessorHtml() is called to retrieve form fields or specific instructions for the process. A processor that requires input of credit card details will return specific inputs for credit card details.

In PayPal’s case it will just display a message that the client will be redirected to PayPal’s website to make a payment.

After a payment processor is selected and the client goes further with the reservation the processTransaction($data) function of a processor is called. Depending on the processor this function will either process the payment or make a redirect towards a payment site. The $data parameter is a structure containing all the reservation data.

Now let’s get some insight on the function in PayPal’s case. Each processor has to return a series of parameters. Please see below:

$result = new stdClass();
$result->transaction_id = 0;
$result->amount=  $data->cost> 0? $data->cost: $data->total;
$result->payment_date = date("Y-m-d");
$result->response_code = 0;
$result->confirmation_id = $data->confirmation_id;
$result->currency=  $data->reservationData->hotel->hotel_currency;
$result->processor_type = $this->type;
$result->status = PAYMENT_REDIRECT;
$result->payment_status = PAYMENT_STATUS_PENDING;
return$result;

These parameters are used to create a payment record. In PayPal’s case you notice that the status is set to redirect and the payment status is set to pending as the payment has been completed yet. For a processor that does the payment processing without redirect the status will be set to another value.

Possible statuses are PAYMENT_SUCCESS, PAYMENT_WAITING, PAYMENT_ERROR, PAYMENT_CANCELED, PAYMENT_IFRAME.

The PAYMENT_WAITING status will redirect the client to the confirmation screen. Use this status when creating payment processor like Wire Transfer where the payment status is confirmed at a later date, independent from the processing available in J-HotelRerservation.

The payment status can be set to one of the following values: PAYMENT_STATUS_PENDING, PAYMENT_STATUS_WAITING, PAYMENT_STATUS_PAID, PAYMENT_STATUS_CANCELED

When your processor is redirecting make sure you set the getPaymentGatewayUrl() and getHtmlFields() functions with the necessary logic. These functions are called when redirecting and you can control their output.

The getPaymentGatewayUrl() function will return the redirect URL which is specific to each processor and represents the URL at which the processing is made.

The getHtmlFields() function will return all the necessary parameters required by the payment gateway.

Processing the Response

If you’re using a redirect processor, meaning that payment is not processed on your website, make sure you set the return URL to:

index.php?option=com_jhotelreservation&task=paymentoptions. processPaymentResponse.

In the url please add the processor type as a parameter. =”&processor=paypal”;

When the payment processor notifies the a response you can use the URL:

index.php?option=com_jhotelreservation&task=paymentoptions.processAutomaticResponse

When the return URL is called by the payment gateway the processResponse($data) response function of a processor is called. The $data parameter of this function represent all the post data received from the payment processor.

Define this function to process the payment gateway specific response. Several parameters need to be returned to the J-HotelReservation processing so that the payment transaction can be updated correspondingly. There parameters are the same as the parameters returned from the processTransaction($data) function but it’s up to you as developer to set them. Please see below.:

public function processResponse($data)
{
    $result = new stdClass();
    $result->transaction_id = $data["txn_id"];
    $result->amount = $data["mc_gross"];
    $result->payment_date = $data["payment_date"];
    $result->response_code = $data["payment_status"];
    $result->confirmation_id = $data["item_number"];
    $result->currency= $data["mc_currency"];
    $result->processor_type = $this->type;
    $result->status = PAYMENT_SUCCESS;
    $result->payment_status = PAYMENT_STATUS_PAID;

Return $result;

}

It is important to set the confirmation_id in case of redirects so that the corresponding reservation payment status is updated. With this final step your payment is complete and statuses are updated accordingly.

Please note that CMSJunkie doesn’t provide any assistance in developing a new payment processor. Any assistance requests will be charged as agreed with the client.