How To Create BC Plugins - Part 2 - Payment Gateways

Though we - over time - will add more and more payment gateways to BreezingCommerce, you might want to know how you can create your own ones. With some PHP knowledge and the basics about BC Plugin development as described here, this tutorial will help you to get your head around payment gateways and creating BC Plugins for BreezingCommerce.

Content:

1 - TYPES OF PAYMENT GATEWAYS

2 - ANATOMY OF A BC PAYMENT PLUGIN: THE ADMIN SIDE

3 - ANATOMY OF A BC PAYMENT PLUGIN: THE FRONTEND SIDE

4 - REFERENCE IMPLEMENTATION

As mentioned above, please make sure to read Part 1 of our BC Plugin tutorials here.

1 - Types of Payment Gateways

Addressing payment gateways in online stores is the most important part but the large amount of worldwide available payment gateways result in a multitude of different approaches on how they work.

There might be more but usually there are these different types of payment gateways and combinations and their corresponding BC Plugins:

Forward & Redirect: The payment gateway expects to forward to its site and once the payment is complete, it redirects back to your store where the payment is verified.
- The simplest form of payment processing.
- Requires some sort of token for the verification on the store-side.
- Can break the payment verification if the customer interrupts from being redirected back to your store.
- PayPal Standard without the use of IPN (Instant Payment Notifications) is an example of this.
Forward & Background Notifications: Similar to above, the user is forwarded to the payment gateway site but the instead of redirecting back to the store for verification, the payment gateway itself will contact your server in the background. Your server then will verify the payment based on the information the server provided.
- Adds a bit more complexity to your payment plugin.
- Beside the need of a token, you might need to enable that feature in your payment gateway settings.
- Doesn't break payment verification upon redirect but the customer still needs to leave your store for payment processing.
- PayPal Standard with the use of IPN is a classic example of this approach.
On-Site Payment & Background Payment Push: The customer will stay in your store and enter his data (e.g. credit card data). The payment gateway will return a hash or ID that is only valid for this transaction. When the data entry is processed, your server will send all the data to the payment gateway's server in the background, including the hash or ID, to finally process and finish the payment.
- The customer doesn't leave your store at all.
- Usually doesn't require any special setup with fixed tokens.
- Example for this would be Stripe credit card payments.
Manual Payments: If you need to offer payment options that don't require a 3rd party service to collect the money it is called manual payment. Manual payments usually require manual clearing through bank transfer or cash on delivery, by the customer.
- No need to contact 3rd party servers.
- Customer doesn't need to leave your store.
- Requires manual action from your customer to invoke the payment and the store owner to verify (e.g. by checking bank statements when using bank transfer).
- Requires a little special treatment within a BC Plugin (more later).
Offline Payments: Similar to offline payments but instead of manual clearing through some customer action, the payment will be cleared by the store owner. An example would be credit card offline payments, where the user enters the credit card information and the store owner will trigger the payment through his point of service.

NOTE: In BreezingCommerce, when a payment is cleared with non-offline/manual payments, an invoice will be generated noting that the payment has been cleared while offline/manual payments will generate invoices with the note that the payment needs to be done (in fact it depends on the plugin what shows up in the invoice).

2 - Anatomy of a BC Payment Plugin: The Admin Side

As explained in Part 1, every plugin, no matter what type, may (but don't have to) provide administration interfaces to collect options that will be used in the code logic. Payment plugins are no exception here, so a regular payment plugin consists of an admin and a public (site) part.

Foreach type of BC Plugin there are specialisations in the form of functions that are only executed for a certain type of plugin. Those functions are either required to be implemented or optional.

The admin side of a bc payment plugin must implement the following functions in its index.php's class. This means that the following functions must exist in your admin class:

function getPluginDisplayName(){
   
    return 'A human readable name for your plugin';
}

Returns a string with a readable name for your plugin. Will be displayed in the administration => Plugins, in the list of available plugins.

function getPluginDescription(){
   
    return 'A human readable description for your plugin';
}

Returns a string with a readable description for your plugin. Will be displayed in the administration => Plugins, in the list of available plugins. This function is available for future versions of the BreezingCommerce but must already be implemented, as well.

function init($subject = null){

}

init() will be called when the plugin loads, right before it fires any other method. The $subject parameter is optional and holds the current cart object. This method can be used to wrap up things that might be used later.

function getPaymentInfo(){

  return 'Some Information';
}

Should return the payment information. The payment information will be visible on invoices and in the personal area of the customer and presented if an order has not the status "paid". The payment information may be a text, containing information how to pay. *For instance for bank transfer it would show the payment information. For paypal it would show the vendor's email address to send the money to, and so on.

function getAfterPaymentInfo(){

  return 'Some Information after successfull payment';
}

Should return a string with information after a payment has successfully been done. Usually you will want to let the information appear on the invoice with this to show that the payment has been cleared.

The admin also provides some optional functions that can be implemented but don't have to be. Those functions are:

public function getPluginIcon(){
        
        return '';
}

The string returned will be display in the administration. By now, this is a placeholder for future versions of BreezingCommerce.

public function handleOrderDisplay($order_id){
        
        return '';
}

With this function, you may display some information in the order details for the selected payment method, based on the order_id. If you for example provide credit card offline payments, you can use this to display the credit card information right in the order.

3 - Anatomy of a BC Payment Plugin: The Frontend Side

While the admin side of payment plugins above mainly include functions to display information, the frontend side's (site) functions can get pretty complex as there will be all the logic to display and verify payments.

The site part of a payment plugin must include the following functions:

function init($subject = null){

}

function verifyPayment(CrBcCart $cart_instance, stdClass $order_object){

}

Must verify a payment. Will be called in the url as soon as the parameter verify_payment=1 is given. Must return true or false based on the success. To display error messages for failed payments, please use Joomla!'s enqueueMessage() function as it will redirect to the site after failed payments, giving enqueueMessage() a chance to display the error.

getPaymentTransactionId(){

   return '';
}

Will be called right after a successfully verified payment. Best is to store the tx id from a payment gateway into a private class variable within verifyPayment() and return it in this method.

function getPaymentInfo(){

  return 'Some Information';
}

function getAfterPaymentInfo(){

  return 'Some Information after successfull payment';
}

function getInitOutput(){

   return '';
}

Inits the payment visually. Visually can mean here to either display some forms to collect e.g. credit card information or redirecting to a payment gateway. Will be skipped on manual payments like cash on delivery (see isManualPayment()).

Just like the admin side, the frontend side also provides some optional methods:

public function getPluginIcon(){
        
        return '';
    }

Returns a string with icon or text which will appear in the checkout process to select a payment option.

public function isManualPayment(){
        
        return false;
    }

Use this if you need to create a payment method that doesn't connect to any payment gateway or if the payment is done with a delay by the customer (e.g. bank wire). If true is returned, the order will be marked as finished but not paid yet, bypassing all other functions like getInitOutput().

public function isOfflinePayment(){
        
        return false;
    }

Use this if this to implement delayed payments but where the action is NOT on the customer side. E.g. when doing credit card offline payments, setting this to true will still let you use functions like getInitOutput() to provide forms to collect data, but it will keep the paid flag to none. In combination with this, it can be very handy to collect data in getInitOutput() and use handleOrderDisplay() to display the collected data for later processing in the order details.

4 - Reference Implementation

As reference implementation for all the information above, please download and unzip the main BreezingCommerce Lite (free) package from here and locate the PayPal plugin. You can use it as foundation to create a custom plugin or start from scratch with the information found here and in Part 1 of our plugin tutorials.

BreezingCommerce