Callback Response

If you are building a payment gateway that supports notifying you when a payment is successful you should create a callback function as part of your module to receive and handle those notifications.

A callback function should process and validate the notification and then call one of several functions made available by WHASOLS to log and apply the payment.

Creating A Callback Function

A sample callback function is included in the sample gateway module named yourmodulename_callback.

We recommend using the sample function as a starting point for your creating your own gateway callback function. Rename it to match the name of your own gateway module.

Most callback function should use the following workflow:

  • Implement logic to validate the authenticity of the payment gateway callback and prevent abuse.
  • Validate the invoice ID the callback relates to using the DoInvoiceValidate helper method.
  • Verify the transaction ID has not already been recorded using the DoTransactionValidate helper method.
  • Log the transaction to the WHASOLS Gateway Log using the AddGatewayLogs helper method.
  • Apply the payment to the invoice using the AddInvoicePayment helper method.

Callback Redirection

When a payment is received, a payment notification containing the transaction details may be sent to the gateway module’s callback function. The URL of the callback url would be considered the Callback URL (e.g. https://example.com/client/paytoinvoice/$gateway_id/$invoiceid).

Some gateways allow you to you pass a Return URL and a Callback URL in the payment button code. WHASOLS can provide the Return URL during the initial payment submission to the gateway via the $arg["system"]["returnurl"] parameter, which is made available in the gateway module _link function.

Other payment gateways require the Return URL to be specified in the payment gateway’s control panel settings outside of WHASOLS to return the client upon completion of a payment (e.g. a success/failure page or redirect to the paid invoice). So, The URL to this page will be considered the Return URL (e.g. https://example.com/client/paytoinvoice/your-gateway-name).

This URL could then be specified in the payment gateway’s control panel settings outside of WHASOLS, leaving just the notification URL specified in the gateway module’s _link function.

If the gateway only supports one URL for both payment notification and redirection after payment, visitors can be redirected to the callback url and output provided to return them to the Client Area via a link or meta refresh. This output should be provided by the callback url after the AddInvoicePayment and AddGatewayLogs functions.

Helper Functions

The following helper functions are made available for use in payment gateway callback files.

Get Gateway Variables

<?php 
/**
 * Get Gateway Variables.
 *
 * Retrieves configuration setting values for a given module name.
 *
 * @param string $gatewayName
 */
$gatewayParams = GetPaymentGatewayVariables('yourgatewayname');
This function can be used to retrieve the configuration data for a module as specified in the _config array. For example, it might be needed to get a gateway username or secret key to validate a callback.

Validate Callback Invoice ID

<?php 
/**
 * Validate Callback Invoice ID.
 *
 * Checks invoice ID is a valid invoice number. Note it will count an
 * invoice in any status as valid.
 *
 * Performs a die upon encountering an invalid Invoice ID.
 *
 * Returns a normalised invoice ID.
 *
 * @param int $invoiceId
 */
$invoiceId = DoInvoiceValidate($invoiceId);
Use this function to verify that the invoice ID received in a callback is valid. Pass the $invoiceid and the gateway name into the function. If the invoice number is invalid, the callback script execution will be halted.

Validate Callback Transaction ID

<?php 
/**
 * Check Callback Transaction ID.
 *
 * Performs a check for any existing transactions with the same given
 * transaction number.
 *
 * Performs a die upon encountering a duplicate.

 * @param int $invoiceId
 * @param string $transactionId
 */
DoTransactionValidate($invoiceId,$transactionId);
Use this function to check for any existing transactions for a given transaction ID. This protects against duplicate callbacks for the same transaction. If the transaction ID is already in the database, the callback script execution will be halted.

Log Transaction

<?php 
/**
 * Add Gateway Logs.
 *
 * Add an entry to the Gateway Log for debugging purposes.
 *
 * The debug data can be a string or an array.
 *
 * @param int $payment_method Gateway id
 * @param int $user_id Client id
 * @param int $invoiceid Invoice id
 * @param string|array $debugData Data to log
 * @param string $transactionStatus Status
 */
AddGatewayLogs(
[
'invoice_id'=>$invoiceid,
'user_id'=>$user_id,
'payment_method'=>$payment_method,
'status'=>$transactionStatus,
'response'=>json_encode($_REQUEST)]
);
Use this function to create a gateway log entry.
  • The payment_method input parameter should be the id of the gateway module.
  • The user_id input parameter should be the id of the client from invoice.
  • The invoice_id input parameter should be the id of the invoice.
  • The response input parameter should be an array of data received (for example, the $_POST or $_REQUEST super globals).
  • The status input parameter should be the human readable result or status to display in the log.

Add Payment to the Invoice

<?php 
/**
 * Add Invoice Payment.
 *
 * Apply a payment to the given invoice ID.
 *
 * @param int $invoiceId       Invoice ID
 * @param int $user_id         Client ID
 * @param string $currency     Currency Code
 * @param string $transactionId  Transaction ID
 * @param float $paymentAmount   Amount paid (defaults to full balance)
 * @param float $paymentFee      Payment fee (optional)
 * @param int $payment_method  Gateway module ID
 */
 AddInvoicePayment(
[
'invoice_id'=>$invoiceid,
'currency'=>$currency,
'user_id'=>$user_id,
'payment_method'=>$payment_method,
'amount'=>$paymentAmount,
'trno'=>$transactionId,
'fee'=>$fee,
'notification'=>'YES'
]);
Use this function to apply the payment to an invoice.

This documentation assumes you are following the sample callback response in the sample module which defines this variable and populates it with the gateway parameters from WHASOLS.