How to Interface with Nelnet

The document "QuickPay Commerce Manager Pass Through Authentication Specification" and "QuikPay Redirect Receipt" detail how to interface with Nelnet. These details have been abstracted to provide a simple interface. This interface is available as a Perl module. A PHP version will soon be available.

Perl

You will need to write a CGI script. Your "Shared Secret Key" will be included in this script, so you will need to set the permissions to protect your key. In Unix terms, the script needs to have permissions 700 (chmod 700 script_name.cgi). Using cgiwrap, the web server can execute your script.

You can download an example CGI script and download the NelNet perl module. The file NelNet.pm must be copied to the directory where you create your CGI script. Future upgrades for this file may be available.

A Simple CGI Script

Go to your cgi-bin directory cd www-home/cgi-bin/ and create the following CGI script. For this example, call the script example.cgi.

#!/usr/bin/perl

print qq|Content-type: text/html\n\n
<HTML>
  <BODY>

    Hello World!
     
  </BODY>
</HTML>
|;

To execute this script, use the cgiwrap version of the URL. Substitute your username in place of username:


http://www.wfu.edu/cgi-bin/cgiwrap/~username/example.cgi

NelNet.pm

The goal of the NelNet.pm Perl module is to encapsulate the security details in order to provide a simple interface to NelNet.

The NelNet.pm Perl module contains multiple Perl objects. The statement, use Nelnet(); at the top of your program allows your program to incorporate these objects.

By default, this module is set to operate in production. While testing your application, you will need to direct the module to operate in test mode. Setting the variable $NelNet::TEST to 1 will enable test mode. When ready for production, you can set this to 0 or just delete this line of code.

  use NelNet();
 
  # for testing your application
  $NelNet::TEST = 1;

The NelNet::Pay Object

To process a transaction, the web developer provides a NelNet URL to the user. This URL requires a list of parameters in the proper order, a timestamp and a digital signature. This object creates the proper URL from the information you provide. The following illustrates the usage of this object. You can also download an example script.

The NelNet::Pay object provides methods to set the parameters to be sent to Nelnet. This page lists all the set methods. The getURL method will return the URL to use for the Nelnet transaction.

Before you can create a transaction, you must provide some details about the transaction. In this example, the OrderType will be "Phone Bill", the OrderNumber will be "1234", the payment method is via credit card and the amount is $55.00 dollars.

The OrderType is a required parameter. This value is assigned to your department by the Commerce Manager administrator. You will also obtain your secret key from the Commerce Manager administrator.

Other parameters are optional but may be very helpful. For example, you may want to assign a unique number for the each OrderType to assist in matching the purchase with a particular person or item.

To create (or instantiate) the NelNet Payment Perl module use the following at the beginning of your script:

  use NelNet();

  $NelNet::TEST = 1;

  $pay = new NelNet::Pay();

To set the various parameters use the following methods:

  $pay->setOrderType('Phone Bill');
  $pay->setOrderNumber('1234');
  $pay->setPaymentMethod('cc');
  $pay->setAmount('5500');

Please note that the amount is specified in Cents. So, $55.00 dollars is specified as 5500.

Next, you need to provide your key so the object can sign the URL. NelNet uses this signature to verify the request came from you.

  $pay->setKey('MY PRIVATE KEY');

Now, we create the URL for the transaction:

  $url = $pay->getURL();

But, before we give this URL to the user, check to see if the URL generation process encountered any errors. The method isError() will return a true value if errors are present. The method errors() will provide text about the errors.

  if ($pay->isError())
    {
      print "Sorry, an error has occurred: " . $pay->errors() . "\n";
      exit(0);
    }

Now that we know there are no errors, we can present the URL to the user. In the above script, we save the URL in a variable called $url. The following code presents this URL to the user.

print qq|Content-type: text\html\n\n

    <HTML>
    <BODY>

    <a href="$url">Click here to pay $55 dollars toward your phone bill.</a>

    </BODY>
    </HTML>
    |;

The NelNet::Receipt Object

If you want confirmation of the on-line payment, NelNet can execute another CGI script upon payment completion. You will need to add two additional lines to your payment script. You will need to call the setRedirectUrl() function to specify the URL to be executed and the function setRedirectUrlParameters() to specify the values you want to receive. Here is a list of the valid parameters.

The setRedirectUrlParameters() accepts a comma separated list of parameter names and can cause an error if invalid parameters are set. You can check the validity of your list of parameter names by querying the isError() function. Adding to the above example, the set functions would now look like the following:

  ... 
  $pay->setPaymentMethod('cc');
  $pay->setAmount('5500');

  $pay->setRedirectUrl('http://www.wfu.edu/cgi-bin/cgiwrap/~username/my_receipt_script.cgi');
  $pay->setRedirectUrlParameters('orderType,transactionType,transactionStatus');

  if ($pay->isError())
    {
      print "Fatal Error";
    }
  ... 

The NelNet::Receipt object validates the receipt data returned from NelNet. This code uses your key to ensure that the data came from NelNet and not a hacker. The verifyHash() function returns a true or false value. The following code illustrates the validation CGI script.

use NelNet;

$receipt = new NelNet::Receipt();

$receipt->setKey('MY PRIVATE KEY');

if ($receipt->verifyHash())
  {
    # Good, the receipt is verified.
  }
else
  {
    die "Invalid Receipt";
  }

Once the Receipt is verified, you can obtain the values for your parameters. The values can be obtained one at a time or all at once. Here is a list of the valid parameters and the valid functions.

The getRedirectUrlParameters causes an error if invalid parameters are specified, so you should query the isError() function after using getRedirectUrlParameters. The get methods are illustrated here:


# using descriptive function names
$orderType = $receipt->getOrderType();
$transactionType = $receipt->getTransactionType();

# or using a single function with a parameter name
$transactionStatus = $receipt->getRedirectUrlParameters('transactionStatus');
$transactionType = $receipt->getRedirectUrlParameters('transactionType');

# or using the single function to obtain all the parameters at once.
($orderType, $transactionType, $transactionStatus) 
    = $receipt->getRedirectUrlParameters('orderType,transactionType,transactionStatus');

[an error occurred while processing this directive]