Documentation - Whasols

Merchant Gateway

Follow the steps below to create a third party gateway module.

A Merchant Gateway is one where a customer enters credit card details in WHASOLS. The payment processes in the background. This can also include 3D Secure when the user leaves your site. Examples include PayPal Pro, Authorize.net, and AIM.

Implementation Guide

Delete the yourmodulename_link function from the module template since this is only required for Third Party Gateway modules.
Enter the gateway-specific code for processing the payment capture into the yourmodulename_capture function. Typically, this takes the format of an HTTP/Curl request to the gateway provider’s API.
If the gateway supports 3D Secure (Verified by Visa or MasterCard Secure Code) refer to 3D Secure.
If your payment gateway supports refunds, implement support for Refunds.

Variables

The following parameters are passed to the yourmodule_capture function along with all defined configuration parameters and their values.

Response Format

The following return parameters are supported.

Parameter	Type	Notes
status	string	One of either `success`, `pending`,`error`, or `declined`.
message	string	The reason why a transaction was declined.
transid	string	The Transaction ID returned by the payment gateway.
fee	float	(Optional) The transaction fee returned by the payment gateway.
rawdata	string or array	The raw data returned by the payment gateway for logging to the gateway log to aid in debugging.
gatewayid	string	See Tokenised Remote Storage.

Example Return

The capture function should always return an array containing information about the transaction attempt. This should take the following format:

<?php return [
    "status"=>"success",
    "rawdata"=>$responseData,
    "transid"=>$transactionId,
    "fee"=>$feeAmount,
];

For a successful capture, the status should be returned as the string success.

For payments that are pending and do not require an immediate payment in WHASOLS, the status should be pending.

For anything else, return a status that indicates the reason for failure. Common failure response status values include declined and error.

The raw data you return will be recorded to the gateway log to aide in debugging. It can accept either a string or an array.

Simple Example

Below is a demonstration of a capture function that submits a payment capture request and receives a JSON response. For a more complete example, please refer to the Sample Merchant Gateway module on GitHub.

<function yourmodulename_capture($arg) {
    $invoiceid = $arg['invoice']['invoiceid'];
    $description = $arg['invoice']['description'];
    $amount = $arg['invoice']['amount'];
    $currencyCode = $arg['invoice']['currency'];
    $cardtype= $arg['card']['cardtype']; //string The card type (for example, Visa or MasterCard).
    $cardnum= $arg['card']['cardnum']; //string	The card number.
    $cardexp= $arg['card']['cardexp']; //string	The card expiry date (format: MMYY).
    $cardstart= $arg['card']['cardstart']; //string The card start date (format: MMYY).
    $cardissuenum= $arg['card']['cardissuenum']; //string The card issue number.
    $cccvv= $arg['card']['cccvv']; //string Only available for card holder present initiated payment attempts.
    $firstname = $arg['client']['firstname'];
    $lastname = $arg['client']['lastname'];
    $email = $arg['client']['email'];
    $address1 = $arg['client']['address1'];
    $address2 = $arg['client']['address2'];
    $city = $arg['client']['city'];
    $state = $arg['client']['state'];
    $postcode = $arg['client']['postcode'];
    $country = $arg['client']['country'];
    $phonenumber = $arg['client']['phonenumber'];
    $postfields = [
        'invoiceid' => $invoiceid,
        'amount' => $amount,
        'currency' => $currencyCode ,
        'cardnumber' => $cardnum,
        'cardexpiry' => $cardexp,
        'cardcvv' => $cccvv,
        'card_holder_name' => $firstname. ' - ' .$lastname,
        'card_address' => [
            'address_line_1' => $address1,
            'city' => $city,
            'state' => $state,
            'postcode' => $postcode,
            'country' => $country,
        ],
    ];
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, 'https://www.example.com/api/capture');
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postfields));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    $response = curl_exec($ch);
    curl_close($ch);
    $data = json_decode($response);
    if ($data->success == 1) {
        $return = [
            'status' => 'success',
            'transid' => $data->transaction_id,
            'fee' => $data->fee,
            'rawdata' => $data,
        ];
    } else {
        $return = [
            'status' => 'declined',
            'message' => $data->decline_reason,
            'rawdata' => $data,
        ];
    }
    return $return;
}