The model contains all of the gateway specific code. It must follow the correct naming conventions and contain certain mandatory functions.
Gateway models extend the Payage Account model. In Payage, an account is an instance of a gateway. An account corresponds to the site administrator's account with the gateway and includes any specific information that the gateway code needs to access the account, usually its email address, and sometimes other identity parameters. The Payage Account model includes several fields commonly required for accessing gateway accounts, but implementing a new gateway may require additional, specific items. This is achieved by storing the specific fields as serialised data. Gateway models access their specific fields as "specific_data", and the common fields as "common_data".
The model file must be named
The model must declare a class as follows:
class PayageModel<type> extends PayageModelAccountWhere
The model must define the following public functions:
| Function | Description |
|---|---|
| initData() | Calls its parent function and initialise any "specific_data" fields required. |
| check_post_data() | Validates any "specific_data" fields when saved by the account configuration form. |
| getPostData() | Retrieves any "specific_data" fields from the Post data. |
| Gateway_handle_request() | Handles an incoming request from the payment gateway. More details below. |
| Gateway_make_button() | Generates a payment button in response to a get_payment_buttons() API call. |
| Gateway_test() | Optional but recommended. If this function exists, a "Test" button appears on the account edit screen, which the user can use to verify that his server can connect to the gateway. This can help users to solve some connectivity issues without support. |
| Gateway_activate() | Optional. If present it is called when the account is published, unpublished, or deleted. |
This function is called by the payment gateway after a payment has been made, and possibly also for any subsequent updates. For example, when we build a payment button for PayPal, three different callback URL's are generated:
$return_url = JURI::root().'index.php?option=com_payage&task=return&aid='.$this->common_data->id.
'&tid='.$payment_data->pg_transaction_id.'&tmpl=component&format=raw';
$cancel_url = JURI::root().'index.php?option=com_payage&task=cancel&aid='.$this->common_data->id.
'&tid='.$payment_data->pg_transaction_id.'&tmpl=component&format=raw';
$notify_url = JURI::root().'index.php?option=com_payage&task=notify&aid='.$this->common_data->id.
'&tid='.$payment_data->pg_transaction_id.'&tmpl=component&format=raw'; Payage uses the "aid" to route the request to the Gateway_handle_request() function of the correct model. The Gateway_handle_request() function uses the "task" to action the request. The gateways use different tasks. Every gateway is different.
All gateways need a 'return' function (although it doesn't have to be called 'return'). There needs to be a function that safely and securely validates that the payment has been made, independently of any messages that could be received externally. The return function must also save all possible details of the payment in the payment record, including full copies of all messages received from the gateway. In some cases, proprietary objects need to be converted to standard objects. Stripe, BitPay and Authorize.Net are examples.
Remember that a single payment record is generated for a Payage Button Request, no matter how many buttons are returned. Initially, the unconfirmed payment does not have an 'account_id' or 'customer_fee' (if there is one) until the user has paid. In most cases the 'return' function needs to populate these items into the payment record.