Remote Input Token Storage

A remote input module is a type of merchant gateway that accepts input of pay method data remotely within an iFrame so that it appears transparent to the end user, and then exchanges it for a token that is returned to WHMCS to be stored for future billing attempts.

Within WHMCS, sensitive payment data such as a card number or bank account information is not stored locally when a remote input module is used.

Creating a Remote Input Gateway

A remote input gateway requires two functions to be implemented in addition to the standard capture. These functions are remoteinput and remoteupdate.

Once processed, a notification will be sent to a callback file where the Pay Method should be stored and the payment applied.

For a more complete example, please refer to the Sample Remote Input Gateway module or Sample Remote Input Bank Gateway module on Github.

Remote Input

The remoteinput function will be called when adding a new payment method as part of checkout, or when adding a new payment method outside of the checkout process.

The remote input function is required to return an HTML form that will be automatically submitted into an iframe target. The page rendered within the iframe should allow the user to enter card or bank details in one of 2 workflow scenarios:

• Making payment using a new card or bank - in this workflow the remote endpoint should allow the user to enter card/bank details, generate a token, and capture payment for the requested amount
• Adding a new card or bank to the users account - in this workflow the remote endpoint should allow the user to enter card/bank details and generate a token, but not perform any immediate capture

The workflow type can be determined based on if an invoiceid and amount parameter is received as part of the parameters passed to the remoteinput function.

Example

function yourmodulename_remoteinput($params)
{
    return '<form method="post" action="https://www.example.com/remote/input">
    <input type="hidden" name="api_user" value="' . $params["api_user"] . '" />
    <input type="hidden" name="api_secret" value="' . $params["api_secret"] . '" />
    <input type="hidden" name="amount" value="' . $params["amount"] . '" />
    <input type="hidden" name="invoice_id" value="' . $params["invoiceid"] . '" />
    <input type="hidden" name="firstname" value="' . $params["clientdetails"]["firstname"] . '" />
    <input type="hidden" name="lastname" value="' . $params["clientdetails"]["lastname"] . '" />
    <input type="hidden" name="address1" value="' . $params["clientdetails"]["address1"] . '" />
    <input type="hidden" name="city" value="' . $params["clientdetails"]["city"] . '" />
    <input type="hidden" name="state" value="' . $params["clientdetails"]["state"] . '" />
    <input type="hidden" name="postcode" value="' . $params["clientdetails"]["postcode"] . '" />
    <input type="hidden" name="country" value="' . $params["clientdetails"]["country"] . '" />
    <input type="hidden" name="phonenumber" value="' . $params["clientdetails"]["phonenumber"] . '" />
    <input type="hidden" name="email" value="' . $params["clientdetails"]["email"] . '" />
    <input type="hidden" name="cust_id" value="' . $params["clientdetails"]["id"] . '" />
    <input type="hidden" name="return_url" value="' . $params['systemurl'] . 'modules/gateways/callback/yourmodulename.php" />
    <noscript>
        <input type="submit" value="Click here to continue &raquo;" />
    </noscript>
</form>';
}

Remote Update

The remoteupdate function will be called when a pay method is requested to be modified and should allow the user to edit the data of on an existing token.

The expected return of this function is direct HTML output. It provides more flexibility than the remote input function by not restricting the return to a form that is posted into an iframe. We still recommend using an iframe where possible, but the update can sometimes be handled by way of a modal, popup or other such facility.

Example

function yourmodulename_remoteupdate($params)
{
    $formAction = 'https://www.example.com/remote/update';
    $formFields = [
        'api_user' => $params['api_user'],
        'api_secret' => $params['api_secret'],
        'token' => $params['gatewayid'],
        'custom_reference' => $params['paymethodid'],
    ];

    $formOutput = '';
    foreach ($formFields as $key => $value) {
        $formOutput .= '<input type="hidden" name="' . $key . '" value="' . $value . '">' . PHP_EOL;
    }
    
    return '<div id="frmRemoteCardProcess" class="text-center">
    <form method="post" action="' . $formAction . '" target="remoteUpdateIFrame">
        ' . $formOutput . '
        <noscript>
            <input type="submit" value="Click here to continue &raquo;">
        </noscript>
    </form>
    <iframe name="remoteUpdateIFrame" class="auth3d-area" width="90%" height="600" scrolling="auto" src="http://about:blank"></iframe>
</div>
<script>
    setTimeout("autoSubmitFormByContainer(\'frmRemoteCardProcess\')", 1000);
</script>';
}

Disallowing Remote Update Example

In some circumstances, it may be appropriate to disallow remote updates for Pay Methods.

To achieve this, you can return an alert to be displayed in place of a form:

function yourmodulename_remoteupdate($params)
{
    return <<<HTML
<div class="alert alert-info text-center">
    Updating your card/bank is not possible. Please create a new Pay Method to make changes.
</div>
HTML;
}

Helper Functions

The following functions are available in WHMCS 7.9 and later. We recommend using these functions within the callback handler of a remote input gateway to create a new pay method or update an existing one. Both functions return a boolean true on a success, and any error will throw an exception that should be caught and logged.

createCardPayMethod

This function can be used to add a new card pay method to a client account.

Parameters

Return

Boolean return true on successful creation of a pay method.

Error

When an error occurs in the function call, an exception will be thrown with an appropriate message. The most common messages are detailed below. Other exceptions could be thrown and need to be caught.

updateCardPayMethod

This function can be used to update an existing card pay method for a client.

Parameters

Return

Boolean return true on successful update of the pay method.

Error

When an error occurs in the function call, an exception will be thrown with an appropriate message. The most common messages are detailed below. Other exceptions could be thrown and need to be caught.

createBankPayMethod

This function can be used to add a new bank pay method to a client account.

Parameters

Return

Boolean return true on successful creation of a pay method.

Error

When an error occurs in the function call, an exception will be thrown with an appropriate message. The most common messages are detailed below. Other exceptions could be thrown and need to be caught.

updateBankPayMethod

This function can be used to update an existing bank pay method for a client.

Parameters

Return

Boolean return true on successful update of the pay method.

Error

When an error occurs in the function call, an exception will be thrown with an appropriate message. The most common messages are detailed below. Other exceptions could be thrown and need to be caught.