Payment Library Creation Guide

Developers are able to create new payment gateways that work seamlessly with the ReceivePay system. This guide will provide a broad overview of how to do this.

This guide is intended for intermediate/advanced PHP developers. It will explain the ReceivePay requirements for a payment gateway. However, it should be noted that the gateway you are attempting to integrate will have its own procedure for communicating with their payment systems. You will require API/integration documentation for the payment gateway. A knowledge of working with XML and SOAP may be required, depending on the gateway's API.

Each gateway is a simple combination of a single PHP class library stored at /system/ReceivePay/libraries/payment/ and a single database table entry registering the gateway.

It is highly suggested that you take a look at at least one current gateway file to understand how gateway integrations work.

Database Requirements

In order for a payment gateway to be recognized, you must add a new record entry in the external_apis table. The table has the following fields:

Field	Description
name	The system name for the payment gateway. This must be a single word and may not contain any spaces.
display_name	The name as displayed within the interface.
prod_url	The URL gateway requests are sent to non-recurring Charges in production/live mode.
test_url	The URL gateway requests are sent to non-recurring Charges in test mode.
dev_url	The URL gateway requests are sent to non-recurring Charges in development mode.
arb_prod_url	The URL gateway requests are sent to Recurring Charges in production/live mode.
arb_test_url	The URL gateway requests are sent to Recurring Charges in test mode.
arb_dev_url	The URL gateway requests are sent to Recurring Charges in test mode.

Only the name and display_name fields are required. However, most gateways stored the API endpoint URLs for their gateway in this table, as opposed to hard-coding them into the PHP library file.

File Location

The gateway class library file is located at /system/ReceivePay/libraries/payment/. The name of the file should match the name entered in the database.

Payment Class Structure

The gateway file will contain a single class, sharing the same name as the name entry in the database.

It must have a public attribute variable called $settings.

At this point, your class should look something like below.

class my_gateway {

	var $settings;
	
	function __construct() 
	{
		$this->settings = $this->Settings();
	}

	function Settings () {
		$this->settings = array();
	}
}
				

Required Methods

There are 5 methods that are required for the gateway to function.

void Settings() - Returns an array of all settings for the gateway. This is a highly structured array. More information below.

boolean TestConnection() - Called when the client attempts to setup the gateway. Should attempt a connection with the gateway and verify that the client information is correct.
Parameters:

• int $client_id - An int with the client's ID.
• int $gateway - An array with the gateway information. (See below).

Returns:

array Charge() - Handles a single, non-recurring charge.
Parameters:

• int $client_id - An int with the client's ID.
• int $order_id - An int with the order's ID.
• array $gateway - An array with the gateway information. (See below).
• array $customer - An array with the customer's information. (See below).
• float $amount - The total amount to charge.
• array $credit_card - An array with the credit card information that will be used.

array Recur() - Called when an initial Recur charge comes through to create a subscription.
Parameters:

• int $client_id - An int with the client's ID.
• array $gateway - An array with the gateway information. (See below).
• array $customer - An array with the customer information. (See below).
• float $amount - The total amount to charge.
• boolean $charge_today - Whether the card should be charged when the subcription is first created.
• string $start_date - The day the subscription should start.
• string $end_date - The day the subscription should end.
• int $interval - The number of days between subscription charges.
• string $credit_card - An array with the credit card information. (See below).
• int $subscription_id - An int with the subscription's ID.
• int$total_occurences - FALSE or an int with the total number of charges.

boolean AutoRecurringCharge() - Called whenever a subscription should be charged after the initial creation.
Parameters:

• int $client_id - An int with the client's ID.
• int $order_id - An in with the order's ID.
• array $gateway - An array with the gateway's information. (See below).
• array $params - An array of extra information.

array CancelRecurring() - Called whenever a subscription is cancelled. If your gateway doesn't support API-driven cancellations, just return TRUE.
Parameters:

• int $client_id - An int with the client's ID.
• array $subscription - An array with the subscription information. (See below).

boolean UpdateRecurring() - Called when the client needs to change their subscription information. If your gateway doesn't support API-driven updates, just return FALSE.
Parameters:

• int $client_id - An int with the client's ID.
• array $gateway - An array with the gateway's information. (See below).
• array $subscription - An array with the subscription's information. (See below).
• array $customer - An array with the customer's information. (See below).
• array $params - An array of extra information.

