Using SagePay with Aeon

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 Online/Pay Now button on the Aeon Order Billing form (ViewOrderApproval.html), they are taken to the Sage Pay-specific CreditCardPayment form. Clicking the Pay Online/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 Order Billing 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.

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.

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.

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");