SagePay payment gateway

The SagePay payment gateway asset allows users in the United Kingdom and Ireland to create a SagePay payment gateway, providing users with a secure way to pay for their items.

SagePay is now Opayo. While the vendor name has changed, the way you integrate with the service is unchanged in Matrix.

To use the SagePay payment gateway, you will need an Opayo vendor account.

The SagePay payment gateway accepts the following card types:

  • Visa

  • Visa Delta/Debit

  • Visa Electron

  • MasterCard

  • UK Maestro

  • Solo

  • American Express

  • Diners Club

  • JCB

  • International Maestro

  • Laser

Once you have added a SagePay payment gateway, you can configure its settings on its associated asset screens. The majority of these screens are the same as a standard page. Read the Asset screens documentation to learn more about the common screens in Matrix assets.

This page covers the unique Details and Display formatting screens in the SagePay payment gateway asset.

Additional dependant assets

The additional dependant assets

When you create a SagePay payment gateway, the display format and cardholder verification bodycopy assets are automatically created beneath it, as shown. You can use these bodycopies to define the contents and layout of the payment and cardholder verification forms. The display format bodycopy can be accessed through the Display formatting screen.

Details screen

The Details screen allows you to configure the settings of the SagePay payment gateway. Read the Asset details screen documentation to learn more about the Status, Future status, Thumbnail, and Details sections.

Configuration

This section allows you to enter your account details, allowing you to accept payments from the payment gateway, and configure the SagePay payment gateway’s general settings.

The configuration section of the Details screen

The fields available in this section are as follows:

Protocol

Enter the VPSProtocol for your SagePay setup, supplied by Opayo. By default, this field will read 2.23.

Vendor

Enter your vendor login name, supplied by Opayo, when your account is created.

Timeout

Select the amount of time in seconds that the payment gateway will wait for the user’s response before returning an error. By default, this field is set 60 seconds.

Currency

Select the currency used in all ecommerce transactions processed by the SagePay payment gateway. The following currencies are available:

  • Great British Pound (GBP)

  • Australian Dollar (AUD)

  • United States Dollar (USD)

  • Euro (EUR)

  • Japanese Yen (JPY)

Description

Enter a description of the items purchased from the ecommerce store. This description will be displayed on the Opayo administration area of the vendor account on the Opayo website. By default, this field will read the total amount.

Delivery address is billing address?

Select whether to use the billing address provided by users as the delivery address for purchased items. If this field is set to Yes, users will not need to provide a delivery address during the transaction process. By default, this field is set to No.

Supported card types

Select the card types that will be available on the SagePay payment gateway. If a card type is not selected, users can not select that card type during the transaction process. By default, all card types are selected.

Fraud prevention

This section allows you to configure 3-D secure protocol, address verification service (AVS), and card verification value (CV2) systems for added security.

Please note that not all credit and debit cards can provide 3-D secure protection and that the AVS system is not available in all countries. The fraud prevention section of the Details screen:

The fraud prevention section of the Details screen

The fields available in this section are as follows:

Enable 3-D secure?

Select whether to enable 3-D secure protection for transactions made on the SagePay payment gateway. If this field is set to Yes, users will be taken to the cardholder verification screen to display the 3-D secure service configured to your Opayo account. For more information, visit the Opayo website.

Enable AVS/CV2?

Select whether to enable the address verification service and card verification value checks for transactions made on the SagePay payment gateway. If this field is set to Yes, address and CV2 fields must be included on the payment gateway using keyword replacements. For more information, refer to the Display formatting screen section in this chapter. Alternatively, pass-through variables can be configured to source the address from the user’s ecommerce form responses. For more information, refer to the pass-through variables section.

Pass-through variables

This section allows you to source address information for Gift Aid and the address verification service (AVS) from the user’s ecommerce form responses. For example, a user’s response to a city form field on an ecommerce form could be passed through the payment gateway to provide the AVS city. The pass-through variables section of the Details screen is shown in the figure:

The pass-through variables section of the Details screen

In the available fields, enter the pass-through variable keys for the corresponding form fields. These keys must be configured on the ecommerce rules screen of the ecommerce form page. Read the Ecommerce form page documentation for more information about the ecommerce rules screen section.

The fields that are available in this section are as follows:

Gift Aid variable name

Enter the pass-through variable key for Gift Aid. If the value passed is equal to 1, Yes, or a True string, this payment will be classified as a Gift Aid charitable donation. The customer has agreed to donate the tax. This feature is only available for Opayo merchant accounts that are Gift Aid enabled. For more information, visit the Opayo website.

First name variable name

Enter the pass-through variable key for the first name.

Surname variable name

Enter the pass-through variable key for the surname.

Address 1 variable name

Enter the pass-through variable key for the first line of the address.

Address 2 variable name

Enter the pass-through variable key for the second line of the address.

City variable name

Enter the pass-through variable key for the address city.

Postcode variable name

Enter the pass-through variable key for the address postcode.

Interface options

The section allows you to change the wording of the buttons for the payment gateway.

The interface options section of the Details screen

The fields that are available in this section are as follows:

Submit button text

Enter the text to display as the Submit button. By default, this button will read Pay. This button is displayed when the keyword replacement Submit button is used on the display format bodycopy.

Reset button text

Enter the text to display as the Reset button. By default, this button will read Reset. This button is displayed when the keyword replacement Reset button is used on the display format bodycopy.

Cancel button text

Enter the text to display as the Cancel button. By default, this button will read Cancel. This button is displayed when the keyword replacement Cancel button is used on the display format bodycopy.

Run mode