Settings Array

The following array contains the required information that each gateway must specify.

• string name - The system name of the gateway. Can not contain spaces.
• string class_name - The name of the gateway class.
• boolean external - Set to TRUE if the gateway redirects to an external checkout, else FALSE.
• boolean no_credit_card - Set to TRUE if the gateway Charge and Recur requests require credit card information in a credit_card node.
• string description - The description that shows up in the gateway selection screen.
• int is_preferred - Set to TRUE.
• string setup_fee - The dollar amount to setup an account. Shown in the gateway selection screen.
• string monthly_fee - The monthly fee the account costs. Shown in the gateway selection screen.
• string transaction_fee - The amount charged per transaction. Shown in the gateway selection screen.
• string purchase_link - The URL to visit to sign up for an account. Shown in the gateway selection screen.
• int allows_updates - If 0, the gateway API does not support updating client/subscription information. If 1, it does support it.
• int allows_refunds - If 0, the gateway API does not support refunding charges. If 1, it does support it.
• int requires_customer_information - Set to TRUE if the Charge and Recur requests require either a customer_id or a complete customer node for a proper request.
• int requires_customer_ip - If 1, the customer's IP address is made available to pass to the gateway.
• array required_fields - An array of values that hold the information you will request during gateway setup. You can create any values you like here, but there are 2 required values:
  • enabled
  • mode
• array field_details - A multidimensional array that holds the details of the required fields.

Field Detail Array

Each item in the field_details array must specify the type, title and options available during setup. We will use the enabled and mode fields to demonstrate the proper format:

'enabled' => array(
	'text' => 'Enable this gateway?',
	'type' => 'radio',
	'options' => array(
		'1' => 'Enabled',
		'0' => 'Disabled')
),
'mode' => array(
	'text' => 'Mode',
	'type' => 'select',
	'options' => array(
		'live' => 'Live Mode',
		'test' => 'Test Mode',
		'dev' => 'Development Server'
	)
)
				

The following keys are available to use in the field_detail arrays:

• string text - The name that is displayed in the gateway setup screen.
• string type - The type of field shown. Valid values are: radio, select, and text.

If the field type contains options, like an HTML radio group, or select dropdown, the options array must also be supplied. In the options array, the key represents the value, while the value represents the text to display on the page.

Common Parameter Arrays

The following arrays are used in many of the required methods, above.

$gateway - Any additional array elements specified in the settings array are also included in this array.

• string url_live
• string url_test
• string url_dev
• string arb_url_live
• string arb_url_test
• string arb_url_dev
• string name
• string alias
• int enabled
• int gateway_id
• string mode
• int customer_id

$customer

• int id - Int with the customer's ID.
• int internal_id
• string first_name
• string last_name
• string company
• string address_1
• string address_2
• string city
• string state - 2-digit state abbreviation
• string postal_code
• string country - 2-digit country code
• string email
• string phone

$credit_card

• string name - Full name on credit card.
• string card_num
• int exp_month - 2-digit month
• int exp_year - 4-digit year
• int cvv - 3-digit card verification code
• string card_type

$subscription

• int subscription_id
• int client_id
• int gateway_id
• int customer_id
• int plan_id
• string notification_url - The URL to return to after gateway charges.
• string start_date - YYYY-MM-DD
• string end_date - YYYY-MM-DD
• string last_charge - YYYY-MM-DD
• string next_charge - YYYY-MM-DD
• int number_charge_failures
• int number_occurrences
• int charge_interval
• float amount
• string card_last_four
• string api_customer_reference
• string api_payment_refernce
• string api_auth_number
• int active
• int renewed
• int updated
• string cancel_date - YYYY-MM-DD HH:MM:SS
• string timestamp
• int client_gateway_id
• int external_api_id
• string alias
• int enabled
• int deleted
• string create_date - YYYY-MM-DD
• string name
• string display_name
• string prod_url
• string test_url
• string dev_url
• string arb_prod_url
• string arb_test_url
• string arb_dev_url

Example Flows

There are two primary types of gateways, as far as the application flow is concerned.

Internal Processors

Internal processors allow the user to enter their payment information on your site. ReceivePay can support this category.

External Processors

External processors require the user to fill out the form on their site, and then redirect the user back to your site, where the processing is completed within ReceivePay. ReceivePay can support this example.