Sagepay V3
Note: The existing SagePay v3 integration has been updated to support the new Opayo v4 integration.
Contents
Overview
Khaos Control's use of the SagePay Protocol v3.0 works in exactly the same way as our integration v2.22, however, SagePay now require some additional fields to be populated relating to billing address information and some special considerations for transactions for US customers as the State is now required.
A new feature of the v3.0 protocol is the support for Card Tokens. Previously only transaction level SagePay tokens were able to be used in the same sales order, but now Card level Tokens can be requested from SagePay and then used on multiple Sales Orders if required, until the card or token expires.
This 'Token Swap' feature is not enabled by default within Khaos Control.
Standard SagePay v3.0 (default behaviour)
Non-US transactions
SagePay now require billing and delivery address information to be supplied as part of their new Version 3 integration protocol. (for example BillingCity). Most of these fields were being included in version 2 already, but now some of them are mandatory and a transaction will be rejected by SagePay if these fields are left blank.
Errors in the form of 'BillingCity is a required field' are errors which are coming back from SagePay and are not created by Khaos Control.
US transactions
A new area has been added to Khaos Control called [ System Data | US State Postal Codes ]. When dealing with US customers their state information will be stored in the County field of Khaos Control. This area is used for maintaining the US state information. When processing SagePay transactions for US customers, the County information will be mapped using this list, to the 2 letter Postal Code. This derived 2 letter code is then supplied to Sage Pay.
The initial list is configured using the most common forms of the US States. You can add your own additional mappings if required, for example 'Washington DC' can also be referred to 'District of Columbia' and may appear in some of your customer addresses like this. In order for this to be mapped correctly users can add a mapping including this text, or any other anticipated combinations that you are aware of which may not necessarily be in the standard list.
Common error messages
FirstNames / Surname
SagePay now legally require that the cardholder infomation is split into a forename and a surname field for all transactions. Therefore when you try to submit the cardholder infomation within a single field, SagePay will respond with a relevant error message which will look similar to the below error message.
SOrder: 123456 Card processing failed - MALFORMED 3120 : The DeliveryFirstnames field is required.
With this in mind, we would strongly recommend that all fields are filled in as accurately as possible to ensure that the transaction can be processed without error. If you are experiencing problems taking a payment please ensure the Card Holder contains information in the form "Title Forename Surname".
Based on customer feedback we will be making some changes to Khaos Control going forward to ensure:
- If the "title " field is not found for the cardholder, the forename and the surname will still be populated to SagePay. This will alllow Khaos Control to handle situations where SagePay V3 submissions fail when the card holder name is not in the form "Title - Forename - Surname" format.
- For those who deal with trade cards and don't have a person as the cardholder, we will be making an amendments to Khaos Control so that the company name will be sent as the surname and a full stop will be populated as the forename. EG: .Khaos Control
- Any company names which are more than 2 words long, will have the extra words truncated to the maximum length which SagePay can receive (20 characters each for Forename and Surname) and spead over the two fields.
Country Code problems
If you find you are receiving an error message similar to the following:
SOrder: 123456 Card processing failed - MALFORMED 3141 : The BillingCountry value is invalid.
Please ensure that the Customers address details associated with the transaction you are attempting to process are linked to a Country in Khaos Control with a valid ISO 3166 2 letter country code. For example the 2 letter country code for the United Kingdom is "GB". The Country codes in use by Khaos Control are user maintained and are located in [System Data | Countries] area.
SagePay v3.0 with Token Swapping (optional behaviour)
When Token Swapping is enabled, this fundamentally changes how Khaos Control processes card number information from within the Sales Order and Customer Statement areas. When a new number is entered into a Sales Order as you would normally, the first step of the Sales Order save process, the system will contact SagePay and acquire a token for that card information. When a Token is successfully received, this will be stored instead of the card details and the Sales Order will be saved.
Issues with the Tokens
- If a Token not successfully received, the save process will be aborted and the Sales Order will not be saved.
- If a Token cannot be acquired, it will not be possible to save the Sales Order, until another payment method is chosen, or card details are provided for which a Token can be successfully acquired.
Information about SagePay tokens
Tokens can be re-used on subsequent Sales Orders, for as long as they are valid (i.e. the card behind them has not expired). The validity of the Token is dictated by SagePay. In the same way as a previous card could be selected, the buttons can be used to select a card for which Khaos Control has stored a token.
Note the CV2 number is valid for one use only.
When a Token is initially requested you will have supplied the CV2 number as part of the card information. After the first authorisation, the CV2 will be removed from SagePay's database at their end " Khaos Control has no control over this part of the process.
This means you have a choice when processing secondary payments or additional payments of contacting the customer when re-using a previous Token to re-acquire the CV2 information. To support this the Khaos Control Sales Order interface has been modified so that you can re-enter the CV2 onto an existing Card Token record within a Sales Order. However this is optional. Or if you choose not to do this, when the CV2 is not present, Khaos Control will do its best to process a transaction even if the CV2 number is not present, by disabling the associated SagePay setting in our Authorisation request.
Notes:
- It is important you are aware of the above facts as your Merchant may charge you additional fees or prevent you from processing transactions where the CV2 number is not presented.
- SagePay may reject attempts to do this if you have Vendor Rules configured to reject transactions which do not provide the CV2 number.