Server Protocol and Integration Guideline

Server Protocol and Integration Guideline

 Server Protocol and Integration Guideline

Document Index

Welcome to the Sage Pay Server Integration Method .................................... 3

Overview of how Server integrated Payments work ....................................... 4
The Server Payment integration Process in Detail ......................................... 5
Step 1: The customer orders from your site. ............................................. 5
Step 2: Your server registers the payment with Sage Pay. .......................... 6
Step 3: Sage Pay reply to the payment registration POST. .......................... 7
Step 4: Customer enters card details on Sage Pay’s Server......................... 9
Step 5: Sage Pay Server checks 3D-Secure enrolment. ............................ 10
Step 6: Server redirects your customer to their Card Issuing Bank. ........... 11
Step 7: The Issuing Bank returns the customer to the Sage Pay. ............... 12
Step 8: Sage Pay Server requests card authorisation. .............................. 13
Step 9: Sage Pay Server contacts your NotificationURL ............................ 14
Step 10: You reply to the Notification POST ............................................ 16
Step 11: Sage Pay Server Redirects the Customer to your site. ................. 17
Step 12: Sage Pay sends Settlement Batch Files to confirm payments. ....... 18
The Transaction Monitor ....................................................................... 19
LOW PROFILE Payment Pages ............................................................... 20
Integrating with Sage Pay Server ............................................................. 22
Stage 1: Integrating with the Sage Pay Simulator ...................................... 23
1: Sage Pay Simulator Account Set up ................................................... 24
2: Server Integration method Set up...................................................... 25
4: Handling the Server payment Callback ............................................... 27
5: Examining your transactions ............................................................. 29
Stage 2: Testing on the Test Server .......................................................... 30
The Test Server My Sage Pay interface ................................................... 32
Additional Transaction Types ................................................................. 34
Stage 3: Going Live ................................................................................ 38
Congratulations, you are live with Sage Pay Server. ................................... 39
Appendix A - The Sage Pay Server 2.23 Protocol ........................................ 40
A1: Transaction registration .................................................................. 41
A2: Server Response to the Transaction Registration POST ....................... 47
A3: Notification of Results for Transactions ............................................. 48
A4: You acknowledge receipt of the Notification POST .............................. 51
A5: Server Integration Full URL Summary .............................................. 52
 Server Protocol and Integration Guideline

Welcome to the Sage Pay Server Integration Method

The Sage Pay Payment system provides a secure, simple means of authorising
credit and debit card transactions from your website.

The Sage Pay system provides a straightforward payment interface for the
customer, and takes complete responsibility for the online transaction, including the
collection and encrypted storage of credit and debit card details, eliminating the
security implications of holding such sensitive information on your own servers.

The Sage Pay Server Integration method is our flagship, and original system.
Server integration talks directly to your web server over a direct, encrypted channel,
exchanging digitally signed messages to register the transaction and notify you
directly of the authorisation results. No sensitive information is sent via the
customer’s browser, and because the customer is redirected to Sage Pay, no card
details need to be taken or stored on your site (removing the need for you to
maintain highly secure encrypted databases, obtain digital certificates or undergo
extensive auditing against the Visa and MasterCard PCI-DSS security standard).

This document explains how your Web servers communicate with Sage Pay Server,
goes on to explain how to integrate with our testing and live environments. It also
contains the complete Sage Pay Server Payment Protocol in the Appendix.

Page 3 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

Overview of how Server integrated Payments work

The final “Pay Now” button on your website is your link to the Sage Pay System.
Once the customer has selected their purchases, entered delivery details, billing
address and so forth, all on your own site, and pressed the final pay or proceed
button, a secure web post is sent from your servers to Sage Pay, registering the
transaction. In response we return a registration Status, further transaction
identifiers (which you store in your database) and a URL to which your site should
redirect the customer.

The redirected customer arrives on the Sage Pay Server payment page where they
enter their credit/debit card details, security codes and address (if you have not
already captured it). The Sage Pay Server main page carries your logo, and a
description (sent by your site) of the goods the customer is paying for, so they can
remain confident they are buying from you. You can even customise those
payment pages to carry the look and feel of your site at no additional cost.

Once the customer has selected their payment method and entered the details,
they are shown a full summary of their order (including basket contents if you have
passed them to us) and asked to confirm that they wish to proceed. Server then
requests 3D-authentication from the card issuing bank (where appropriate), then
requests authorisation from your acquiring bank. Once the bank has authorised the
payment (and assuming the address and card value checks have passed any rules
you may have set up), we send an HTTP or HTTPS POST directly to your web
servers, informing you of the outcome. Anti-tampering mechanisms are attached
to the POST, so that you can confirm the server messages have not been modified
in transit.

Having received this POST, your site confirms the transaction status against your
own records and replies to us with a final redirection URL. The Sage Pay Server
then redirects your customer back to your website for confirmation of their order
and any other completion pages you wish to display.

Sage Pay provides Integration Kits, which are simple worked examples in various
different scripting languages that perform all the tasks described above. You
simply customise these to work with your particular environment. So whether you
are running .NET, ASP, PHP, Coldfusion, Java or PERL, and whether your servers
are Linux Apache or Win32 IIS, we’ve already done half of the work for you.

The following sections explain the integration process in more detail. The complete
Server Payment integration protocol is attached in the appendix, providing a
detailed breakdown of the contents of the HTTPS messages sent between your
servers and ours during a transaction.

A companion document, “Server and Direct Shared Protocols”, gives details of how
to perform other transaction related POSTs, such as Refunds, Repeat payments,
additional Authorisations and the Release/Abort mechanisms for Deferred
transactions.

Page 4 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

The Server Payment integration Process in Detail

This section details the messages exchanged between your Web servers and the
Sage Pay’s Server system.

Step 1: The customer orders from your site.

A payment begins with the customer ordering goods or services from your site.
This process can be as simple as selecting an item from a drop down list, or can
involve a large shopping basket containing multiple items with discounts and
delivery charges. Your interaction with your customer is entirely up to you and the
Sage Pay Server system only requires you to collect a few compulsory pieces of
information, which are detailed in the latter part of this guide.

It is generally a good idea to identify the customer by name, e-mail address,

delivery and billing address and telephone number. It is also helpful to have your
server record the IP Address from which the user is accessing your system. You
should store these details in your database alongside details of the customer’s
basket contents or other ordered goods.

YOU DO NOT NEED TO COLLECT CREDIT OR DEBIT CARD DETAILS. All your
site needs to do is calculate the total cost of the order in whatever currency your
site operates and present the user with a confirmation page, summarising their
order. On this page there will be a Proceed or Continue button which, when clicked,
will initiate the payment process outlined in the following sections.

Page 5 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

Step 2: Your server registers the payment with Sage Pay.

Once the user has clicked Continue, a script on your web server will construct a
payment registration message (see Appendix A1) and POST it via HTTPS to the
Sage Pay Server transaction registration service.

This POST contains your Vendor Name (chosen by you on the Sage Pay online
application form, or assigned to you by Sage Pay when your account is created)
and your own unique reference to this payment (in a field called VendorTxCode,
which you must ensure is a completely unique value for each transaction).

The message also contains the total value and currency of the payment, and
address details for the customer. You must specify a brief description of the goods
or services purchased, to appear on the payment screen, and provide a URL for the
Sage Pay servers to call back to, once the payment process is complete (this is
called the NotificationURL).

Because this message is POSTed directly from your servers to ours across a 128-bit
encrypted session, no sensitive information is passed via the customer’s browser,
and anyone who attempted to intercept the message would not be able to read it.
Using the Server integration method, you can be assured that the information you
send to us cannot be tampered with, or understood by anyone other than us.

Sage Pay respond to your transaction registration POST (see step 3 below)
synchronously, in the Response object of the same POST.

The integration kits we provide contain scripts in a variety of languages that

illustrate how you compose and send this message from your server to ours.
Please visit the developer’s area of the website at
http://www.sagepay.com/developers.asp to obtain your kit.

Page 6 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

Step 3: Sage Pay reply to the payment registration POST.

On receipt of your POST, our systems start by validating its contents.

Server first checks to ensure all the required fields are present, and that their
format is correct. If any are not present a reply with a Status of MALFORMED is
generated, with the StatusDetail field containing a human readable error message
stating which field is missing. This normally only happens during development
stage whilst you are refining your integration.

If all fields are present, the information in those fields is then validated. The
Vendor name is checked against a pre-registered set of IP addresses, so that
Server can ensure the POST came from a recognised source. The currency of the
transaction is validated against those accepted by your merchant accounts. The
VendorTxCode is checked to ensure it has not been used before. The amount field
is validated. Flag fields are checked, in fact, every field is checked to ensure you
have passed the correct types of value. If any of the information does not check
out, a reply with a Status of INVALID is returned, again with a human readable
error message in StatusDetail explaining what was invalid.

If you receive either a MALFORMED or INVALID message you should use the
detailed response in the StatusDetail error message to help debug your scripts. If
you receive these messages on your live environment, you should inform your
customer that there has been a problem registering their transaction, then flag an
error in your back-office systems to help you debug. You can e-mail the Sage Pay
Support team (support@sagepay.com) for help with your debugging issues.

If everything in the original POST checks out, the transaction is registered with the
Sage Pay Server system and a new transaction code is generated that is unique
across ALL vendors using our payment systems, not just unique to you. This code,
the VPSTxId, is our unique reference to the transaction, and is sent back to you in
the reply along with a Status of OK and a blank StatusDetail field.

Page 7 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

An OK message also contains a SecurityKey field. This is a ten character long,

one use, alphanumeric string used as a key for confirming the MD5 hash signature
in the notification POST (see Step 10 below).

