Transactions extends AppModel
Transaction management
Table of Contents
Properties
| $float_precision |
Methods
| __construct() | Initialize Transactions |
| add() | Adds a transaction to the system |
| addType() | Adds a transaction type |
| apply() | Applies a transaction to a list of invoices. Each invoice must be in the transaction's currency to be applied |
| applyFromCredits() | Applies available client credits in the given currency to all open invoices, starting from the oldest. |
| delete() | Permanently removes a transaction from the system |
| deleteType() | Delete a transaction type and update all affected transactions, setting their type to null |
| edit() | Updates a transaction |
| editType() | Updates a transaction type |
| get() | Retrieves a transaction and any applied amounts |
| getApplied() | Returns all invoices that have been applied to this transaction. Must supply either a transaction ID, invoice ID or both. |
| getByTransactionId() | Retrieves a transaction and any applied amounts |
| getCreditedAmount() | Returns the amount of payment for the given transaction ID that is currently available as a credit |
| getCredits() | Returns the amount of payment for the given client ID that is currently available as a credit for each currency |
| getDebitTypes() | Retrieves a set of key/value pairs representing transaction debit types and language |
| getList() | Retrieves a list of transactions and any applied amounts for the given client |
| getListCount() | Returns the total number of transactions for a client, useful in constructing pagination for the getList() method. |
| getSearchCount() | Return the total number of transactions returned from Transactions::search(), useful in constructing pagination |
| getSimpleList() | Retrieves a list of all transactions in the system |
| getStatusCount() | Retrieves the number of transactions given a transaction status type for the given client |
| getTotalCredit() | Retrieves the total credit amount available to the client in the given currency |
| getType() | Retrieves a single payment type |
| getTypes() | Retrieves a list of all transaction types |
| search() | Search transactions |
| transactionStatusNames() | Retrieves all transaction status values and their name in key/value pairs |
| transactionTypeNames() | Retrieves all transaction types and their name in key=>value pairs |
| unApply() | Unapplies a transactions from one or more invoices. |
| validateApplyAmounts() | Validates whether the given amounts can be applied to the given invoices, or if the amounts would exceed the amount due on the invoices. Also ensures the invoices can have amounts applied to them. |
| validateCurrencyAmounts() | Validates whether the invoice amounts being applied are in the transaction's currency |
| validatePositiveAmounts() | Validates whether each of the given amounts is greater than or equal to zero |
| validateStatus() | Validates a transaction's 'status' field |
| validateType() | Validates a transaction's 'type' field |
| verifyApply() | Verifies that transaction can be applied to a list of invoices |
| getCreditApplyAmounts() | Creates a list of credits to be applied to invoices for each transaction |
| getCurrencyPrecision() | Retrieves the decimal precision for the given currency |
| getTransaction() | Returns a partially built query Record object used to fetch a single transaction |
| getTransactionRules() | Returns the rule set for adding/editing transactions |
| getTransactions() | Partially constructs the query required by Transactions::getList() and Transactions:getListCount() |
| getTypeRules() | Returns the rule set for adding/editing transaction types |
| searchTransactions() | Partially constructs the query for searching transactions |
Methods
__construct()
Initialize Transactions
public
__construct() : mixed
add()
Adds a transaction to the system
public
add(array<string|int, mixed> $vars) : int
Parameters
- $vars : array<string|int, mixed>
-
An array of tax info including:
- client_id The client ID this transaction applies to.
- amount The transaction amount
- currency The currency code of this transaction
- type The transaction type (cc, ach, other)
- transaction_type_id The transaction type ID (optional, default NULL)
- account_id The account ID (optional, default NULL)
- gateway_id The gateway ID (optional, default NULL)
- transaction_id The gateway supplied transaction ID (optional, default NULL)
- parent_transaction_id The gateway supplied parent transaction ID (optional, default null)
- reference_id The gateway supplied reference ID (optional, default NULL)
- message The message returned by the gateway (optional, default NULL)
- status The transaction status (optional, default 'approved')
- date_added The date the transaction was received (optional, defaults to current date)
Return values
int —The ID of the transaction created, void on error
addType()
Adds a transaction type
public
addType(array<string|int, mixed> $vars) : int
Parameters
- $vars : array<string|int, mixed>
-
An array of transaction types including:
- name The transaction type name
- type The transaction debit type ('debit' or 'credit')
- is_lang Whether or not the 'name' parameter is a language definition 1 - yes, 0 - no (optional, default 0)
Return values
int —The transaction type ID created, or void on error
apply()
Applies a transaction to a list of invoices. Each invoice must be in the transaction's currency to be applied
public
apply(mixed $transaction_id, array<string|int, mixed> $vars) : mixed
Parameters
- $transaction_id : mixed
- $vars : array<string|int, mixed>
-
An array of transaction info including:
- date The date in local time (Y-m-d H:i:s format) the transaction was applied (optional, default to current date/time)
- amounts A numerically indexed array of amounts to apply including:
- invoice_id The invoice ID
- amount The amount to apply to this invoice (optional, default 0.00)
applyFromCredits()
Applies available client credits in the given currency to all open invoices, starting from the oldest.
public
applyFromCredits(int $client_id[, string $currency = null ][, array<string|int, mixed> $amounts = [] ]) : mixed
If specific amounts are specified, credits will only be applied to the invoices given.
Parameters
- $client_id : int
-
The ID of the client whose invoices to apply from credits
- $currency : string = null
-
The ISO 4217 3-character currency code. Must be set if $amounts are specified (optional, null will apply from all currencies; default null)
- $amounts : array<string|int, mixed> = []
-
A numerically-indexed array of specific amounts to apply to given invoices:
- invoice_id The invoice ID
- amount The amount to apply to this invoice (optional, default 0.00)
Return values
mixed —Void, or an array indexed by a credit's transaction ID, containing the amounts that were actually applied, including:
- invoice_id The invoice ID
- amount The amount that was applied to this invoice
delete()
Permanently removes a transaction from the system
public
delete(int $transaction_id) : mixed
Parameters
- $transaction_id : int
-
The transaction ID to remove
deleteType()
Delete a transaction type and update all affected transactions, setting their type to null
public
deleteType(int $type_id) : mixed
Parameters
- $type_id : int
-
The ID for this transaction type
edit()
Updates a transaction
public
edit(int $transaction_id, array<string|int, mixed> $vars[, int $staff_id = null ]) : int
Parameters
- $transaction_id : int
-
The transaction ID
- $vars : array<string|int, mixed>
-
An array of tax info including:
- amount The transaction amount (optional)
- currency The currency code of this transaction (optional)
- type The transaction type (cc, ach, other) (optional)
- transaction_type_id The transaction type ID (optional, default NULL)
- account_id The account ID (optional, default NULL)
- gateway_id The gateway ID (optional, default NULL)
- transaction_id The gateway supplied transaction ID (optional, default NULL)
- parent_transaction_id The gateway supplied parent transaction ID (optional, default null)
- reference_id The reference ID (optional, default NULL)
- message The message returned by the gateway (optional, default NULL)
- status The transaction status (optional, default 'approved')
- date_added The date the transaction was received (optional, defaults to current date)
- $staff_id : int = null
-
The ID of the staff member that made the edit for logging purposes
Return values
int —The ID of the transaction created, void on error
editType()
Updates a transaction type
public
editType(int $type_id, array<string|int, mixed> $vars) : mixed
Parameters
- $type_id : int
-
The type ID to update
- $vars : array<string|int, mixed>
-
An array of transaction types including:
- name The transaction type name
- type The transaction debit type ('debit' or 'credit')
- is_lang Whether or not the 'name' parameter is a language definition 1 - yes, 0 - no (optional, default 0)
get()
Retrieves a transaction and any applied amounts
public
get(int $transaction_id) : mixed
Parameters
- $transaction_id : int
-
The ID of the transaction to fetch (that is, transactions.id NOT transactions.transaction_id)
Tags
Return values
mixed —A stdClass object representing the transaction, false if it does not exist
getApplied()
Returns all invoices that have been applied to this transaction. Must supply either a transaction ID, invoice ID or both.
public
getApplied([int $transaction_id = null ][, int $invoice_id = null ]) : array<string|int, mixed>
Parameters
- $transaction_id : int = null
-
The ID of the transaction to fetch
- $invoice_id : int = null
-
The ID of the invoice to filter applied amounts on
Return values
array<string|int, mixed> —An array of stdClass objects representing applied amounts to invoices
getByTransactionId()
Retrieves a transaction and any applied amounts
public
getByTransactionId(int $transaction_id[, int $client_id = null ][, int $gateway_id = null ]) : mixed
Parameters
- $transaction_id : int
-
The ID of the transaction to fetch (that is, transactions.transaction_id NOT transactions.id)
- $client_id : int = null
-
The ID of the client to fetch a transaction for
- $gateway_id : int = null
-
The ID of the gateway used to process the transaction
Tags
Return values
mixed —A stdClass object representing the transaction, false if it does not exist
getCreditedAmount()
Returns the amount of payment for the given transaction ID that is currently available as a credit
public
getCreditedAmount(int $transaction_id) : float
Parameters
- $transaction_id : int
-
The ID of the transaction to fetch a credit value for
Return values
float —The amount of the transaction that is currently available as a credit
getCredits()
Returns the amount of payment for the given client ID that is currently available as a credit for each currency
public
getCredits(int $client_id[, string $currency = null ]) : array<string|int, mixed>
Parameters
- $client_id : int
-
The ID of the client to fetch a credit value for
- $currency : string = null
-
The ISO 4217 3-character currency code (optional)
Return values
array<string|int, mixed> —A list of credits by currency containing:
- transaction_id The transaction ID that the credit belongs to
- credit The total credit for this transaction
getDebitTypes()
Retrieves a set of key/value pairs representing transaction debit types and language
public
getDebitTypes() : array<string|int, mixed>
Return values
array<string|int, mixed> —An array of key/value pairs representing transaction debit types and their names
getList()
Retrieves a list of transactions and any applied amounts for the given client
public
getList([int $client_id = null ][, string $status = 'approved' ][, int $page = 1 ][, array<string|int, mixed> $order_by = ['date_added' => 'DESC'] ][, array<string|int, mixed> $filters = [] ]) : array<string|int, mixed>
Parameters
- $client_id : int = null
-
The client ID (optional, default null to get transactions for all clients)
- $status : string = 'approved'
-
The status type of the transactions to fetch (optional, default 'approved') - 'approved', 'declined', 'void', 'error', 'pending', 'returned', or 'all' for all statuses
- $page : int = 1
-
The page to return results for
- $order_by : array<string|int, mixed> = ['date_added' => 'DESC']
-
The sort and order conditions (e.g. array('sort_field'=>"ASC"), optional)
- $filters : array<string|int, mixed> = []
-
A list of parameters to filter by, including:
- payment_type The payment type on which to filter transactions
- transaction_id The (partial) transaction number on which to filter transactions
- reference_id The (partial) transaction reference on which to filter transactions
- applied_status The applied status on which to filter transactions
- start_date Get the transactions from this start date
- end_date Get the transactions to this end date
- start_amount Get the transactions from this start amount
- end_amount Get the transactions to this end amount
Return values
array<string|int, mixed> —An array of stdClass objects representing transactions, or false if none exist
getListCount()
Returns the total number of transactions for a client, useful in constructing pagination for the getList() method.
public
getListCount([int $client_id = null ][, string $status = 'approved' ][, array<string|int, mixed> $filters = [] ]) : int
Parameters
- $client_id : int = null
-
The client ID (optional, default null to get transactions for all clients)
- $status : string = 'approved'
-
The status type of the transactions to fetch (optional, default 'approved') - 'approved', 'declined', 'void', 'error', 'pending', 'returned', or 'all' for all statuses
- $filters : array<string|int, mixed> = []
-
A list of parameters to filter by, including:
- payment_type The payment type on which to filter transactions
- transaction_id The (partial) transaction number on which to filter transactions
- reference_id The (partial) transaction reference on which to filter transactions
- applied_status The applied status on which to filter transactions
- start_date Get the transactions from this start date
- end_date Get the transactions to this end date
- start_amount Get the transactions from this start amount
- end_amount Get the transactions to this end amount
Tags
Return values
int —The total number of transactions
getSearchCount()
Return the total number of transactions returned from Transactions::search(), useful in constructing pagination
public
getSearchCount(string $query) : mixed
Parameters
- $query : string
-
The value to search transactions for
Tags
getSimpleList()
Retrieves a list of all transactions in the system
public
getSimpleList([int $client_id = null ][, int $page = 1 ]) : array<string|int, mixed>
Parameters
- $client_id : int = null
-
The ID of the client whose transactions to retrieve (optional)
- $page : int = 1
-
The page to return results for (optional, default 1)
Return values
array<string|int, mixed> —An array of stdClass objects representing each transaction
getStatusCount()
Retrieves the number of transactions given a transaction status type for the given client
public
getStatusCount([int $client_id = null ][, string $status = 'approved' ][, array<string|int, mixed> $filters = [] ]) : int
Parameters
- $client_id : int = null
-
The client ID (optional, default null to get transactions for all clients)
- $status : string = 'approved'
-
The transaction status type (optional, default 'approved') - 'all' for all statuses
- $filters : array<string|int, mixed> = []
-
A list of parameters to filter by, including:
- payment_type The payment type on which to filter transactions
- transaction_id The (partial) transaction number on which to filter transactions
- reference_id The (partial) transaction reference on which to filter transactions
- applied_status The applied status on which to filter transactions
- start_date Get the transactions from this start date
- end_date Get the transactions to this end date
- start_amount Get the transactions from this start amount
- end_amount Get the transactions to this end amount
Return values
int —The number of transactions of type $status for $client_id
getTotalCredit()
Retrieves the total credit amount available to the client in the given currency
public
getTotalCredit(int $client_id, string $currency) : float
Parameters
- $client_id : int
-
The ID of the client to fetch a credit value for
- $currency : string
-
The ISO 4217 3-character currency code
Return values
float —The total credit available to the client in the given currency
getType()
Retrieves a single payment type
public
getType(int $type_id) : mixed
Parameters
- $type_id : int
-
The payment type ID
Return values
mixed —An array of stdClass objects representing a payment type, or false if one does not exist
getTypes()
Retrieves a list of all transaction types
public
getTypes() : mixed
Return values
mixed —An array of stdClass objects representing transaction types, or false if none exist
search()
Search transactions
public
search(string $query[, int $page = 1 ]) : array<string|int, mixed>
Parameters
- $query : string
-
The value to search transactions for
- $page : int = 1
-
The page number of results to fetch (optional, default 1)
Return values
array<string|int, mixed> —An array of transactions that match the search criteria
transactionStatusNames()
Retrieves all transaction status values and their name in key/value pairs
public
transactionStatusNames() : array<string|int, mixed>
Return values
array<string|int, mixed> —An array of key/value pairs representing transaction status values
transactionTypeNames()
Retrieves all transaction types and their name in key=>value pairs
public
transactionTypeNames() : array<string|int, mixed>
Return values
array<string|int, mixed> —An array of key=>value pairs representing transaction types and their names
unApply()
Unapplies a transactions from one or more invoices.
public
unApply(int $transaction_id[, array<string|int, mixed> $invoices = null ]) : mixed
Parameters
- $transaction_id : int
-
The ID of the transaction to unapply
- $invoices : array<string|int, mixed> = null
-
A numerically indexed array of invoice IDs to unapply this transaction from, or null to unapply this transaction from any and all invoices
validateApplyAmounts()
Validates whether the given amounts can be applied to the given invoices, or if the amounts would exceed the amount due on the invoices. Also ensures the invoices can have amounts applied to them.
public
validateApplyAmounts(array<string|int, mixed> $amounts[, float $total = null ]) : bool
Parameters
- $amounts : array<string|int, mixed>
-
An array of apply amounts including:
- invoice_id The invoice ID
- amount The amount to apply to this invoice (optional, default 0.00)
- $total : float = null
-
The total amount of the transaction used to ensure that the sum of the apply amounts does not exceed the total transaction amount
Return values
bool —True if the amounts given can can be applied to the invoices given, false if it exceeds the amount due or the invoice can not receive payments
validateCurrencyAmounts()
Validates whether the invoice amounts being applied are in the transaction's currency
public
validateCurrencyAmounts(int $transaction_id, array<string|int, mixed> $amounts) : bool
Parameters
- $transaction_id : int
-
The ID of the transaction
- $amounts : array<string|int, mixed>
-
An array of apply amounts including:
- invoice_id The invoice ID
- amount The amount to apply to this invoice (optional)
Return values
bool —True if each invoice is in the transaction's currency, or false otherwise
validatePositiveAmounts()
Validates whether each of the given amounts is greater than or equal to zero
public
validatePositiveAmounts(array<string|int, mixed> $amounts) : bool
Parameters
- $amounts : array<string|int, mixed>
-
An array of apply amounts including:
- invoice_id The invoice ID
- amount The amount to apply to this invoice (optional, default 0.00)
Return values
bool —True if all amounts are greater than or equal to zero, false otherwise
validateStatus()
Validates a transaction's 'status' field
public
validateStatus(string $status) : bool
Parameters
- $status : string
-
The status to check
Return values
bool —True if the status is validated, false otherwise
validateType()
Validates a transaction's 'type' field
public
validateType(string $type) : bool
Parameters
- $type : string
-
The type to check
Return values
bool —True if the type is validated, false otherwise
verifyApply()
Verifies that transaction can be applied to a list of invoices
public
verifyApply(array<string|int, mixed> &$vars[, bool $validate_trans_id = true ][, float $total = null ]) : bool
Parameters
- $vars : array<string|int, mixed>
-
An array of transaction info including:
- transaction_id The transaction ID (only evaluated if $validate_trans_id is true)
- date The date in UTC time (Y-m-d H:i:s format) the transaction was applied (optional, default to current date/time)
- amounts A numerically indexed array of amounts to apply including:
- invoice_id The invoice ID
- amount The amount to apply to this invoice (optional, default 0.00)
- $validate_trans_id : bool = true
-
True to validate the transaction ID in $vars, false otherwise
- $total : float = null
-
The total amount of the transaction used to ensure that the sum of the apply amounts does not exceed the total transaction amount. Only used if $validate_trans_id is false (optional)
Return values
bool —True if the transaction can be applied, false otherwise (sets Input errors on failure)
getCreditApplyAmounts()
Creates a list of credits to be applied to invoices for each transaction
private
getCreditApplyAmounts([array<string|int, mixed> $credits = [] ][, array<string|int, mixed> $invoices = [] ][, array<string|int, mixed> $amounts = [] ]) : array<string|int, mixed>
Parameters
- $credits : array<string|int, mixed> = []
-
A list of client credits for all currencies, containing:
- transaction_id The transaction ID
- credit The credit available for this transaction
- $invoices : array<string|int, mixed> = []
-
An array of stdClass objects representing client invoices
- $amounts : array<string|int, mixed> = []
-
A list of specific amounts to be applied per invoice (optional)
- invoice_id The ID of the invoice to apply credits to
- amount The amount of credit to apply to the invoice
Return values
array<string|int, mixed> —A list of credits set to be applied, keyed by transaction ID, with each containing a list of amounts:
- invoice_id The invoice ID to apply the credit to
- amount The amount to apply to the invoice_id for this particular transaction
getCurrencyPrecision()
Retrieves the decimal precision for the given currency
private
getCurrencyPrecision(string $currency, int $company_id) : int
Parameters
- $currency : string
-
The ISO 4217 3-character currency code
- $company_id : int
-
The ID of the company
Return values
int —The currency decimal precision
getTransaction()
Returns a partially built query Record object used to fetch a single transaction
private
getTransaction() : Record
Return values
Record —The Record object representing this partial query
getTransactionRules()
Returns the rule set for adding/editing transactions
private
getTransactionRules([array<string|int, mixed> $vars = [] ]) : array<string|int, mixed>
Parameters
- $vars : array<string|int, mixed> = []
-
An array of input data for the rules
Return values
array<string|int, mixed> —Transaction rules
getTransactions()
Partially constructs the query required by Transactions::getList() and Transactions:getListCount()
private
getTransactions([array<string|int, mixed> $filters = [] ]) : Record
Parameters
- $filters : array<string|int, mixed> = []
-
A list of parameters to filter by, including:
- client_id The client ID (optional, default null to get transactions for all clients)
- payment_type The payment type on which to filter transactions
- transaction_id The (partial) transaction number on which to filter transactions
- reference_id The (partial) transaction reference on which to filter transactions
- applied_status The applied status on which to filter transactions
- start_date Get the transactions from this start date
- end_date Get the transactions to this end date
- minimum_amount Get the transactions from this start amount
- maximum_amount Get the transactions to this end amount
- status The status type of the transactions to fetch (optional, default 'approved') - 'approved', 'declined', 'void', 'error', 'pending', 'refunded', 'returned' (or 'all' for all approved/declined/void/error/pending/refunded/returned)
Return values
Record —The partially constructed query Record object
getTypeRules()
Returns the rule set for adding/editing transaction types
private
getTypeRules() : array<string|int, mixed>
Return values
array<string|int, mixed> —Transaction type rules
searchTransactions()
Partially constructs the query for searching transactions
private
searchTransactions(string $query) : Record
Parameters
- $query : string
-
The value to search transactions for
Tags
Return values
Record —The partially constructed query Record object