The Gateway API is responsible for allowing your users to buy points for real money. These purchases are either done manually or using online payment processors, such as PayPal or Netbilling. To buy points, a user must select the amount of points they want to buy and the payment processor they want to use. You can select to use just one particular payment gateway or multiple and let the user decide which one they want to use.

myCred comes with several built-in gateways located in the mycred/add-ons/buy-creds/gateways/ folder.

The buyCred module handles your installed gateways, built-in or custom ones, manages your pending payments and logs of purchases. The module will construct and load a gateway in the front-end when:

• A logged in user visits any front-end page *.
• If a new purchase request is detected.
• If a Callback from a payment processor is detected.

* If the gateway needs to detect when a buyer returns to the website in order to process a payment (not using callback), the gateway will be loaded by buyCred on each front-end page load where the website is visited by someone who is logged in.

In order to buy points, four pieces of information needs to be submitted to the gateway API:

• The Amount of points to purchase
• The point type
• The gateway ID selected to handle the payment and
• A security token.

If the purchase is made as a gift, the recipients ID is also needed. Once the security token is verified, the requested gateway is constructed and the gateways buy() method is called upon to handle the purchase request. If the request is made by a user that is excluded or if the security token has expired, the gateway will not be loaded and the page will simply refresh.

Step 1.

A logged in user requests to purchase points using the mycred_buy or mycred_buy_form shortcodes.

Step 2.

The user clicks on the purchase link or submits the purchase form.

Step 3.

The request is validated and minimum amount is enforced. A pending payment is saved.

Step 4.

The checkout page is loaded to manage local payments or redirect to external servers.

The buyCRED add-on supports three types of payment gateways:

Local

The buyers payment information is collected locally and sent to the payment processor. The buyer never leaves your website.

Example: Netbilling

Remote

The buyer is redirected to an external payment processor where they pay and are redirected back to your website.

Example: PayPal

Manual

The user makes a purchase request but no payment information is collected. Payments are manually handled.

Example: Bank Transfer

Each gateway is a class based of the myCred_Gateway abstract class. A gateway class must have a constructor and the buy class method. All other methods are optional:

Basic buyCRED Gateway example.

First we need to construct our gateway using the myCred_Gateway class. This will register our gateway settings and apply defaults to existing settings.

While our class constructor only uses one variable; the gateway module settings, the parent constructor uses two:

• The Gateways arguments – This holds the gateways ID and settings.
• The buyCred add-on settings that were passed down.

Gateway Arguments

The following arguments are available for Gateways:

The buy() class method is called when a user makes a purchase request and this method is expected to parse the request, construct arguments needed for the payment processor and load the checkout page.

You can access your gateway settings using $this->prefs and the myCred_Gateway abstract class provides a large set of methods that you can access to help handle requests. Here are some of the most used methods:

Once a purchase request has been saved, we need to either collect a users payment details, show them how to complete their payment (manual gateways) or redirect them to the payment processor.

This is done using the “Checkout” page which is a page override that buyCRED generates before your theme’s style / page layout is loaded. This is mainly to prevent third-party conflicts and to prevent other scripts and styles from being used. In future versions of myCred, this might however change, and instead use a dedicated checkout page.

Structure

The checkout page is rendered using the get_page_header() and get_page_footer() class methods. The content part can either be added manually via your class or use one of the built-in content render methods:

Example: The Bank Transfer gateway inserts it’s own custom checkout page content.

Example: The PayPal gateway uses the built-in redirection on the checkout page.

Example showing how the buy() method in the gateway class can be used when a user needs to be redirected to a remote payment processor.

buyCRED Callbacks refer to the instances when a remote payment processor contacts your website in order to inform of updates regarding a pending payment, e.g. the payment being completed / captured. Callbacks are optional of course, if your gateway does not support it, you do not have to use it.

All callbacks have to use the proper callback identification, and you can use the callback_url() method to get this URL  for your gateway.

Once a valid callback is received, the gateway in question is loaded and the process() class method is called upon to handle the call. Most payment processors offer a callback or “postback” feature and how this call is processed varies.