You should store the VPSTxId and SecurityKey, along with your own
VendorTxCode, in your database alongside the customer and order details for this
transaction.

The final component of the reply is a field called NextURL, which is the page to
which you should redirect the customer to allow them to continue with their
purchase.

If the Status is OK, your script should send a redirect request containing this URL to
your customer’s browser.

This is the first stage at which anything noticeable has happened at the customer
end. The HTTPS POST and response described above are completely invisible to
the customer. As far as the customer is concerned they clicked the “Pay Now”
button and now find themselves on Sage Pay’s payment pages.

Page 8 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

Step 4: Customer enters card details on Sage Pay’s

Server.

The customer is presented with a card selection page requesting their credit/debit
card details. If you are a certified PayPal Business account holder and you have
activated PayPal on your Sage Pay account, the PayPal option will also be displayed
to your shoppers on this page. For further information about adding PayPal as a
payment option on your payment pages, please visit the website:
http://www.sagepay.com/developers.asp

The card selection page will contain your company logo and the description of
goods passed in Step 2 above. You can elect to customise these pages further by
producing your own custom templates (please contact templates@sagepay.com if
you require more information about custom templates).

Once the customer has entered their details, the Sage Pay Form system verifies
that information prior to communicating with the bank, to ensure the card number
is valid, the card type matches the card number, the expiry date is not in the past
and, where appropriate, the issue number and start date are in the correct format.
If the customer selects PayPal on the card selection page, the customer is
redirected to PayPal to select their payment method, before being returned to the
Sage Pay order confirmation screen.

If valid card details have been entered, the customer is presented with an order
confirmation screen where they have one last chance to change their mind and
cancel the transaction.

If the customer decides to cancel, you will be sent a cancellation message at the
notification stage (jump to Step 9) and no details are sent to your acquiring bank.

If the customer wishes to continue Sage Pay initiate 3D-Secure authentication

checks.

Page 9 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

Step 5: Sage Pay Server checks 3D-Secure enrolment.

The Sage Pay’s servers send the card details provided by your customer to the
Sage Pay 3D-Secure Merchant Plug-In (MPI). This formats a verification request
called a VEReq, which is sent to the 3D-Secure directory servers to query whether
the card and card-issuer are part of the 3D-Secure scheme.

The 3D Secure directory servers send a verification response called a VERes back to
our MPI where it is decoded, and the Sage Pay system is informed of the inclusion
or exclusion of the card.

If the card or the issuer is not part of the scheme, or if an MPI error occurs, our
server will check your 3D-Secure rule base to determine if authorisation should
occur. By default you will not have a rule base established and transactions that
cannot be 3D-authenticated will still be forwarded to your acquiring bank for
authorisation.

If you do have a rulebase set up, our systems check the rules you have in place to
determine whether you wish the customer to proceed with authorisation, or you
require them to select a different payment method. In such circumstances the
shopper will be returned to the card selection page for another attempt. After the
3rd unsuccessful attempt, the Sage Pay Server contacts your Notification URL (see
step 9) with Status of REJECTED and StatusDetail indicating the reason for the
rejection. The 3DSecureStatus field will contain the results of the 3D-Secure
lookup. REJECTED transactions will never be authorised and the customer’s card
never charged, so you should reply to the notification POST with a RedirectURL
which sends your customer to an order failure page, explaining why the transaction
was cancelled.

If your rule base DOES allow authorisation to occur for non-3D-authenticated

transactions, then the Sage Pay Server continues with the authorisation process
(jump ahead to step 8).

In most cases 3D-secure verification will be possible and process continues below.

Page 10 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

Step 6: Server redirects your customer to their Card

Issuing Bank.

The customer’s browser is redirected

to their Card Issuing Bank’s 3D-
Secure authentication pages. These
vary from bank to bank, but their
purpose is to require the customer to
authenticate themselves as the valid
card holder.

3D-Secure is much like an online

version of Chip and Pin. The customer
must answer questions at their card
issuer site (these might be a simple
password, characters from a password,
or numbers generated via card
devices, depending on the level of
security employed by the bank) and in
so doing, the bank is validating the
customer’s right to use the card for
the transaction on your site.

If they determine that the person

attempting the transaction IS the real
card holder, they assume the liability
for fraudulent use of that card and
you are protected from what are
known as ‘Chargebacks’ if the
cardholder subsequently claims that
their card weas used fraudulently.

This level of protection for you is ONLY afforded by 3D-Secure, which is

why it is a good idea to keep it enabled on your merchant account through
Sage Pay. We set all new accounts with 3D-Secure active by default.

Page 11 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

Step 7: The Issuing Bank returns the customer to the

Sage Pay.

If the customer successfully completes 3D-Authentication with their bank, they are
redirected to Sage Pay along with a unique authentication value (called CAVV for
cards issued by Visa, and UCAF for MasterCard issued cards). This is passed to
your acquiring bank during authorisation (see step 7 below) to secure the liability
shift for the transaction.

If the customer does not successfully 3D-Authenticate with their issuing bank, they
are passed back to the Sage Pay’s server anyway, but without the CAVV/UCAF
value. At this stage the Sage Pay Form system consults your 3D-Secure rule base
to see if authorisation should be attempted. By default 3D-Authentication failures
are NOT sent for authorisation, but all other message types are. Refer to the Sage
Pay Rulebase Guide for more information about using 3D-Secure and AVS/CV2
rules.

If authorisation is not possible, your customer is returned to the card selection

screen to choose an alternative payment method. After three failed attempts, our
server will POST a REJECTED message to your NotificationURL (see step 9 below),
otherwise an authorisation will be gained from your acquiring bank (see step 8)

Page 12 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

Step 8: Sage Pay Server requests card authorisation.

The Sage Pay services format a bank specific authorisation message (including any
3D-Secure authentication values where appropriate) and pass it to your merchant
acquirer over the private banking network.

The request is normally answered within a second or so with either an authorisation

code, or a failure message. This is obtained directly from the issuing bank by the
acquiring bank in real time.

Whilst this communication is ongoing, the customer is shown a page containing the
text, “Please wait while your transaction is authorised with the bank”.

The Sage Pay Server system handles all authorisation failures in the same way,
replying to your site with a NOTAUTHED message and a blank authorisation code
(after three failed attempts. The first two failures return the customer to the card
selection screen to try another card). If the acquirer does return an Authorisation
code, Sage Pay Form prepares an OK response to send back to you (next step).

If AVS/CV2 fraud checks are being performed, the results are compared to any rule
bases you have set up (see the Fraud Screening companion documentation for
more information). If the bank has authorised the transaction but the card has
failed the fraud screening rules you have established, Sage Pay Server immediately
reverses the authorisation with the bank, requesting the shadow on the card for
this transaction to be cleared, and prepares a REJECTED response for your website.

Please note: Some card issuing banks may decline the online reversal
which can leave an authorisation shadow on the card for up to 10 working
days. The transaction will never be settled by Sage Pay and will appear as
a failed transaction in My Sage Pay.

Page 13 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

Step 9: Sage Pay Server contacts your NotificationURL

The Sage Pay Server sends a HTTP or HTTPS POST to the NotificationURL script on
your server to indicate the outcome of the transaction.

This POST contains a Status field that holds either OK, if the transaction was
authorised at step 8, NOTAUTHED if the authorisation was failed by the bank,
ABORT if the user decided to cancel the transaction whilst on our payment pages,
REJECTED if your fraud screening rules were not met, or ERROR if an error has
occurred at Sage Pay (these are very infrequent, but your site should handle them
anyway. They normally indicate a problem with bank connectivity).

The StatusDetail field of the POST contains further human readable details about
the Status field, explaining why a certain status was returned.

The URL to which the completion message is POSTed is the NotificationURL sent
in the original transaction registration (in Step 2 above).

The transaction authorisation results are ALWAYS POSTed to your Notification URL,
so whether the Status is OK, NOTAUTHED, REJECTED, ABORT or ERROR, your
Notification script must decide how to process each message type and redirect the
user accordingly. The integration kits have example pages that show how to
process the Notification POST.

The Notification POST can be over HTTPS if you have an SSL certificate securing
your website. If you do not then the POST will just be HTTP, which means it will be
plain text and not encrypted. The problem with plain text POSTs is that a clever
hacker could intercept the packets of information and modify the response before
sending it on to you (although we must stress this is a very complex and difficult
process). They could, for example, change a NOTAUTHED message to an OK
message. To counteract this, the Notification POST has a VPSSignature field
attached to sign the POST (which is an MD5 hash of the contents of the message)

Your Notification script should read the VendorTxCode and VPSTxId from the
POST and retrieve the relevant information about the order from your database,

Page 14 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

including, most importantly, the SecurityKey for the transaction (which was sent
back to your servers in step 2)

Using the SecurityKey and the contents of the notification POST, your script can
reconstruct that message and run it through a MD5 Hash algorithm. Hash
algorithms are one-way functions (that is, if you pass the same data through the
same algorithm you’ll get the same signature value every time you run it. There is,
however, no way to regenerate the original data from the signature data, even if
you know the algorithm used and the key). Hashing is a standard means of
digitally signing messages in this manner.

Your script can then compare the value it has generated to the VPSSignature
value in the POST. If they match, the message has not been tampered with. If
they do not, then the message may well have been altered in some way and you
can act accordingly by declining the transaction and notifying us immediately!

If the Hash values match, you should store the TxAuthNo field from the
notification POST in your database alongside the VendorTxCode, VPSTxId and
SecurityKey. The TxAuthNo field DOES NOT contain the actual Bank Authorisation
Code because it is not unique (although we do store this in our system for you), but
contains instead a unique reference number to that authorisation that we call the
VPSAuthCode. This is the transaction ID sent to the bank during settlement (we
cannot use your VendorTxCode because it is too long and might contain
unacceptable characters) so the bank will use this value to refer to your transaction
if they need to contact you about it.

