---
title: 'API Functions'
url: 'https://manuals.remository.com/payage-dev/receiving-payments/api-functions'
markdown: 'https://manuals.remository.com/payage-dev/receiving-payments/api-functions.md'
date: '2026-11-14'
description: "The API functions are defined in the file api.php, which must be included before the functions are called. It is advisable to check that Payage is installed before calling the API. For example: if (!file_exists(JPATH_ADMINISTRATOR.'/components/com_payage/api.php')) { echo JText::_('COM_PA…"
taxonomy:
  category:
    - docs
---

[](#) [ edit this page](https://github.com/getgrav/grav-skeleton-rtfm-site/blob/develop/pages/04.receiving-payments/03.api-functions/docs.md) 

# API Functions

The API functions are defined in the file api.php, which must be included before the functions are called. It is advisable to check that Payage is installed before calling the API. For example:

```
if (!file_exists(JPATH_ADMINISTRATOR.'/components/com_payage/api.php'))
     {
     echo JText::_('COM_PAYAGE_TEST_NOT_INSTALLED');
     return;
     }
require_once JPATH_ADMINISTRATOR.'/components/com_payage/api.php';
```

## get\_buttons($call\_array, &$html)

This function returns a complete HTML structure that renders all relevant buttons according to the selected layout. A parameter array supplies the information required for Payage to select the required accounts and customise buttons for them. The currency and group are used to select the relevant accounts. The rest of the parameters are used to prepare the transaction and build the buttons.

Calling this function also loads the Payage front end CSS file, payage.css, which styles the buttons and the layouts. In some applications you might want to enclose the button HTML in a container element and constrain its width.

### Parameters

The $call\_array parameter is an associative array with the following elements. Mandatory elements are shown in bold, the rest are optional. The %...% shows the invoice variable name associated with the element.

| Element | Description |
|---|---|
| **currency** | The 3 character currency code for the accounts to be selected. |
| group | The account group to select accounts from. The default is 0 (zero) which selects from all published accounts. It is better to allow the administrator to configure the account group used by your application, so that the site administrator can assign different accounts for different purposes. |
| layout | The choices are as follows. The default is LAPG\_LAYOUT\_RIGHT. `LAPG_LAYOUT_INLINE` - Inline blocks that flow like characters `LAPG_LAYOUT_TABLE` - An HTML table `LAPG_LAYOUT_RIGHT` - Responsive table with buttons on the right `LAPG_LAYOUT_LEFT` - Responsive table with buttons on the left `LAPG_LAYOUT_ONE` - Just the first button `LAPG_LAYOUT_BOXED_NB` - Boxes without borders `LAPG_LAYOUT_BOXED_IB` - Boxes with borders `LAPG_LAYOUT_BOXED_OB` - Boxes with an outer border |
| **app\_name** | The name of the calling application as you wish it to appear in Payage's payment list. |
| app\_transaction\_id | Your application's transaction ID for this payment, if it has one. |
| app\_transaction\_details %APP\_xxxxx% | Any transaction data that you want to be stored in Payage with the payment. Can be plain text, an object or an array. Storing data here for a potential payment is better than using the Joomla session because the storage time is controlled by Payage ("Minutes to keep unconfirmed transactions"), and the data is visible in the Payage admin interface ("Unconfirmed Payments"). The %APP\_xxxxx% variable retrieves any scalar element, where the name is up to 21 characters long, for example app\_transaction\_details->xxxxx or app\_transaction\_details\['xxxxx'\]. |
| **item\_name** %PRODUCT% | The name of the item being purchased. This name is passed to the payment gateway as the item name, and is shown on Payage's payment list. |
| item\_id %PRODUCT\_ID% | This is stored in the Payage payment and where possible passed to payment gateways as the product ID or SKU. |
| item\_description %PRODUCT\_DESCRIPTION% | This is stored in the Payage payment and where possible passed to payment gateways as the product description. |
| **gross\_amount** %PRICE% | In most cases this is the gross amount to collect, including tax. For gateways that implement dynamic tax based on customer location, this can be the net amount or the gross amount depending on the gateway. Must be greater than zero. |
| tax\_amount %TAX% | The tax amount for the transaction. Cannot be negative. |
| tax\_id %TAX\_ID% | The buyer's VAT or other tax ID, if the application has it. |
| tax\_id\_status | The verification status of the buyer's tax ID. Up to 255 characters. For example "Unconfirmed: Vies error xxxxxxx", or "Confirmed by Vies", etc. |
| tax\_exempt %TAX\_EXEMPT% | Sets the tax\_exempt indicator on the payment. Tax exempt payments do not allow the buyer to change their tax ID when requesting an invoice. |
| tax\_type %TAX\_TYPE% | A description of the tax type used in the tax calculation, typically the country name or the country specific tax name. |
| tax\_rate %TAX\_RATE% | The tax rate as a percentage, e.g. 19.5 |
| firstname | The buyer's first name, if the application has it. All the name and address items are stored in the Payage payment and where possible passed to the payment gateways. |
| lastname | The last name of the client, if the application has it. |
| email | The client's email address, if the application has it. |
| address1 | First line of the client's address, if the application has it. |
| address2 | Second line of the client's address, if the application has it. |
| city | The client's city, if the application has it. |
| state | The client's state, if the application has it. |
| zip\_code | The client's zip code, if the application has it. |
| country\_code | The client's two character billing country code, if the application has it. |
| country | The client's billing country name, if the application has it. If country\_code is specified and country is not, Payage will populate the country element. |
| ip\_country\_code | The country code of the IP address, if the application has it. |
| ip\_country | The country name of the IP address, if the application has it. |
| **app\_return\_url** | A URL within your application that Payage will redirect to after all payment processing is completed. This URL will be activated by the user's browser after payment. The return\_url will be called with an additional URL parameter 'tid', being the Payage transaction ID for the payment. The tid must be used with the get\_payment\_data() API call to retrieve full details of the payment transaction. The URL should include the site language on multi-language sites. |
| app\_update\_path | A PHP file within your application that contains a payment\_update() function. If Payage receives an update to the status of a payment, for example a Webhook or a PayPal IPN notification, it will load this file and call the payment\_update() function, passing the tid as described above. |
| button\_extra | Any additional attributes to be added to the image payment buttons, for example class="hasTip". Not used for responsive buttons. |
| max\_buttons | The maximum number of buttons to return. If zero or unspecified, all matching buttons are returned. |

### Example

```
require_once JPATH_ADMINISTRATOR.'/components/com_payage/api.php';
$call_array['currency'] = 'GBP';
$call_array['layout'] = LAPG_LAYOUT_LEFT;
$call_array['app_name'] = 'Payage_Test';
$call_array['gross_amount'] = 2.50;
$call_array['app_return_url'] = JURI::root(true).
         '/index.php?option=com_payage_test&task=payment_complete';
$return_status = PayageApi::get_buttons($call_array, $html);
```

### Return Values

The return values are:

| Value | Meaning |
|---|---|
| 0 | Success. One or more payment buttons was returned in the $html parameter. |
| 1 | No published accounts matched the currency and group number supplied |
| 2 | Called with empty or invalid currency |
| 3 | Called with no app\_name |
| 4 | Called with no gross\_amount or gross\_amount < 0 |
| 5 | Called with empty app\_return\_url or app\_return\_url length > 255 characters |
| 6 | Failed to store the payment in the database. The \['error'\] element contains further details |
| 7 | Called with tax\_amount > gross\_amount |

In the error cases, the $html parameter contains a technical error message that is not intended for end users. The application should log the error privately and show a friendly message to the user indicating that payment is temporarily unavailable.

In the success case, the HTML layout is returned in the $html parameter, and all the necessary CSS and Javascript has been added to the Joomla document.

### The Return Callback (app\_return\_url)

When a payment completes, Payage performs all the necessary processing to determine the validity and status of the transaction. It then redirects the user's browser to the app\_return\_url that you specify. It adds an additional URL parameter: 'tid', being the Payage transaction ID for the payment. The tid must then be used with the get\_payment\_data() call to retrieve full details of the payment transaction.

It is important to be aware that malicious users may also attempt to call this URL in an attempt to avoid payment or seek some other vulnerability so the application must validate calls thoroughly and not perform any processing for invalid calls.

### The Update Callback (app\_update\_path)

When a payment update occurs, for example when a Pending payment clears, Payage will call the application's payment\_update() function, passing the same tid parameter as above. This function should be declared as follows.

```
function payment_update($tid)
{
}
```

This function should be a stand-alone function, not a method of a class, and the file it is defined in should not contain any other functions or code. See the Payage\_Test component for an example.

In normal operation the file containing the payment\_update() function will be loaded in the context of the front end of Payage, so be careful when using Joomla constants such as JPATH\_COMPONENT\_ADMINISTRATOR as they may not contain the values you might expect. Also note that the language file for your component will not be loaded automatically. If you need it, you will have to load it explicitly.

It is difficult to test the payment\_update() function using live calls from a payment gateway as any PHP errors that occur will be invisible. For initial testing, it is best to make status changes to a payment in the Payage administration user interface. The payment\_update() function is then called in the context of the Payage administrator component and any errors should be visible in the normal way.

## get\_layouts()

Returns an array of button layout options and their names translated by the Payage language file. You can use this call to build a list of layouts that the administrator configuring your application can choose from.

## get\_payment\_buttons($call\_array)

For most purposes this function has been superceded by get\_buttons(), but it is still available and will not be removed. It returns an array of payment buttons that need to be organised into an HTML layout. The $call\_array parameter has the same structure as for the get\_buttons() function, except that the layout element is not used or required.

You might want to use this function if you need to present the payment buttons in a layout not supported by the get\_buttons() function.

Calling this function also loads the Payage front end CSS file, payage.css, which styles the buttons, especially the responsive buttons.

### Example

```
require_once JPATH_ADMINISTRATOR.'/components/com_payage/api.php';
$call_array['currency'] = 'GBP';
$call_array['app_name'] = 'Payage_Test';
$call_array['gross_amount'] = 2.50;
$call_array['app_return_url'] = JURI::root(true).
         '/index.php?option=com_payage_test&task=payment_complete';
$return_array = PayageApi::get_payment_buttons($call_array);
```

### Return Values

This function returns an array, which always contains an element \[0\]\['status'\] and an element \[0\]\['error'\].

The calling application should always test the value of element \[0\]\['status'\] to determine the success or failure of the call. The status values are as listed above for the get\_buttons() function.

When element \[0\]\['status'\] is non-zero, element \[0\]\['error'\] contains the English description of the error. These error descriptions are technical and should not be displayed to end users.

When element \[0\]\['status'\] is zero, element \[0\]\['error'\] contains an empty string, element \[0\]\['transaction\_id'\] contains the Payage transaction ID, and elements \[1\] to \[N\] contain information about one or more payment buttons, with each element containing the following elements:

| Element | Description |
|---|---|
| \['type'\] | The short name of the gateway type, e.g. "PayPal". |
| \['button'\] | The complete html for the payment button. |
| \['description'\] | The account description, which you may wish to display with the button. The administrator configures this description as part of the Payage account, for example, "Click here to pay securely with PayPal". |
| \['fee'\] | The additional fee that the user will be charged for using this payment method. Payage allows administrators to configure different fee structures for each account, so the fee for using each button may be different. You may want to display the fee with the button. |
| \['status'\] | Normally this element contains 0. If the payment button cannot be generated due to a gateway specific error, this element contains a gateway specific error code. |
| \['error'\] | Normally this element contains an empty string. If the payment button cannot be generated due to a gateway specific error, this element contains the English description of the error. |

## get\_payment\_data($index, $field='pg\_transaction\_id')

This call retrieves the payment record held by Payage. The application's app\_return\_url and payage\_payment\_update() functions will both need to use this call.

Using this API call is better than accessing the #\_\_payage\_payments table directly because it will isolate the application from future structural changes. It also provides the account\_name and gateway\_shortname fields by joining to the #\_\_payage\_accounts table. However this call can only be used to retrieve data for a single transaction. If you want to provide more extensive access to payment data within your application, you will have to access the Payage database tables directly.

### Parameters

| Parameter | Description |
|---|---|
| index | Normally this should be the Payage transaction ID (tid) |
| field | If the first parameter is the Payage transaction ID, this parameter may be omitted. This second parameter may be used to name any other column of the #\_\_payage\_payments table to be used for the lookup. You could use the "app\_transaction\_id" column, for example. |

### Return Values

The return value is a StdClass object containing the payment data, or the value false if the transaction was not found. The properties of interest are:

| Property | Description |
|---|---|
| date\_time\_initiated | Date-time the payment button was requested using the get\_payment\_buttons() function. |
| date\_time\_updated | The last time the payment was updated. |
| pg\_transaction\_id | The Payage transaction id |
| pg\_status\_code | The Payage status code |
| pg\_status\_text | The Payage status text |
| pg\_history | The plain text history of updates to the payment record |
| app\_name | The app\_name submitted with get\_payment\_buttons() |
| app\_item\_name | The item\_name submitted with get\_payment\_buttons() |
| app\_return\_url | The return\_url submitted with get\_payment\_buttons() |
| app\_update\_url | The update\_url submitted with get\_payment\_buttons() |
| app\_transaction\_id | The transaction\_id submitted with get\_payment\_buttons() |
| app\_transaction\_details | The transaction\_details submitted with get\_payment\_buttons() |
| gw\_transaction\_id | The payment gateway's transaction id, if there is one |
| gw\_pending\_reason | If the payment is pending, this field may contain the reason, if the gateway supplies this information. |
| gw\_transaction\_details | More details retrieved from the payment gateway, serialised using the PHP serialize() function. The details supplied are different for each gateway. |
| currency | The currency submitted with get\_payment\_buttons() |
| gross\_amount | The gross\_amount submitted with get\_payment\_buttons() |
| tax\_amount | The tax\_amount submitted with get\_payment\_buttons() |
| customer\_fee | The fee charged to the customer as calculated by Payage according to the account configuration and added to the gross\_amount before payment. |
| gateway\_fee | The fee charged by the gateway, if any, and if available |
| payer\_email | The payer's email address, if this is supplied by the gateway |
| payer\_first\_name | The payer's first name, if this is supplied by the gateway |
| payer\_last\_name | The payer's last name, if this is supplied by the gateway |
| payer\_country | The payer's country, if this is supplied by the gateway |
| account\_name | The name of the Payage account name that was used |
| gateway\_name | The shortname of the gateway that was used |
| processed | An integer that you can set using the Set\_Payment\_Processed() API call. Unless you change it, its value is 0. |

The status code is defined as follows:

```
define("LAPG_STATUS_NONE",     0); // button has been created 
define("LAPG_STATUS_SUCCESS",  1); // payment was made successfully
define("LAPG_STATUS_PENDING",  2); // the payment was made but is uncleared
define("LAPG_STATUS_FAILED",   3); // payment failed to verify
define("LAPG_STATUS_CANCELLED",4); // user clicked cancel at the payment gateway 
define("LAPG_STATUS_REFUNDED", 5); // manually refunded in Payage
```

## set\_payment\_processed($transaction\_id, $value)

Sets the value of the "processed" field for a payment. You can use this to prevent processing a payment more than once.

The "processed" field is not used by Payage, so you can use it for any purpose you wish. You could, for example, set it to the transaction status that has been processed, for example "2" for a pending transaction, and "1" when the transaction changes to success.

### Parameters

| Parameter | Description |
|---|---|
| transaction\_id | The Payage transaction id |
| value | The value to be set |

### Example

```
require_once JPATH_ADMINISTRATOR.'/components/com_payage/api.php';
$status = PayageApi::set_payment_processed($tid, $new_value);
```

### Return Values

Returns true if the operation succeeded, or false if not. If false, an entry is logged to the Payage System Log.

## set\_app\_transaction\_id($transaction\_id, $value)

Sets the "app\_transaction\_id" field for a payment. In some cases, the application might not generate its own transaction ID until after payment, and so cannot supply it to the get\_payment\_buttons() call. This call lets you set it later.

### Parameters

| Parameter | Description |
|---|---|
| transaction\_id | The Payage transaction id |
| value | The value to be set |

### Example

```
require_once JPATH_ADMINISTRATOR.'/components/com_payage/api.php';
$status = PayageApi::set_app_transaction_id($tid, $transaction_id);
```

### Return Values

Returns true if the operation succeeded, or false if not. If false, an entry is logged to the Payage System Log.

## change\_payment\_state($transaction\_id, $status, $app\_name)

Changes the status of a payment and writes a note to the notes column.

### Parameters

| Parameter | Description |
|---|---|
| transaction\_id | The Payage transaction id |
| status | The numeric Payage payment state, as defined above. |
| app\_name | The application name, to be used when adding the note to the notes column. |

### Example

```
require_once JPATH_ADMINISTRATOR.'/components/com_payage/api.php';
$status = PayageApi::change_payment_state($tid, $new_status, 'MediaShop');
```

### Return Values

Returns true if the operation succeeded, or false if not. If false, an entry is logged to the Payage System Log.

## get\_status\_description($status)

Returns a translated text description of a supplied payment status code, using the language files of the com\_payage component.

### Parameters

| Parameter | Description |
|---|---|
| status | The numeric Payage payment state, as defined above. |

### Example

```
require_once JPATH_ADMINISTRATOR.'/components/com_payage/api.php';
$status = PayageApi::get_status_description($payment_data->pg_status_code);
```

### Return Values

The return value is the status code description, or (translated) "Unknown status".

## get\_currencies($group)

Returns an array containing a list of all the currency codes for which published gateway accounts exist.

### Parameters

| Parameter | Description |
|---|---|
| group | The account group to get the list of currencies for. Zero (0) means all groups.. |

### Example

```
require_once JPATH_ADMINISTRATOR.'/components/com_payage/api.php';
$status = PayageApi::get_currencies(0);
```

### Return Values

An array of name/value pairs with both the name and value set to the currency code:

```
['EUR'] => 'EUR'
['GBP'] => 'GBP'
```

If there are no accounts for the specified group, an empty array is returned.

## get\_groups($include\_all)

Returns an array containing a list of all the group numbers for which published gateway accounts exist.

### Parameters

| Parameter | Description |
|---|---|
| include\_all | If true, includes group 0 as the first entry in the array. |

### Example

```
require_once JPATH_ADMINISTRATOR.'/components/com_payage/api.php';
$status = PayageApi::get_groups(true);
```

### Return Values

Each element of the array is a name/value pair with both the name and value set to the group number:

```
[0] => 0
[1] => 1
```

If there are no accounts, an empty array is returned.

## get\_version()

Gets the installed version of Payage.

### Parameters

None.

### Example

```
require_once JPATH_ADMINISTRATOR.'/components/com_payage/api.php';
    $version = PayageApi::get_version();
    if (version_compare($version,"2.12","<"))
         {
         echo "This application requires at least version 2.12 of Payage!";
         return false;
         }
```

### Return Values

The version number of the currently installed version of Payage.

## get\_invoice\_link($tid = null)

Searches the Joomla menu system for a Payage Invoice Request menu item. If one exists, the link is returned, including the "tid" parameter if supplied.

### Parameters

| Parameter | Description |
|---|---|
| tid | Optional: Payage transaction ID |

### Example

```
require_once JPATH_ADMINISTRATOR.'/components/com_payage/api.php';
$link = PayageApi::get_invoice_link('425c95d87603106f024fc8707f068626');
```

### Return Values

For example:

```
https://www.mysite.com/invoices?tid=425c95d87603106f024fc8707f068626
```

 [ ](https://manuals.remository.com/payage-dev/receiving-payments/sample-code) [](https://manuals.remository.com/payage-dev/receiving-payments/timeouts)

---

## Navigation

- Parent: [Receiving Payments](https://manuals.remository.com/payage-dev/receiving-payments.md)
- Previous: [Sample Code](https://manuals.remository.com/payage-dev/receiving-payments/sample-code.md)
- Next: [Timeouts](https://manuals.remository.com/payage-dev/receiving-payments/timeouts.md)