Using SagePay with Aeon

Follow

Credit card payments made using Sage Pay are made on a secure page hosted by this provider. When a researcher chooses transactions to pay for and clicks the Pay Now button on the Aeon Orders to Approve/Pay form (ViewOrderApproval.html), they are taken to the Sage Pay-specific CreditCardPayment form. Clicking the Pay Now button on this form takes them to a secure page outside of Aeon to perform the credit card transaction.

After the payment is submitted and the transaction is complete, the researcher is returned back to the Orders to Approve/Pay page in the Aeon web interface. The forms show an updated balance due and a status line at the top of the form notifies the researcher that the payment was successful and displays the payment confirmation code. 

On the Sage Pay side, configuring a site's account to work with Aeon should not require more than adding the IP address of the Aeon web server to Sage Pay's list of IPs allows submitting transactions. If any further configuration is required or your site needs help configuring Sage Pay more generally, refer to the My Sage Pay user manual.

Customization Keys

You will need to set the following key values in the Aeon Customization Manager.

PaymentProviderMerchantId Enter the merchant ID or login provided to you by Sage Pay. Specialized ViewOrderApproval and CreditCardPayment forms have been created to work with Authorize.Net, PayPal and Sage Pay. Your Implementation Coordinator or Customer Service Agent will supply these to you when you are setting up your payment provider information. They are also available as a zip file at Aeon 3.8 Downloads.
CreditCardTransactionsDescription This value is used as a product description on the Sage Pay website to describe the researcher's purchase. The default value of this key includes the transaction numbers of the included requests:  Aeon Photoduplication charges for transaction(s) <#PARAM name='TransactionNumbers'>. This key is located under System | General.

Web Edits

Below are the steps necessary to set up the web pages to work with Sage Pay. Specialized ViewOrderApproval and CreditCardPayment forms have been created to work with Sage Pay. Your Implementation Coordinator or Customer Service Agent will supply these to you when you are setting up your payment provider information. They are also available as a zip file at  Aeon 3.8 Downloads.

ViewOrderApprovals Form

Replace the default ViewOrderApprovals form in the Web folder with the ViewOrderApprovals form designed to work with credit card payments. This form contains the Pay Now button that takes the researcher to the CreditCardPayment.html form.

CreditCardPayment Form

Replace the default CreditCardPayment form in the Web folder with the Sage Pay CreditCardPayment.html form.

Note the action of the Sage Pay form is set to aon.dll?Action=11&Type=107. The form is posted back to the Aeon dll with an action of 11 and action type of 107. This code is specific to Sage Pay and will not work for other providers. Once the dll processes the request it forwards the researcher to the Sage Pay site to collect credit card details and complete the transaction.

Make the following changes to these hidden fields on the form:

  • VPSProtocol. This field has a default value of 2.23. This value should not be changed unless warranted by future revisions to the Sage Pay communication protocol.
  • Currency. This field specifies the currency that the transaction uses as has a default value of BGP. This value is specified by the three-letter ISO code and must match the currency the site has configured their Sage Pay account to accept. Common values you made need to use: 
    • USD: US Dollars
    • GBP: Great British Pounds
    • EUR: Euros
    • CAD: Canadian Dollars
  • Description. The description field provides the value that will be used on the Sage Pay website to describe the researcher's purchase. The default setting simply pulls the value from the CreditCardTransactionsDescription customization key but can be changed if you wish to differentiate the product's description, and additional values can be added.
  • TransactionNumbers. This field has a value of TransactionNumbers. This field is needed by the dll and should not be edited or removed.
  • NotificationURL. This field is the URL that Sage Pay will post to, to notify Aeon that a credit card transaction has completed, successfully or otherwise. The default value is <#CUSTOMIZATION name=WebURL />/aeon.dll?action=11&type=108" />. This URL must use an action of 11 and an action type of 108. A couple of caveats to note:
    • If you are using the website on the webserver and are using local host or a 127 address to access the pages, that URL will be used to replace the dll tag and Sage Pay will not be able to reach the web server. Make sure to use the same URL an external user would use in this case. 
    • This may not work if a site is using RemoteAuth and the dll being used is under a RemoteAuth directory. In this case, the NotificationURL should be edited to point to the URL under the non-Shibboleth directory.

The NotificationURL value is constructed using the WebURL customization key. The value can also be constructed using a #DLL tag that provides the address of the DLL that is actually being used. Most of the time these values are the same, but there can be some subtle differences. For example, if a site were using the Aeon.dll in the test web directory, the #DLL method would build the notification URL as ‘http://university.edu/aeon/testweb/aeon.dll?action=11&type=108’ while the #CUSTOMIZATION method would build it as ‘http://university.edu/aeon/aeon.dll?action=11&type=108’. The #DLL may be a better approach if a shared server setup has different directories and pages for different sites.

Billing and Delivery Address Information

Sage Pay requires both billing and delivery address (BillingAddress and DeliveryAddress) details to be collected before passing the customer to them for credit card processing. Since shipping isn't typically relevant for electronically delivered documents, the default CreditCardPayment.html for Sage Pay only collects BillingAddress fields; the DLL then duplicates them into DeliveryAddress fields if those are not present.

The default CreditCardPayment form contains the required fields as well as a dropdown that will provide the option to populate the fields from either the primary or secondary address record of the Aeon account. This page hides the US state field by default unless "United States" is selected on the Country dropdown. The state field (BillingState) is required by US banks when processing credit cards.

Web Tag Edits to the CreditCardPayment Form

The DLL tag on the Sage Pay CreditCardPayment form has some new optional parameters:

  • absoluteUrl: When set to true, the <#DLL> tag will be replaced by the full url of the aeon.dll.
    For example, <#DLL> or <#DLL absoluteUrl ="false"> would be replaced by "aeon.dll".
    <#DLL absoluteUrl="true"> would be replaced by
    "http://aeon.institution.edu/aeon/aeon.dll?Action=10&Form=10".
  • queryFields: By default, the query parameters in the url for a pay are included in the
    <#DLL> replacement, such as "aeon.dll?Action=10&Form=10". If set to false, the query
    parameters will not be included. For example, <#DLL queryFields="false"> would be
    replaced by just "aeon.dll".
  • encodeUrl: If set to true, the string will be HTTP encoded so that it can be used as a URL
    query parameter, for example <#DLL absoluteUrl="true" encodeUrl="true"> would be replaced
    by "http%3A%2F%2Faeon.institution.edu%2Faeon%2Faeon.dll%3FAction%3D10%26Form
    %3D10%0A", in contrast to the absoluteUrl example above.
  • Option name = Countries: The <#OPTION name="Countries"> option has changed slightly.
    You can now specify the format of the value of the dropdown that is submitted by using the
    mode parameter, for example <#OPTION name="Countries" mode="twoLetter">. The values
    for mode are "twoLetter" (the default), "threeLetter", "numeric" (ISO numeric code), and "name",
    which is just the full name.

JavaScript

Note that the javascript of this page has been changed from previous versions. If a user cancels the page instead of using the post previously used, the account is returned to the Main Menu:

$("#cancel").click(function() {
		window.location.replace("<#DLL queryFields=false>?action=10&form=10");

Questions?

If this article didn’t resolve your issue, please take a moment and answer a few questions to help improve our documentation:

Feedback