As mentioned above, your Notification script must reply to the Notification POST in
all circumstances, irrespective of the Status of the message, otherwise the Sage
Pay transaction monitor will cancel the transaction and keep trying to notify you
about the cancellation (see “Transaction Monitor” later in this document).

If the Sage Pay Server system cannot contact your Notification URL on the first
attempt, it will try to notify you a further 9 times, at approximately 1 second
intervals in case your server is busy. If your Notification URL still cannot be
contacted after 10 seconds (i.e. after the 10th attempt), the transaction is timed out
by the Transaction Monitor (see The Transaction Monitor section later in this
document) and never settled, so your customer is not charged*.

If the transaction is timed out, the Sage Pay system continues to attempt to send
Notification Posts to your Notification URL with a Status of ABORT to inform you of
the cancelled transaction.

*Important note for PayPal transactions: Non-PayPal transactions are timed-

out by the Transaction Monitor and never settled if our Server cannot contact your
Notification URL, however as all PayPal transactions are settled instantly (once the
shopper has returned to the Sage Pay Order Confirmation Page), if there is a
problem with Sage Pay notifying you of the transaction, it is possible that your
PayPal Admin area will display a transaction as successful, but the My Sage Pay
Admin area will state the transaction has failed. We strongly recommend you to log
into your PayPal Admin area regularly, and cancel any transactions which are
displayed as failed in the My Sage Pay Admin area (so that your PayPal Admin area
and My Sage Pay Admin area reconcile).

Page 15 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

Step 10: You reply to the Notification POST

Your notification script should reply to the Sage Pay Server POST with three fields:
Status, which indicates if you wish to accept the transaction notification,
StatusDetail to hold human readable reasons for accepting the transaction or
otherwise, and RedirectURL, which is the completion page on your own site to
which the customer should be redirected by the Sage Pay Server.

You can reply with a Status of either OK, INVALID or ERROR.

ERROR should be used very rarely, and should ONLY be sent if something
unforeseen has happened on your server or database (if you receive a notification
POST for a transaction you cannot find, for instance).

A Status of INVALID should be sent if you are not happy with the contents of the
POST, either because the MD5 hash signatures did not match or you do not wish to
proceed with the order.

OK should be sent if you are happy with the notification and wish to proceed to
charge the customer.

