The buyCred Payment Gateway API

Navigation:

Description

In this tutorial I will introduce you to the gateway API used by the buyCred add-on.

By default myCred offers 4 different payment gateways for you to use but you can expand this and add any number of other gateways.

Requirements

• Basic PHP knowledge.
• Experience with building WordPress plugins.

Before we get started

This tutorial is meant for users who have some experience with building WordPress plugins and have a basic understanding of PHP!

While I am happy to troubleshoot any gateway related issues or answer questions, I will not be offering any support on troubleshooting the payment service you are attempting to implement! Please remember that myCred is a one man operation and I just can’t support every single payment gateway out there.

Gateway Types

myCred was built for two main types of payment processors:

• Local
  Local gateways collects the necessary payment information from the user on your website and sends this information after validation to a payment processor. The user never leaves your website. I.e. Zombaio and NETbilling.
• Remote
  Remove gateways will redirect a user to a remote website where the user enters their payment details, gets processed and returned to your website once completed or cancelled. I.e. PayPal and Skrill (Moneybookers).

The Process

When a user requests to buy points though the mycred_buy or mycred_buy_form shortcodes, they are re-directed to the processing page with their request. Example requests:

// Request though the mycred_buy shortcode
$_GET = array(
	'mycred_buy' => 'gateway-id',
	'amount'     => 10,
	'token'      => 'securitytoken'
)
// Request though the mycred_buy_form shortcode
$_POST = array(
	'mycred_buy' => 'gateway-id',
	'amount'     => 10,
	'token'      => 'securitytoken',
	'post_id'    => 1,
	'gift_to'    => 1
)

As you can see the mycred_buy shortcode sends the request though $_GET while the mycred_buy_form sends it though $_POST.

Notes on the above request examples:

1. The post_id variable is only sent if you have setup the mycred_buy_form shortcode to allow users to purchase points for the content author. If this is not setup or used, the post_id variable will not be included.
2. The gift_to variable is only used if the purchase is made for another member (a.k.a. Gifting). If you do not use this feature this variable will not be included.
3. The user id of the buyer is not included in the request! You would need to use get_current_user_id to get the buyers ID.

Registering your Gateway

Before constructing the gateway, the first thing you would need to do is to register your custom gateway with myCred. This is done though the mycred_setup_gateways filter.

add_filter( 'mycred_setup_gateways', 'register_custom_gateway' );
function register_custom_gateway( $gateways )
{
	// Using a gateway class
	$gateways['unique-gateway-id'] = array(
		'title'    => __( 'Gateway Title' ),
		'callback' => array( 'gateway_class_name' )
	);
	// or Using a gateway function
	$gateways['unique-gateway-id'] = array(
		'title'    => __( 'Gateway Title' ),
		'callback' => 'gateway_function_name'
	);
	return $gateways;
}

Note that you can either use a class for your gateway in which case the ‘callback’ value must be inside an array or you can use a function in which case you should just set it to the function name.

The myCred_Payment_Gateway Class

The myCred_Payment_Gateway class is an abstract class used by all built-in gateways. It contains commonly used functions along with help functions for drop-down menus. You don’t need to use it, if you prefer to write everything yourself, that’s perfectly fine. In this tutorial however I will be going through how to use the class method.

There are three class methods that your custom gateway must include:

1. process() This method is called either when a local request is made (i.e. your local form is submitted) or if this is a remote gateway, when the IPN call is returned. Note! For this to work, the IPN call from the payment processor must contain the mycred_call variable!
2. buy() This method is called when the user submits a purchase request though the two shortcodes and either re-directs the user to a remote gateway or presents the purchase form.
3. returning() This method is used when the user is returning from a remote payment processor. You can use this method to either process the result as the user returns (if thats how the payment system works) or use it to redirect users to the appropriate landing page (i.e. Cancelled or Thank You page).

The Payment Processing Page

Either when you need to collect your buyers payment details (for local gateways) or when you redirect the buyer to a payment processor (for remote gateways), the buyCred add-on generates a “Processing” page.

This processing page is constructed by using the purchase_header() and purchase_footer() class methods. If you are building a remote gateway, you can also use form_with_redirect() while if you are building a local gateway, you would need to output your form or any details needed yourself between the purchase_header and purchase footer functions.

Example 1: Constructing a payment page for a local gateway:

class My_Custom_Gateway extends myCRED_Payment_Gateway {
	function __construct( $gateway_prefs ) {
		parent::__construct( $args, $gateway_prefs );
	}
	function buy() {
		$this->purchase_header( 'Header / Title' );
		echo 'these things needs to be included on this page';
		$this->purchase_footer();
	}
}

Example 2: Constructing a payment page for a remote gateway:

class My_Custom_Gateway extends myCRED_Payment_Gateway {
	function __construct( $gateway_prefs ) {
		parent::__construct( $args, $gateway_prefs );
	}
	function buy() {
		$this->purchase_header( 'Header / Title' );
		$arguments = array();
		$this->form_with_redirect( $arguments );
		$this->purchase_footer();
	}
}

You can find more information on these functions in the documentation for the myCred_Payment_Gateway class. I also recommend you look at how existing gateways do this!

IPN handling for remote gateways

When working with remote gateways, we are required to intercept calls from the gateway confirming the users payment. Most payment processors offer a “Instant Payment Notifications” service where they will call your website on a specific URL informing you how things went.

When a IPN call is made and contains the mycred_call variable, the gateway API will load the corresponding gateway to handle this callback. buyCred in-itself does not do anything about these calls besides intercepting them, it is up to your gateway class to handle this.

To achieve this, buyCred will load the process() method in your class. This method should do whatever you need to do in order to verify the call and award points according to the purchase. I recommend you have a look how the PayPal gateway handles IPN calls in it’s process() function.

On the other hand if your building a local gateway, make sure you include the mycred_call variable in your form in order for the process() function to fire!

Other useful methods

The myCred_Payment_Gateway class comes with several help functions for you to play with:

• currencies_dropdown This function generates a dropdown menu with all supported currencies for your user to select from. You can use the mycred_dropdown_currencies filter to add more currencies that your gateway might support.
• item_types_dropdown This function generates a dropdown of item types. Mainly used by PayPal but can be customized via the mycred_dropdown_item_types filter.
• list_option_countries This function will generate the options to use in a select element with a list of countries and their two character codes as values.
• list_option_us_states This function will generate the options to use in a select element with a list of US states and their two character codes as values.
• list_option_months This function will generate the options to use in a select element which a list of months and their numeric values with a leading zero.
• list_option_card_years This function will generate the options to use in a select element for selection of year (expiration year for credit cards). The first year returned is the current year and you can select how many years to return (defaults to 16).

Done

If you have any questions regarding how to use this API or if you think something could be improved / added, please comment below.