The section allows you to modify the payment gateway to function in Simulator, Test, or Live modes. The run mode section of the Details screen is shown in the figure:

The run mode section of the Details screen

In the Run mode field, select the mode that the SagePay payment gateway will be running in. The following options are available:

Simulator

This mode simulates the Opayo test and live systems. Simulator accounts are trial accounts provided free of charge by Opayo. If this mode is selected, the payment gateway will not process any payments. The card number field on the SagePay payment gateway form will be replaced with the test drop-down menu, as shown in the figure:

The SagePay payment gateway running in simulator mode
Test

This mode will run the payment gateway under test mode. If this mode is selected, the payment gateway will not process any payments. The card number field on the SagePay payment gateway form will be replaced with the test drop-down menu.

Live

This mode will run the payment gateway under live mode. If this mode is selected, the payment gateway will be fully functional and able to process payments.

Display formatting screen

The display formatting screen allows you to edit the display format bodycopy. To edit this bodycopy:

  1. Right-click on the display format bodycopy in the asset tree.

  2. Selecting Edit contents.

Display format bodycopy

The display format bodycopy is used to define the layout of the SagePay payment gateway page. The default layout of the payment gateway is shown in the figure:

The default layout of the SagePay payment gateway

To change the information that is being shown:

  1. Click on the edit edit icon – the WYSIWYG editor will appear.

  2. Use the keyword replacements and formatting to set the information’s layout to show on the payment gateway page. By default, the information shown in the figure will appear in the WYSIWYG editor.

The WYSIWYG editor on the display format bodycopy
By default, the transaction amount on the SagePay payment gateway will be listed in British pounds. This setting may need to be changed depending on the currency you have selected on the Details screen.

Keyword replacements on the display format bodycopy

A list of keyword replacements is provided in the WYSIWYG editor toolbar on the Edit contents screen of the display format bodycopy. You can use these keyword replacements in conjunction with text, images, and links to configure the payment gateway page’s layout. The standard keyword replacements that are available include the following:

Name on card

This will show the name in the card field.

Card number

This will show the credit card number field.

Card start month

This will show the credit card start month field.

Card start month select

This will show the credit card start month select field, allowing users to select a month from a drop-down menu.

Card start year

This will show the credit card start year field.

Card start year select

This will show the credit card start year select field, allowing users to select a year from a drop-down menu. The keyword replacement will display the current year and previous five years in the drop-down menu by default. Altering this keyword replacement can configure the number of years back displayed by appending _xx, where xx is the number of years in addition to the current year to display. For example, it will show the current year as well as ten years backward. If the current year is 2010, the menu will display all years from 2000 to 2010.

Card expiry month

This will show the credit card expiry month field.

Card expiry month select

This will show the credit card expiry month select field, allowing users to select a month from a drop-down menu.

Card expiry year

This will show the credit card expiry year field.

Card expiry year select

This will show the credit card expiry year select field, allowing users to select a year from a drop-down menu. The keyword replacement will display the current year and next five years in the drop-down menu by default. Altering this keyword replacement can configure the number of years forward displayed by appending _xx, where xx is the number of years in addition to the current year to display. For example, it will show the current year as well as ten years forward. If the current year is 2010, the menu will display all years from 2010 to 2020.

Card issue number

This will show the card issue number field.

Card CV2

This will show the card verification value (CV2) field. This field is required for CV2 verification checks.

Card type

This will show the card type menu field. Only card types selected in the supported card types field on the Details screen will be available in this field.

Billing first names

This will show the billing first names field.

Billing surname

This will show the billing surname field.

Billing address 1

This will show the first line of billing address field.

Billing address 2

This will show the second line of billing address field.

Billing city

This will show the billing city field.

Billing postcode

This will show the billing postcode field.

Billing country

This will show the billing county field.

Billing state

This will show the billing state field.

Billing phone

This will show the billing phone number field.

Delivery first name

This will show the delivery first name field.

Delivery surname

This will show the delivery surname field.

Delivery address 1

This will show the first line of delivery address field.

Delivery address 2

This will show the second line of delivery address field.

Delivery city

This will show the delivery city field.

Delivery postcode

This will show the delivery postcode field.

Delivery country

This will show the delivery county field.

Delivery state

This will show the delivery state field.

Delivery phone

This will show the delivery phone number field.

Transaction amount

This will show the amount of money that is to be paid in the transaction.

Transaction currency

This will show the transaction currency. For example, AUD.

Processing error(empty if no error)

This will show any processing errors. For example, if the user forgets to fill out a field.

Submit button

This will show the Submit button.

Cancel button

This will show the Cancel button.

Reset button

This will show the Reset button.

A number of these fields are compulsory when creating an active payment gateway. If the required fields are not available to the user, the transaction will not be able to be completed.

Cardholder verification bodycopy

The cardholder verification bodycopy is used to define the SagePay payment gateway’s 3-D secure verification page layout. By default, the 3-D secure service configured to your SagePay account will be nested within this page. For more information, visit the Opayo website.

To change the information that is being shown:

  1. Click on the edit edit icon – the WYSIWYG editor will appear.

  2. Use the keyword replacements and formatting to set the information’s layout to show on the verification page.

By default, the information shown in the figure will appear in the WYSIWYG editor.

The WYSIWYG editor on the cardholder verification bodycopy

Keyword replacements on the cardholder verification bodycopy

A list of keyword replacements is provided in the WYSIWYG editor toolbar on the Edit contents screen of the cardholder verification bodycopy. You can use these keyword replacements in conjunction with text, images, and links to configure the verification page’s layout. The standard keyword replacements that are available include the following:

Cardholder verification form

This will show the 3-D secure service configured to your Opayo account.