Regardless of status, the RedirectURL must be sent that contains a valid, Fully
Qualified URL (i.e. an address starting http:// or https://) to the final completion
page on your site to which Sage Pay will send your customer.

When the Status is OK, this is normally a page saying “Thank you for your order,
reference 123456, please visit us again.” In the case of INVALID or ERROR, the
RedirectURL will normally point to an error page, normally with a support telephone
number.

If the Status field you send back to our Server is anything other than OK then the
transaction is never settled with the bank (see Step 12) and the customer is NOT
charged for the goods or services (se PayPal exception above). In these
circumstances you should not send goods out to the customer.

Page 16 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

Step 11: Sage Pay Server Redirects the Customer to your

site.

The Sage Pay Server sends a simple HTML page to the customer’s browser that
redirects them to the page on your server pointed to by the RedirectURL field
(sent in step 10 above).

As before, the customer is unaware of the background POST and response process
in the previous two steps. From their perspective they simply clicked “Proceed” on
their payment screens, got a message saying “Authorising please wait…” and then
found themselves back on your website on a completion page of some description.

The real time processing of the transaction by Sage Pay is now complete, but later
in the day, the final stage of the process is carried out between us and the banks
without you or your site needing to do anything.

Page 17 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

Step 12: Sage Pay sends Settlement Batch Files to

confirm payments.

Once per day, after 2:00am, the Sage Pay system batches all authorised
transactions for each acquirer and creates a bank specific settlement file.

Transactions for ALL merchants who use the same merchant acquirer are included
in this file. Every transaction (excluding PayPal transactions*) that occurred from
00:00:00am until 11:59:59pm on the previous day, is included in the files.

They are uploaded directly to the acquiring banks on a private secure connection.
This process requires no input from you or your site. The contents of these batches
and confirmation of their delivery can be found in the My Sage Pay system.

If the file does not transmit correctly, the system tries a further nine times at 10-
minute intervals. If all 10 attempts fail the transactions for that bank are
rescheduled for inclusion in the following day’s batch instead. Sage Pay monitor
this process each day to ensure the files have been sent, and if not, the support
department correct the problem during the day to ensure the file is sent correctly
that evening (or normally resubmit the file manually the same day to ensure funds
are available to all vendors more expediently).

The acquirers send summary information back to Sage Pay to confirm receipt of the
file, then later more detailed information about rejections or errors. If transactions
are rejected, we correct any errors and resubmit them for you. Your bank will
contact you directly if there are payment related problems with the transactions.

*Important note for PayPal transactions: PayPal transactions are settled by

immediately with PayPal. The funds from your customers’ PayPal payments are
deposited into your PayPal Business account immediately. You can then withdraw or
transfer the funds electronically into your specified bank account. Although PayPal
transactions are included in the Settlement Reports displayed within My Sage Pay,
as PayPal transactions are not settled by Sage Pay directly with the banks, we
recommend you to log into your PayPal Admin area to obtain a report of your
PayPal transactions.

Page 18 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

The Transaction Monitor

If the Sage Pay Server system is unable to inform your website of the success or
failure of your transaction (see step 9 above), even after multiple attempts, then
the transaction is placed in suspension.

Likewise, if a customer reaches the Sage Pay payment pages, changes their mind
but does not click Cancel, choosing instead to simply close their browser, or go
elsewhere, then the transaction is stuck in limbo.

Sage Pay guarantee to inform you about the success or failure of every transaction
you send to us, so transactions such as those mentioned above have to be dealt
with.
The Sage Pay transaction monitor is a
service that runs within our secure private
network, monitoring the database, looking
for unfinished transactions that are over 15
minutes old. When it finds one, it cancels
the transactions and sends a POST to your
Notification URL (in exactly the same manner
as in Step 9 above) with a Status of ABORT.

Because the process is identical to a normal

Notification POST, your script should reply as it
would to any ABORT notification POST (see
step 10), with a Status and a RedirectURL.
Because the user is no longer online, no
redirection message will be sent to the client
browser, but our server operates on the
principle that if it receives a reply from your
server, then your site must be aware that the
transaction has been cancelled, so goods will
not be shipped and the user will not be
charged.

If your site does not reply to the ABORT Post, the service continues to try and
notify you at the following intervals:

o 5 attempts at 5 minutes intervals

o 15 attempts at 15 minute intervals
o 13 attempts at 1 hour intervals
o 1 attempt per day for the next 29 days

During this period, the transaction is still classed as ‘active’, and therefore will not
appear within the My Sage Pay reports (where only completed transactions are
listed). If your Notification URL still cannot be contacted after 30 days, the monitor
stops trying, and the transaction will be marked as completed and listed within the
failed transactions tables displayed in My Sage Pay.

Page 19 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

LOW PROFILE Payment Pages

With the Server integration, you have the option of using LOW PROFILE payment
pages (by sending PROFILE=LOW in your transaction registration POST). This
enables you to select a less graphical, simpler set of payment pages instead of the
normal default set.

Low Profile templates are designed to run inside IFRAMEs and present simple HTML
pages with no pop-ups, limited formatting and minimal graphics. This allows you to
ostensibly keep the customer on your own site, whilst actually redirecting them to
the Sage Pay servers to enter their card details.

To use Server in this way, you must obtain an SSL Certificate for your site, and
server the page containing the IFRAME over HTTPS. If you do not, whilst all
transaction information passed between your site and the Sage Pay Systems is
encrypted using our high-security SSL certificates, from a customer's perspective,
the secure padlock will not display in the main browser window and they will be less
likely to enter their card details into what they perceive to be an insecure site.

Please note that you will NOT be able to accept PayPal transactions with
Low Profile templates enabled.

The Low Profile option displays a Card Details page to the shopper (rather than the
initial ‘card selection’ screen), asking for the Card information and Billing Address
details.

If 3D Secure is active on your account, the customer is redirected to the card

issuing bank’s 3D Secure page as in normal profile, but the page will not be
returned as the main content in your IFRAME (not wrapped with a Sage Pay screen).

Page 20 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

Once the shopper completes 3D Authentication, (or if 3D Secure is disabled on your

account), the shopper is presented with a simpler “authorising please wait screen”,
again in your IFRAME.

Your NotificationURL is contacted in the normal manner and you should reply with a
RedirectURL. VERY IMPORTANT: Your customer will be redirected back to the
page you supply, but they will be inside your own IFRAME. The code on the
RedirectURL page will need to break out of the IFRAME to return the customer to
full screen pages on your website. Examples of how to do this will be provided in
future releases of the integration kits.

You have the option of customising the Low Profile pages, (including the ‘ReadOnly’
and ‘NoAddress’ options) so that the look and feel of the payment pages is similar
to your own site. For further information about how you can customise the LOW
PROFILE payment pages, please refer to the Sage Pay Custom Templates Kit, which
can be obtained from the developer’s area on our website:

http://www.sagepay.com/developers.asp

Page 21 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

Integrating with Sage Pay Server

Linking your Website to Sage Pay Server involves creating two scripts (or modifying
the examples provided in the integration kits), one to register the transaction with
our servers, process the response we send back and redirect the customer across
to us; and the other to handle the notification call-back from our servers, process
the message and respond with a Status and RedirectURL.

Stage 1
The Sage Pay Simulator system is the starting point for your integration. This user-
friendly expert system on our test environment analyses the messages your site
sends to us, reports any errors therein, and simulates all possible responses from
the real Sage Pay live environment.

The Sage Pay Simulator can be configured on the following URL:

https://test.sagepay.com/Simulator

Payment transactions should be sent from your scripts to the following URL:
https://test.sagepay.com/Simulator/VSPServerGateway.asp?Service=VendorRegisterTx

Stage 2
Once your site is able to talk to Sage Pay Simulator and process all possible
outcomes, you will be able to move over to the Sage Pay Test Server. This is an
exact copy of the live site but without the banks attached and with a simulated 3D-
Secure environment. Authorisations on the test server are only simulated, but the
user experience is identical to Live, and a version of the My Sage Pay pages also
runs here so you can familiarise yourself with the features available to you.

The My Sage Pay admin system for viewing your Test transactions is at:
https://test.sagepay.com/mysagepay

Transactions from your scripts should be sent to the Sage Pay Test Server at:
https://test.sagepay.com/gateway/service/vspserver-register.vsp

Stage3
Once you are happily processing end-to-end transactions on the test server and we
can see test payments and refunds going through your account, AND you’ve
completed the online Direct Debit signup, your account on the Live Server is
activated for you to start using. You will need to redirect your scripts to send
transactions to the live service, send through a Payment using your own credit card,
then VOID it through the My Sage Pay Admin service so you don’t charge yourself.
If this works successfully, then you are ready to trade online.

The Live My Sage Pay Admin screens are at:

https://live.sagepay.com/mysagepay

Transactions from your scripts should be sent to the Sage Pay Live Server at:
https://live.sagepay.com/gateway/service/vspserver-register.vsp

Page 22 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

Stage 1: Integrating with the Sage Pay Simulator

The Sage Pay Simulator is an expert system that emulates the Sage Pay Server
system and allows you to develop your site to correctly send and process the
messages exchanged between your site and ours. The Simulator will provide more
detailed feedback of any errors or issues than the real Sage Pay Server, allowing
you to debug and enhance your code.

Log into the Sage Pay Simulator at https://test.sagepay.com/simulator and enter

your Vendor Name (as you selected on the Online Registration forms) and the
password (also the same as that used on those forms. You can change it in the
Simulator if you wish).

If you wish to test your integration with Sage Pay before you have obtained a
Merchant Account, you can do so free of charge with the Sage Pay Simulator. To
register for a Simulator account, please visit our website:

https://support.sagepay.com/apply/requestsimaccount.aspx

When you log in to the Sage Pay Simulator you will be presented with the main
menu screen. Extensive help is provided in the Simulator (click the context
sensitive Help button on each screen for more details) so this document will not
cover everything in too much detail, but outlined in subsequent sections are the
important steps you should take to get your site talking to the Simulator.

Page 23 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

1: Sage Pay Simulator Account Set up

Click the Account button in the main menu to open the following screen:

You should ensure that:

• all company details are correct.

• all technical details about web server and platform are correct.
• the “Simulate Server” box is checked.
• all relevant payment types have been set up.
• you have at least one payment currency set up (usually GBP unless your site
accepts multi-currency transactions).
• the IP addresses of your servers are listed.

Add and/or correct any entries and click the Update button to save any changes.
Back takes you back to the main menu.

Page 24 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

2: Server Integration method Set up

Click the Server button in the main menu to open the Server options page.

This page allows you to define the behaviour of the Sage Pay Simulator when it
responds to your initial transaction registrations (Steps 2 and 3 of the payment
process described above). By default the system will verify your POST to ensure
the contents are correctly formatted and if they are, return a Status of OK, a
VPSTxId, a SecurityKey and a NextURL. If your POST is incorrectly formatted or
contains bad data, it will respond with a Status of MALFORMED or INVALID and
explain what was wrong in the StatusDetail field.

You can use this page to force errors even if your data is okay. This is useful when
testing upgrades to your scripts and proofing your error handling routines.

For now you should leave the default setting of Automatic (clicking Update if
necessary) then log out of the Simulator.

Page 25 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

3: Registering a Payment
If you don’t plan to implement the protocol entirely on your own, you should install
the most appropriate integration kit or worked example for your platform. These
can be obtained from the development area on the Sage Pay website
http://www.sagepay.com/developers.asp.

The kits will not quite run out of the box because you have to provide some specific
details about your site in the configuration files before a transaction can occur, but
they will provide end to end examples of registering the transactions and handling
the notification POSTs. Ensure you’ve completed all configuration in the includes
file as detailed in the kit instructions, then locate the Transaction Registration script
(called transactionRegistration).

This script provides a worked example of how to construct the Transaction

Registration POST (see Appendix A section A1 in the attached protocol) and how to
read the response that comes back (section A2).

Check that this script is sending transactions to the Sage Pay Simulator (rather
than the test or live sites), then execute this page, passing it some dummy
transaction data, to send a payment registration to the Simulator. You may wish to
modify the script at this stage to echo the results of the POST to the screen, or a
file, so you can examine the Status and StatusDetail reply fields to check for errors.

Once your script can successfully register a Payment and you receive a Status of
OK, you should ensure your code stores the VPSTxId and SecurityKey alongside
your uniquely generated VendorTxCode and the order details in your own database
before redirecting the browser to the URL sent by us in the NextURL field.

At this stage it is wise to log in to Sage Pay Simulator in a separate browser

window and change the response type to each of the error messages in turn so you
can write code in your registration page to handle each error appropriately (by
logging the error, informing the user that a problem has occurred, perhaps giving
them a phone number to call instead and alerting support staff as appropriate).

When you are happy that your script can handle all errors, set the Server option
setting back to Automatic so your script can redirect the user to the Simulator
payment pages.

Page 26 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

4: Handling the Server payment Callback

After your site has passed the customer across to the Sage Pay payment pages,
they enter their card details and the bank authorise their transaction (an OK
response) or fail it (a NOTAUTHED response), or Sage Pay may reverse an
authorisation if your fraud screening rules are not met (a REJECTED response).
The customer may also change their mind and click Cancel on one of the payment
pages (an ABORT response).

Irrespective of the type of feedback the Sage Pay Server needs to send you, the
message is always sent to the same script on your server. We refer to this script
as the Notification Script and it is pointed to by the contents of the NotificationURL
field you sent to us in step 2 of the process above (see the protocol section A1). In
your kits this script is normally called notificationPage.

The Simulator will show you the contents of your registration POST, including the
NotificationURL, in the screens following the redirection step. The final page will
allow you to choose which type of message you wish to send back to your
Notification script from our servers.

You can choose not only the type of message sent back, but also the results of the
additional fraud checks. For now, leave everything set as default (MATCHED and
OK) and click the OK button to send back a positive response (mimicking a
successfully authorised transaction).

This message (see Steps 9 and 10 in the payment process above, and section A3 in
the Appendix) is POSTed to your Notification script, which should process it and
reply with a Status and a RedirectURL (see Appendix A4).

Page 27 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

Processing the Notification POST is slightly more complex because you need to
validate the MD5 digital signature that is attached to the message to ensure it has
not been tampered with and genuinely comes from Sage Pay. The example scripts
in the Integration Kits show you how to do this, but the steps are:

1. Split the fields out of the POST to obtain the authorisation result, transaction
ids and VPSSignature value.
2. Use the transaction ids to look up the order in your database and retrieve
the SecurityKey passed to you during transaction registration.
3. Rebuild the Notification POST using the contents of your database and the
POST itself in the order specified in the protocol (see A3).
4. Pass that data through a MD5 hashing algorithm (provided either as part of
your scripting language or as part of our kits) to generate a hash value.
5. Compare that hash value to the contents of the VPSSignature field. If they
match, the data has not been tampered with. If they do not, either the data
has been modified or there is a mismatch between your data and ours, and
the transaction should be cancelled.

If the signatures match, your Notification Script should respond with a Status of OK
and a RedirectURL pointing to either an order completion page (if the Status was
OK) or an appropriate order failure page (if the Status was NOTAUTHED or ERROR).
You may wish ABORT messages to redirect the customer to a page providing them
with alternative methods of payment, or asking them why they chose to cancel.

If the signatures do not match, you should check that your code is rebuilding the
message correctly, and if you are sure that it is, all such messages should be
responded to with an INVALID and a RedirectURL pointing the user to a failure page.

If you cannot find the transaction we are notifying you about, you should return an
ERROR Status and a RedirectURL pointing to an error page.

The Sage Pay Simulator will show you the response returned by your notification
script. If the page throws an error, this error will be displayed to enable you to
debug it. If it responds correctly, with a Status and a RedirectURL, you will be
shown a Redirect button that will send the browser to your completion page.

Important Note: Your Notification URL should ONLY respond with a Status field, a
RedirectURL field and optionally a StatusDetail field. No other HTML, headers,
comments or text should be included either before or after these fields. The Sage
Pay Server will treat all such text as an error and fail the transaction!

For OK responses, you should store the TxAuthNo field against the other fields in
your database for this transaction. This reference number uniquely identifies the
transaction with your acquiring bank and they are likely to quote you this value if
there are issues with it.

You should use the Sage Pay Simulator to send each type of message (OK, ABORT,
NOTAUTHED, REJECTED and ERROR) to your notification page to check that all
message types are handled correctly. You may also wish to add code that stores
the 3DSecureStatus and CAVV fields, if you plan to use Visa and Mastercard’s
extended fraud checking systems (Verified by Visa, VbV, and Mastercard Secure
Code, MSC), and specific code that stores or reacts to the AVS and CV2 results
(additional card security checks). See our Fraud Screening document for more
information about these systems.

Page 28 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

5: Examining your transactions

The Sage Pay Simulator keeps the last month’s worth of simulated transactions
online for you to examine at your leisure. Using the Transactions button you can
view everything you’ve sent us to ensure the data is as you expected.

You can also see from this screen which transactions have been subsequently
refunded or used as the basis for repeat payments.

Once your site can initiate transactions AND handle the callbacks, then you’ve
completed the basic Sage Pay Server integration and can move on to testing your
site against the real Sage Pay Servers, firstly on the Test Server (see the next main
section). If, however, you wish to link in additional processes, such as Refunds or
Repeats, or the ability to Release or Abort Deferred transactions, you should
continue with step 6 below.

Page 29 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

Stage 2: Testing on the Test Server

If your site works correctly against the Sage Pay Simulator then this is normally a
very quick step. The Test Server is an exact copy of the Live System but without
the banks attached. This means you get a true user experience but without the
fear of any money being taken from your cards during testing.

In order to test on the Test Server, however, you need a Test Server account to be
set up for you by the Sage Pay Support team. These accounts can only be set up
once you have completed all sections of the Online Registration forms
(https://support.sagepay.com/apply/) including the Merchant Account section.
Often when applying to trade online it takes a while for the Merchant Account to be
assigned by your acquirer, so you may wish to ensure that you set those wheels in
motion before you begin your integration with Sage Pay, to ensure things don’t
bottleneck at this stage.

The Support Team will set up an account for you on the Test Server under the
same Vendor Name as your online application form and Simulator account. You will,
however, be issued with different passwords for security purposes. The Support
Team will let you know how to retrieve those passwords and from there how to use
the My Sage Pay Admin screens to look at your transactions.

To link your site to the Test Server, you need only to change your transaction
registration script to send the message to the Test Server URL for the Server
integrated payment method rather than the Simulator. In many kits this is done
simply by changing the strConnectTo string in the includes file to “TEST”. If
you’ve been developing your own scripts, then the Test Site URL for payment
registration is:

https://test.sagepay.com/gateway/service/vspserver-register.vsp
(for other transaction types, the final server-register.vsp section would be changed
to refund.vsp, release.vsp, void.vsp etc.)

When your site redirects the customer you will find yourself on the real Sage Pay
payment pages rather than the Simulator.

You will always receive an OK message and an Authorisation Code from the test
server if you are using one of the test cards listed below. All other valid card
numbers will be declined, allowing you to test your failure pages. If you do not use
the correct Address, Post Code and CV2 digits, the transaction will still authorise,
but you will receive NOTMATCHED messages in the AVS/CV2 checks, allowing you
to test your rule-bases and fraud specific code.

Any cardholder name and start/expiry dates will be accepted for these cards so long
as the dates are valid and the card not expired.

Page 30 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

Card Type Card Number Issue CV2 Address PostCode

Visa Credit 4929000000006 123 88 412
MasterCard Credit 5404000000000001 123 88 412
Visa Debit / Delta 4462000000000003 123 88 412
Solo 6334900000000005 1 123 88 412
UK Maestro 5641820000000005 01 123 88 412
American Express 374200000000004 123 88 412
Visa Electron 4917300000000008 123 88 412
JCB 3569990000000009 123 88 412
Diner’s Club 36000000000008 123 88 412
Laser (LASER) 6304990000000000044 123 88 412

If you have 3D-Secure set up on your test account, you can use the My Sage Pay
Admin interface to switch on the checks at this stage to test 3D-Secure.

This simulation is more advanced than the Sage Pay Simulator process because it
creates real 3D-secure messages. It does not talk to the Visa and MasterCard
systems though, so no live authentications can occur.

At the Simulated Authentication screens, to successfully authenticate the

transaction, enter “password” (without the quotes) into the password box. Any
other phrase will fail the authentication, allowing you to test your rules and 3D-
Secure response handling. We’ll be extending this to allow you to simulate all 3D-
Secure responses.

The process will then continue as per the Live Servers. Only the authorisation
stage is simulated.

Once you’ve checked you can process an end-to-end transaction and tested any
additional transaction types you have set up (such a Refunds and Releases) then
you are almost ready to go live. Before doing so, however, you should log in to the
My Sage Pay Admin system on the test servers to view your transactions and
familiarise yourself with the interface.

Page 31 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

The Test Server My Sage Pay interface

A Test Server version of the My Sage Pay Admin system is available to you whilst
using your test account to view your transactions, refund payments, release
deferred payments, void transactions etc. You should familiarise yourself with this
system on the Test Server before you go live so you know how to use the system
on the Live Servers.

The Test Server My Sage Pay can be found at:

https://test.sagepay.com/mysagepay

When you log in to the My Sage Pay Admin screens you will be asked for a Vendor
Name, a User Name and a Password. The first time you log in you will need to
do so as your system Administrator:

• In the Vendor Name box, enter your Vendor Name, as selected in your
Online Registration screens and used throughout the development as your
unique merchant identifier.
• In the User Name box, enter the Vendor Name again.
• In the Password box, enter the My Sage Pay Admin password as supplied
to you by Sage Pay when your test account was set up.
• Click Login.

Page 32 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

The administrator can ONLY create user accounts, unlock other accounts and
change account parameters. You cannot, whilst logged in as administrator, view
your transactions or take payments through the online terminal.

To use those functions, and to protect

the administrator account, you need to
create new users for yourself and others.
Click the Add button to add a new user.

Enter a username for yourself and a

password you’ll remember, then ensure
all the check boxes are enabled for your
account. Click the Add button and your
new account will appear in the list.

Now click the Logout button and click to

Log back in, this time entering:

• Your Vendor name in the Vendor

Name box.
• The User Name of the account
you just created in the User
Name box.
• The password for the account you
just created in the Password box.

…and click Login.

You are now logged in using your own account and can view your test transactions
and use all additional functions. You need only log in as Administrator again if you
wish to create additional users, or if you lock yourself out of your own account, you
can use the Administrator account to unlock yourself. If you happen to lock out the
Administrator account, you will need to contact Sage Pay to unlock it for you.

Detailed context sensitive help is available on every Admin page by clicking the
Help button, so a description of the functions will not be presented here. Play with
the system until you are comfortable with it though, you cannot inadvertently
charge anyone or damage anything whilst on the test server.

Page 33 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

Additional Transaction Types

Sage Pay supports a number of additional methods of registering a transaction and

completing the payment.

DEFERRED transactions.

By default a PAYMENT transaction type is used in your scripts to gain an

authorisation from the bank, then settle that transaction early the following
morning, committing the funds to be taken from your customer’s card.

In some cases you may not wish to take the funds from the card immediately, but
merely place a “shadow” on the customer’s card to ensure they cannot
subsequently spend those funds elsewhere, and then only take the money when
you are ready to ship the goods. This type of transaction is called a DEFERRED
transaction and is registered in exactly the same way as a normal PAYMENT. You
just need to change your script to send a TxType of DEFERRED when you register
the transaction (protocol A1) instead of PAYMENT.

DEFERRED transactions are NOT sent to the bank for completion the following
morning. In fact, they are not sent at all until you RELEASE them by logging into
the My Sage Pay interface, finding the transaction and clicking the Release button.

You can release ONLY ONCE and ONLY for an amount up to and including
the amount of the original DEFERRED transaction.

If you are unable to fulfil the order, you can also ABORT deferred transactions in a
similar manner and the customer will never be charged.

DEFERRED transactions work well in situations where it is only a matter of days

between the customer ordering and you being ready to ship. Ideally all DEFERRED
transaction should be released within 6 days (according to card scheme rules).
After that the shadow may disappear from the card before you settle the
transaction, and you will have no guarantee that you’ll receive the funds if the
customer has spent all available funds in the mean time. If you regularly require
longer than 6 days to fulfil orders, you should consider using AUTHENTICATE and
AUTHORISE instead of DEFERRED payments (see below)

DEFERRED transactions remain available for RELEASE for up to 30 days. After that
time they are automatically ABORTed by the Sage Pay systems.

Additional notes for using Deferred/Release with PayPal transactions

Unlike a normal Sage Pay DEFERRED transaction, no shadow is placed on the

customer’s card for a PAYPAL DEFERRED transaction. An order is simply registered
with the PayPal account and a successful authorisation for a DEFERRED transaction
only confirms the availability of funds and does not place any funds on hold.

When you RELEASE a DEFERRED PayPal transaction PayPal applies best efforts to
capture funds at that time, but there is a possibility that funds will not be available.

We recommend that you do not ship goods until after obtaining a

successful release.

Page 34 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

REPEAT payments

If you have already successfully authorised a customer’s card using as PAYMENT, a

released DEFERRED or an AUTHORISE (see below) you can charge an additional
amount to that card using the REPEAT transaction type, without the need to store
the card details yourself.

If you wish to regularly REPEAT payments, for example for monthly subscriptions,
you should ensure you have a “Continuous Authority” merchant number from your
bank (please contact your acquiring bank for further details), but ad-hoc REPEATs
do not require a Continuous Authority merchant number. REPEAT payments cannot
be 3D-Secured, or have CV2 checks performed on them (unless you supply those
values again. Sage Pay are not allowed to store CV2 numbers) so you are better to
make use of Authenticate and Authorise if you need to vary the transaction amount
on a regular basis.

You can only REPEAT a PayPal transaction if the initial transaction was set up as a
PayPal Reference transaction (with BillingAgreement set to 1. See the Appendix for
details).

AUTHENTICATE and AUTHORISE

The AUTHENTICATE and AUTHORISE methods are specifically for use by merchants
who are either (i) unable to fulfil the majority of orders in less than 6 days (or
sometimes need to fulfil them after 30 days) or (ii) do not know the exact amount
of the transaction at the time the order is placed (for example, items shipped priced
by weight, or items affected by foreign exchange rates).

Unlike normal PAYMENT or DEFERRED transactions, AUTHENTICATE transactions do

not obtain an authorisation at the time the order is placed. Instead the card and
card holder are validated using the 3D-Secure mechanism provided by the card-
schemes and card issuing banks, with a view to later authorisation.

Your site will register your transaction with a TxType of AUTHENTICATE, and
redirect the customer to Sage Pay Server to enter their card details. Sage Pay
Server will contact the 3D-Secure directories to check if the card is part of the
scheme. If it is not, then the card details are simply held safely at Sage Pay and
your SuccessURL is sent a Status of REGISTERED (This also happens if you do not
have 3D-Secure active on your account or have used the Apply3DSecure flag to
turn it off).

If, however, the card is part of the 3D-Secure scheme, the customer is redirected
to their card issuing bank for authentication (just like a normal 3D-Secure payment,
see steps 5-7 in the Payment Process above). Here they will authenticate
themselves and be returned to Sage Pay Server.

If they have not passed authentication, your rule base is consulted to check if they
can proceed for authorisation anyway. If not, your NotifcationURL is sent a Status
of REJECTED. If they failed authentication but can proceed, your NotificationURL
is sent a REGISTERED status. If the user passed authentication with their bank
and a CAVV/UCAF value is returned, a Status of AUTENTICATED and a CAVV
value is returned, for you to store if you wish.

Page 35 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

In all cases, the customer’s card is never authorised. There are no shadows placed
on their account and your acquiring bank is not contacted. The customer’s card
details and their associated authentication status are simply held at Sage Pay for up
to 90 days (a limit set by the card schemes, 30 days for International Maestro
cards) awaiting an AUTHORISE or CANCEL request from your site (see the
“Server and Direct Shared Protocols” document for details of these messages).

To charge the customer when you are ready to fulfil the order, your site will need to
send an AUTHORISE request. You can Authorise any amount up to 115% of the
value of the original Authentication, and use any number of Authorise requests
against an original Authentication so long as the total value of those authorisations
does not exceed the 115% limit, and the requests are inside the 90 days limit. This
is the stage at which your acquiring bank is contacted for an auth code. AVS/CV2
checks are performed at this stage and rules applied as normal. This allows you
greater flexibility for partial shipments or variable purchase values. If the
AUTHENTICATE transaction was AUTHENTICATED (as opposed to simply
REGISTERED) all authorisations will be fully 3D-Secured, so you will still receive the
fraud liability shift.

When you have completed all your Authorisations, or if you do not wish to take any,
you can send a CANCEL message to our Server to archive away the Authentication
and prevent any further Authorisations being made against the card. This happens
automatically after 90 days.

Both AUTHORISE and CANCEL operations can also be performed within the My Sage
Pay Admin area.

REFUNDs and VOIDs

Once a PAYMENT, AUTHORISE or REPEAT transaction has been authorised, or a

DEFERRED transaction has been RELEASEd, it will be settled with the acquiring
bank early the next morning and the funds will be moved from the customer’s card
account, across to your merchant account. The bank will charge you for this
process, the exact amount depending on the type of card and the details of your
merchant agreement.

If you wish to cancel that payment before it is settled with the bank the following
morning, you can send a VOID message to our servers to prevent the transaction
ever being settled (see the “Server and Direct Shared Protocols” document for
more detail), thus saving you your transaction charges and the customer from ever
being charged. You can also VOID transactions through the My Sage Pay Admin
interface. VOIDed transactions can NEVER be reactivated though, so use this
functionality carefully.

Once a transaction has been settled, however, you can no longer VOID it. If you
wish to return funds to the customer you need to send a REFUND message to our
servers, or use the My Sage Pay Admin screens to do the same.

You can REFUND any amount up to the value of the original transaction. You can
even send multiple refunds for the same transaction so long as the total value of
those refunds does not exceed the value of the original transaction. Again, the
REFUND protocol can be found in the “Server and Direct Shared Protocols”
document.

You cannot VOID a PayPal transaction, but you are able to REFUND a PayPal
transaction.

Page 36 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

The Sage Pay Simulator and Additional Transaction Types

The Sage Pay Simulator can handle all the additional transaction types discussed
above. It will accept PAYMENT, AUTHENTICATE and DEFERRED transactions at the
registration stage, plus it has services that emulate those of the real servers when
you send REFUND, RELEASE, ABORT, REPEAT, AUTHORISE, CANCEL and VOID
messages to it.

The additional transaction types, however, do not have a user configurable

interface associated with them. By default they are all set to Automatic mode, so
they will respond with an OK unless the data you send would generate a
MALFORMED or INVALID response.

For information regarding registering additional transaction types using HTTPS

POSTS, please refer to the Server and Direct Shared Protocols Guide, which can be
obtained from the developer’s area on our website:

http://www.sagepay.com/developers.asp

Page 37 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

Stage 3: Going Live

Once Sage Pay receives your application your account will be created and details
will be sent to the bank for confirmation. The bank will be expected to confirm your
merchant details within 3 to 5 working days. Once both the Direct Debit (filled out
during application) and the confirmation of your merchant details reach Sage Pay,
your account will become Live automatically.

This does not mean you will immediately be able to use your Live account

You must ensure you have completed testing of your account before you are
granted access to your Live account. Details can be found below:

http://www.sagepay.com/developers/integration_manual/processes_go%20live.ht
ml

NB – Without confirmation from the bank and without Direct Debit submission,
Sage Pay will not be able to set your account Live. You will only be charged by Sage
Pay when your account has valid Direct Debit and confirmation of your merchant
details from the bank.

Once your Live account is active, you should point your website transaction
registration scripts to the following URL:

https://live.sagepay.com/gateway/service/vspserver-register.vsp

(for other transaction types, the server-register.vsp section would be changed to

refund.vsp, void.vsp, release.vsp etc.)

You should then run an end-to-end transaction through your site, ordering
something relatively inexpensive from your site and paying using your own valid
credit or debit card. If you receive an authorisation code, then everything is
working correctly.

You should then log into the Live Server My Sage Pay screens at
https://live.sagepay.com/mysagepay and in a similar manner to the test server,
first log in as the Administrator, then create a Live System User account for
yourself, log in as that user, locate your test transaction and VOID it, so you are
not charged for the transaction. At this stage the process is complete.

It is worth noting here that none of the users you set up on the My Sage Pay
system on the Test Server are migrated across to Live. This is because many
companies use third party web designers to help design the site and create users
for them during test that they would not necessarily like them to have in a live
environment. You will need to recreate any valid users on the Live system when
you first log in.

Page 38 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

Congratulations, you are live with Sage Pay Server.

Well done. Hopefully the process of getting here was as painless and hassle free as
possible. You’ll be pleased to know that now you are live we don’t cut the strings
and run away. You should contact us with any transaction queries that arise or for
any help you need with the My Sage Pay system.

Here are the best ways to reach us and the best people to reach:

• If you require any information on additional services, e-mail

sales@sagepay.com

• If you have a query regarding a Sage Pay invoice, e-mail

finance@sagepay.com

• If you have a question about a transaction, have issues with your settlement
files, are having problems with your payment pages or My Sage Pay screens,
or have a general question about online payments or fraud, e-mail
support@sagepay.com with your Sage Pay Vendor Name included in the
mail.

• If you have any suggestions for future enhancements to the system, or

additional functionality you’d like to see added, please e-mail
feedback@sagepay.com with your comments. We do take all comments on
board when designing upgrades, although we may not be able to answer
every mail we get.

• You can call us as well on 0845-111-4455, for any type of enquiry.

We will also keep you updated about major system changes, new reports and other
enhancements via the Updates section in My Sage Pay, plus your e-mail address
will be added to our group mail list used to alert you to upgrades and other pending
events.

You can also always check our system availability and current issues on the Sage
Pay Monitor page at http://www.sagepay.com/system_monitor.asp

Thanks again for choosing Sage Pay, and we wish you every success in your e-
commerce venture.

Page 39 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

Appendix A - The Sage Pay Server 2.23 Protocol

This section details the Sage Pay Server Protocol. It details the contents of the POSTs and responses, between your website and ours. The
format and size of each field is given, along with accepted values and characters. The legend below explains the symbols:

Accented Characters New line (Carriage Return and Line Feed)

Ampersand character Numbers
At sign Plus sign
Colon Parentheses
Comma Semi-colon
Curly Brackets Apostrophe (single quote)
Full Stop/Period Backslash and Forward Slash
Hyphen Space
Letters (A-Z and a-z) Underscore
ISO 3166-1 2-letter country codes Valid Base64 characters (A-Z,a-z,0-9,+ and /)
Valid 2-letter US States ISO 4217 3-letter Currency codes
RFC 1738 compliant HTTP(S) URL
All non-compliant characters, including
spaces, should be URL Encoded
Valid HTML with no active content. Script will be filtered. Includes all valid letters, numbers,
punctuation and accented characters.
RFC 5321/5322 (see also RFC 3696) compliant e-mail Addresses.

Page 40 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

A1: Transaction registration

This is performed via a HTTPS POST request, sent to the initial Sage Pay Payment URL service server-register.vsp. The details should be URL
encoded Name=Value fields separated by ‘&’ characters.

Request format (continued overleaf)

Name Format Values Comments
VPSProtocol Numeric. 2.23 in this release Default or incorrect value is taken to be 2.23.
Fixed 4 characters.

TxType Alphabetic PAYMENT, DEFERRED or See companion document “Server and Direct Shared Protocols” for
Max 15 characters. AUTHENTICATE ONLY other transaction types (such as Refund, Releases, Aborts and
Repeats). The value should be in capital letters.

Vendor Alphanumeric Vendor Login Name Used to authenticate your site. This should contain the Sage Pay
Max 15 characters. Vendor Name supplied by Sage Pay when your account was created.

VendorTxCode Alphanumeric Vendor Transaction Code This should be your own reference code to the transaction. Your site
Max 40 characters should provide a completely unique VendorTxCode for each
transaction.
Amount Numeric. Amount for the Transaction containing minor Must be positive and numeric, and may include a decimal place where
0.01 to 100,000.00 digits formatted to 2 decimal places where appropriate. Minor digits should be formatted to two decimal places.
appropriate. e.g. 5.10, or 3.29. Values such as 3.235 will be rejected. Minimum
for no minor unit currencies like JPY is 1.

Currency Alphabetic Three-letter currency code to ISO 4217 The currency must be supported by one of your Sage Pay merchant
3 characters Examples: GBP, EUR and USD accounts or the transaction will be rejected.

Description Alphanumeric Free text description of goods or services being The description of goods purchased is displayed on the Sage Pay
Max 100 characters purchased Server payment page as the customer enters their card details.

NotificationURL Alphanumeric Fully qualified URL (including http:// or https:// Callback URL to which Notification POSTs are sent (see step A3).
Max 255 characters header).

Page 41 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

Request format (continued…)

BillingSurname Alphabetic Customer’s surname In Protocol 2.23, unlike previous protocols, the Billingxxxxx columns
Max 20 characters are compulsory.

BillingFirstnames Alphabetic Customer’s first names

Max 20 characters

BillingAddress1 Alphanumeric First line of billing address

Max 100 characters

Optional: Alphanumeric Second line of billing address

Max 100 characters
BillingAddress2

BillingCity Alphanumeric City component of the address

Max 40 characters

BillingPostCode Alphanumeric The Post/Zip code of the Billing Address

Max 10 characters

BillingCountry Alphabetic ISO 3166-1 country code of the cardholder’s

Max 2 characters billing address

Optional*: Alphabetic State code for US customers only*

Max 2 characters
BillingState
Optional: Alphanumeric Phone number at billing address
Max 20 characters
BillingPhone
DeliverySurname Alphabetic Customer’s surname
Max 20 characters In Protocol 2.23, unlike previous protocols, the Deliveryxxxx columns
are compulsory.
DeliveryFirstnames Alphabetic Customer’s first names
Max 20 characters

DeliveryAddress1 Alphanumeric First line of delivery address

Max 100 characters

Optional: Alphanumeric Second line of delivery address

Max 100 characters
DeliveryAddress2

Page 42 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

Request format (continued…)

DeliveryCity Alphanumeric City component of the address
Max 40 characters

DeliveryPostCode Alphanumeric The Post/Zip code of the delivery address

Max 10 characters

DeliveryCountry Alphabetic ISO 3166-1 country code of the cardholder’s

Max 2 characters delivery address

Optional*: Alphabetic State code for US customers only*

Max 2 characters
DeliveryState
Optional: Alphanumeric Phone number at delivery address
Max 20 characters
DeliveryPhone
Optional: Alphanumeric The customer’s e-mail address. The current version of the Server integration method does not send
Max 255 characters NOTE: If you wish to use multiple e-mail confirmation e-mails to the customer. This field is provided for your
CustomerEMail
addresses, you should add them using the : records only.
(colon) character as a separator. e.g.
me@mail1.com:me@mail2.com

Optional: Alphanumeric See the next page for the Format of the Basket You can use this field to supply details of the customer’s order. This
Max 7500 characters field information will be displayed to you in My Sage Pay.
Basket

Optional: Flag 0 = No Gift Aid Box displayed (default) This flag allows the gift aid acceptance box to appear for this
1 = Display Gift Aid Box on payment screen. transaction on the payment page. This only appears if your vendor
AllowGiftAid
account is Gift Aid enabled.

Optional: Flag 0 = If AVS/CV2 enabled then check them. If Using this flag you can fine tune the AVS/CV2 checks and rule set
rules apply, use rules. (default) you’ve defined at a transaction level. This is useful in circumstances
ApplyAVSCV2
1 = Force AVS/CV2 checks even if not enabled where direct and trusted customer contact has been established and
for the account. If rules apply, use rules. you wish to override the default security checks.
2 = Force NO AVS/CV2 checks even if enabled
on account. This field is ignored for PAYPAL transactions
3 = Force AVS/CV2 checks even if not enabled
for the account but DON’T apply any rules.

Page 43 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

Request format (continued…)

Optional: Flag 0 = If 3D-Secure checks are possible and rules Using this flag you can fine tune the 3D Secure checks and rule set
allow, perform the checks and apply the you’ve defined at a transaction level. This is useful in circumstances
Apply3DSecure
authorisation rules. (default) where direct and trusted customer contact has been established and
1 = Force 3D-Secure checks for this transaction you wish to override the default security checks.
if possible and apply rules for authorisation.
2 = Do not perform 3D-Secure checks for this This field is ignored for PAYPAL transactions
transaction and always authorise.
3 = Force 3D-Secure checks for this transaction
if possible but ALWAYS obtain an auth code,
irrespective of rule base.
Optional: Alphabetic NORMAL (DEFAULT) or LOW A profile of LOW returns the new simpler payment pages which have
Max 10 characters only one step and minimal formatting. Designed to run in i-Frames.
Profile
Omitting this field or sending NORMAL renders the normal card
selection screen.

Optional: Flag 0 = This is a normal PayPal transaction, not the This field must be set for PAYPAL REFERENCE transactions
first in a series of payments (default) All non-PayPal transactions can be repeated without this flag.
BillingAgreement
1 = This is the first in a series of PayPal If you wish to register this transaction as the first in a series of regular
payments. Subsequent payments can be taken payments, this field should be set to 1. If you do not have a PayPal
using REPEAT. account set up for use via Sage Pay, then this field is not necessary
and should be omitted or set to 0.
Optional: Alphanumeric E = Use the e-commerce merchant account This optional flag is used to tell the SAGE PAY System which merchant
1 character (default). account to use. If omitted, the system will use E, then M, then C by
AccountType
C = Use the continuous authority merchant default.
account (if present).
M = Use the mail order, telephone order This field is ignored for PAYPAL transactions
account (if present).

Page 44 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

Basket Contents

The shopping basket contents can be passed in a single, colon-delimited field, in the following format:

Number of lines of detail in the basket field:

Item 1 Description:
Quantity of item 1:
Unit cost item 1 without tax:
Tax applied to item 1:
Cost of Item 1 including tax:
Total cost of item 1 (Quantity x cost including tax):
Item 2 Description:
Quantity of item 2:
....
Cost of Item n including tax:
Total cost of item n

IMPORTANT NOTES:

o The line breaks above are included for readability only. No line breaks are needed; the only separators should be the colons.

o The first value “The number of lines of detail in the basket” is NOT the total number of items ordered, but the total number of
rows of basket information. In the example below there are 6 items ordered, (1 DVD player and 5 DVDs) but the number of
lines of detail is 4 (the DVD player, two lines of DVDs and one line for delivery).

Page 45 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

So, for example, the following shopping cart...

Items Quantity Item value Item Tax Item Total Line Total

Pioneer NSDV99 DVD-Surround Sound System 1 424.68 74.32 499.00 499.00

Donnie Darko Director’s Cut 3 11.91 2.08 13.99 41.97

Finding Nemo 2 11.05 1.94 12.99 25.98

Delivery --- --- --- --- 4.99

Would be represented thus:

4:Pioneer NSDV99 DVD-Surround Sound System:1:424.68:74.32:499.00: 499.00:Donnie Darko Director’s

Cut:3:11.91:2.08:13.99:41.97: Finding Nemo:2:11.05:1.94:12.99:25.98: Delivery:---:---:---:
---:4.99

If you wish to leave a field empty, you must still include the colon. e.g.

DVD Player:1:199.99:::199.99

Page 46 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

A2: Server Response to the Transaction Registration POST

This is the plain text response part of the POST originated by your servers in A1. Encoding will be as Name=Value pairs separated by carriage
return and linefeeds (CRLF).

Response format:
Name Format Values Comments
VPSProtocol Alphanumeric. Version number of the protocol of the system. This This will match the protocol version supplied in A1.
Fixed 4 characters. release will return 2.23
Status Alphanumeric OK – Process executed without error If the VendorTxCode passed in A1 has been used before, but that
Max 15 characters. transaction is still active, then details of that transaction are passed
MALFORMED – Input message was missing fields or back in this POST and the suffix REPEATED is appended to the Status.
badly formatted – normally will only occur during Your system must be able to handle repeated messages from Sage Pay.
development.
If the status is not OK, the StatusDetail field will give more information
INVALID – Transaction was not registered because about the problem.
although the POST format was valid, some information
supplied was invalid. E.g. incorrect vendor name or Please notify Sage Pay if a Status report of ERROR is seen, together
currency. with your VendorTxCode and the StatusDetail text.

ERROR – A problem occurred at Sage Pay which

prevented transaction registration.

StatusDetail Alphanumeric Human-readable text providing extra detail for the Always check StatusDetail if the Status is not OK
Max 255 characters Status message.
VPSTxId Alphanumeric Sage Pay’s ID to uniquely identify the Transaction on Only present if Status is OK or OK REPEATED.
38 characters our system.
SecurityKey Alphanumeric A Security key which SAGE PAY uses to generate a This value is used to allow detection of tampering with notifications from
10 characters MD5 Hash for to sign the Notification message (A3 SAGE PAY Server. It must be kept secret from the Customer and held in
below). The signature is called VPSSignature. your database.
Only present if Status is OK.
NextURL Alphanumeric URL to which the Vendor must redirect the Customer Only present if Status is OK.
Full Qualified URL to continue the Transaction Note that the full URL must be used for the redirect, including any
Max 255 characters appended parameters.

Page 47 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

A3: Notification of Results for Transactions

The Sage Pay Server will send notification in the request part of a POST to the Notification URL provided in A1. The request will be URL encoded,
with Name=Value fields separated by ‘&’ characters.

Request format (continued overleaf)

Name Format Values Comments
VPSProtocol Alphanumeric 2.23 in this release Protocol version used by the system.
4 characters Same as sent in Step A1
TxType Alphanumeric PAYMENT, DEFERRED or As supplied by your site in A1.
Max 20 characters AUTHENTICATE
VendorTxCode Alphanumeric Your unique Vendor Transaction Code Same as sent by your servers in Step A1.
Max 40 characters
VPSTxId Alphanumeric Sage Pay’s ID to uniquely identify the Transaction on our Same value as returned in the response in A2.
38 characters system.
Status Alphabetic OK – Transaction completed successfully with authorisation. In the case of NOTAUTHED, the Transaction has completed
Max 20 characters through the SAGE PAY System, but it has not been authorised
NOTAUTHED – The Sage Pay system could not authorise the by the bank.
transaction because the details provided by the Customer were
incorrect, or not authenticated by the acquiring bank. A status of REJECTED means the bank may have authorised
the transaction but your own rule bases for AVS/CV2 or 3D-
ABORT – The Transaction could not be completed because the Secure caused the transaction to be rejected.
user clicked the CANCEL button on the payment pages, or went
inactive for 15 minutes or longer. In the cases of ABORT and ERROR (see below) the
Transaction has not completed through the Server and can be
REJECTED – The Sage Pay System rejected the transaction retried.
because of the rules you have set on your account.
Please notify Sage Pay if a Status report of ERROR is seen,
AUTHENTICATED – The 3D-Secure checks were performed together with your VendorTxCode and the StatusDetail text.
successfully and the card details secured at Sage Pay.
AUTHENTICATED and REGISTERED statuses are only
REGISTERED – 3D-Secure checks failed or were not returned if the TxType is AUTHENTICATE.
performed, but the card details are still secured at Sage Pay.

ERROR – An error occurred at Sage Pay which meant the

transaction could not be completed successfully.
StatusDetail Alphanumeric Human-readable text providing extra detail for the Status You should always check this value if the Status is not OK.
Max 255 characters message
TxAuthNo Long Integer Sage Pay unique Authorisation Code for a successfully Only present if the transaction was successfully authorised
authorised transaction aka VPSAuthCode. (Status OK).

Page 48 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

Request format (continued…)

AVSCV2 Alphabetic Response from AVS and CV2 checks. Will be one of the Provided for Vendor info and backward compatibility with the
Max 50 characters following: ALL MATCH, SECURITY CODE MATCH ONLY, banks. Rules set up at the Sage Pay server will accept or reject
ADDRESS MATCH ONLY, NO DATA MATCHES or DATA the transaction based on these values.
NOT CHECKED. More detailed results are split out in the next three fields. Not
present if the Status is AUTHENTICATED or REGISTERED.
AddressResult Alphabetic NOTPROVIDED, NOTCHECKED, MATCHED, The specific result of the checks on the cardholder’s address
Max 20 characters NOTMATCHED numeric from the AVS/CV2 checks. Not present if the Status is
AUTHENTICATED or REGISTERED
PostCodeResult Alphabetic NOTPROVIDED, NOTCHECKED, MATCHED, The specific result of the checks on the cardholder’s Post Code
Max 20 characters NOTMATCHED from the AVS/CV2 checks. Not present if the Status is
AUTHENTICATED or REGISTERED
CV2Result Alphabetic NOTPROVIDED, NOTCHECKED, MATCHED, The specific result of the checks on the cardholder’s CV2 code
Max 20 characters NOTMATCHED from the AVS/CV2 checks. Not present if the Status is
AUTHENTICATED or REGISTERED
GiftAid Flag 0 = The Gift Aid box was not checked for this transaction. This field is always present even if GiftAid is not active on your
1 = The user checked the Gift Aid box on the payment page account.
3DSecureStatus Alphabetic OK - 3D Secure checks carried out and user authenticated This field details the results of the 3D-Secure checks (where
Max 50 characters correctly. appropriate)

NOTCHECKED – 3D-Secure checks were not performed. NOTCHECKED indicates that 3D-Secure was either switched
off at an account level, or disabled at transaction registration
NOTAVAILABLE – The card used was either not part of the with a setting like Apply3DSecure=2
3D Secure Scheme, or the authorisation was not possible.

NOTAUTHED – 3D-Secure authentication checked, but the

user failed the authentication.

INCOMPLETE – 3D-Secure authentication was unable to

complete. No authentication occurred.

ERROR - Authentication could not be attempted due to data

errors or service unavailability in one of the parties involved
in the check.

CAVV Alphanumeric The encoded result code from the 3D-Secure checks (CAVV Only present if the 3DSecureStatus field is OK
Max 32 characters or UCAF).

Page 49 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

Request format (continued…)

AddressStatus Alphabetic Either NONE, CONFIRMED or UNCONFIRMED PayPal Transactions Only. If AddressStatus is confirmed and
Max 20 characters PayerStatus is verified, the transaction may be eligible for
PayerStatus Alphabetic Either VERIFIED or UNVERIFIED PayPal Seller Protection. To learn more about PayPal Seller
Max 20 characters Protection, please contact PayPal directly or visit:
https://www.paypal.com/uk/cgi-
bin/webscr?cmd=p/gen/ua/policy_spp-outside#spp-policy for
further information.
CardType Alphabetic VISA, MC, DELTA, SOLO, MAESTRO, UKE, AMEX, DC, MC is MasterCard, UKE is Visa Electron. MAESTRO should be
Max 15 characters JCB, LASER, PAYPAL used for both UK and International Maestro. AMEX and DC
(DINERS) can only be accepted if you have additional merchant
accounts with those acquirers.
Last4Digits Numeric The last 4 digits of the card number used in this transaction. This field is supplied to allow merchants using wallet systems to
Max 4 characters PayPal transactions have 0000 identify the card to their customers
VPSSignature Alphanumeric MD5 signature of the concatenation of the values of: To detect any possible tampering with messages, your site
Max 100 characters VPSTxId + VendorTxCode + Status + TxAuthNo + should compute the same MD5 signature (which incorporates
VendorName+ AVSCV2 + SecurityKey + AddressResult the Security key provided at Transaction registration) and
+ PostCodeResult + CV2Result + GiftAid + check it against VPSSignature.
3DSecureStatus + CAVV + AddressStatus +
PayerStatus + CardType + Last4Digits. You can then decide what to do with transactions that appear to
have been tampered with.
NOTE: MD5 value is returned in UPPER CASE

Page 50 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

A4: You acknowledge receipt of the Notification POST

This is the plain text response part of the POST originated by the Server in the step above. Encoding must be as Name=Value fields
separated by carriage-return-linefeeds (CRLF).

Response format:
Name Format Values Comments
Status Alphabetic OK – Send this if you successfully received the notification OK statuses will allow the transaction to settle and money to
Max 20 characters Post in A3. Send this unless an error occurs during move into the Vendor account.
notification.
INVALID or ERROR responses will prevent the transaction
INVALID – send INVALID if the details you received in the from settling, so the customer will not be charged.
A3 post were consistent with expectations for this
Transaction. The RedirectURL must still be provided, and You should send OK in all circumstances where no errors occur
Sage Pay will still redirect the Customer back to your site, but in validating the Notification POST, so even if Sage Pay send
the transaction will NOT be settled with the bank. Only send you a status of ABORT or NOTAUTHED in A3 above, you should
this result if you want to cancel the transaction. reply with an OK and a RedirectURL that points to a page
informing the customer that the transaction did not complete.
ERROR – An error has occurred during your Notification
processing. The Sage Pay system will check for a
RedirectURL, and if one is provided the Customer will be
redirected to your site, but the transaction will NOT be
settled with the bank. Only send this result if you want to
cancel the transaction and report an ERROR to Sage Pay.

RedirectURL Alphanumeric Full qualified URL (including http:// or https:// header) to If you wish to pass parameters back to your own site (such as
Max 255 characters which you’d like the customer redirected on completion of the the session id or transaction code), these should be included in
transaction RedirectURL.

StatusDetail Alphanumeric Human-readable text providing extra detail for the Status If Status is not OK, state what is wrong with the Transaction
Max 255 characters message and why you are rejecting it.

IMPORTANT NOTE: Before writing the three fields above to the Response object of the POST, please ensure you clear your response
buffer to remove any header code, comments or HTML. The Sage Pay Server is expecting “Status=” to be the first characters in the
response. If it does not see these, it treats the response as though it is an error and fails the transaction! Sage Pay Simulator will warn
you about this when you are testing.

Page 51 of 52
Version Date: Monday, 26 October 2009 Version: 2.23
 Server Protocol and Integration Guideline

A5: Server Integration Full URL Summary

The table below shows the complete web addresses to which you send the messages detailed above.

Transaction Registration (PAYMENT, DEFERRED, AUTHENTICATE)

Simulator: https://test.sagepay.com/Simulator/VSPServerGateway.asp?Service=VendorRegisterTx
TEST System: https://test.sagepay.com/gateway/service/vspserver-register.vsp
Live System: https://live.sagepay.com/gateway/service/vspserver-register.vsp

Please ensure that your firewalls allow outbound Port 443 (HTTPS only!) and inbound ports 443 (and optionally 80 HTTP) access in order
to communicate with our servers (on Simulator/Test/Live).

Page 52 of 52
Version Date: Monday, 26 October 2009 Version: 2.23