Technical Guide Update Sage

Pay Form Protocols

Migrating from v2.22 to v3.00

Table of Contents

1.0
1.1
1.2

Summary
Introduction
Audience

2.0
2.1
2.2
2.3
2.4
2.5
2.6

Migrating from v2.22 to v3.00

Migration Summary
Mandatory Field Changes
Optional Field Changes
Optional PayPal Field Changes
Transaction Registration Field Changes
Say Pay Response Field Changes

4
4
4
5
6
7
10

3.0

Crypt Field Changes

11

4.0
4.1

Appendix: XML Examples

Mandatory Transaction Registration Field
Changes
Mandatory Sage Pay Response Field Changes
Optional Transaction Registration Fields
Optional Sage Pay Response Fields
Optional PayPal Transaction Registration
Optional PayPal Response Fields

12

4.2
4.3
4.4
4.5
4.6

Technical Guide Migrating from v2.22 to v3.00

Version 1.00 26 March 2014

3
3
3

12
12
13
13
14
14

Page 2 of 14

1.0 Summary

1.1

Introduction

The Sage Pay Form protocol is one of our most common methods of integration for
payment processing. This flexible integration method can be implemented with a variety of
programming languages and server technologies. As changes to the Sage Pay Form
protocol have been made in order to add additional features and flexibility, this document
serves as a brief technical guide that details the requirements necessary to upgrade from
v2.22 to v3.00 of the Sage Pay Form protocol.
1.2

Audience

This document is intended for partners, developers, and merchants that currently use or
manage a Sage Pay Form protocol implementation and serves to summarise the specific
requirements and changes necessary to upgrade from v2.22 to v3.00.
As the protocol implementation is not reliant upon a specific technology, this guide is
relevant for all merchants and partners that intend to upgrade an existing implementation
to v3.00 of the protocol.
In addition to this guide, Sage Pay has developed integration kits for Java, PHP, and .NET
that can be found on our Form Integration section of the Sage Pay website. These kits
provide example implementations for v3.00 of the Sage Pay Form protocol. Along with the
integration kits, the detailed Form Integration Protocol and Guidelines provides very
specific details for new merchants integrating to Sage Pay Form v3.00 and will
encompass the information found within this technical guide.

Technical Guide Migrating from v2.22 to v3.00

Version 1.00 26 March 2014

Page 3 of 14

2.0 Migrating from v2.22 to v3.00

2.1

Migration Summary

When upgrading from Sage Pay Form v2.22 to Sage Pay Form v3.00 there are 13 required
changes to the transaction registration value (which could increase to 24 with the introduction
of new features and optional fields), and 3 required changes to the Sage Pay Response
(which could increase to 5 due to the introduction of two new features and optional fields).
Changes will need to be made to the Crypt field depending on the current implementation,
and additional details can be found within the Crypt Field Changes section of this
document.

2.2

Mandatory Field Changes

The following fields are required to be updated as part of the mandatory field changes to
integrate with v3.00 of the Sage Pay Form protocol. The VPSProtocol field is the only field
that is not part of the Crypt field.
Transaction Registration:

VPSProtocol

BillingSurname

BillingFirstnames

BillingAddress1

BillingCity

BillingPostCode*

BillingCountry

DeliverySurname

DeliveryFirstnames

DeliveryAddress1

DeliveryCity

DeliveryPostCode*

DeliveryCountry

Sage Pay Response:

BankAuthCode

DeclineCode

ExpiryDate

* Mandatory changes are highlighted in red in the table below

* The postcode can be blank for countries that do not have postcodes ( e.g. Ireland) but is required in all countries that do
have them. Providing a blank field when information is required will cause an error.

Technical Guide Migrating from v2.22 to v3.00

Version 1.00 26 March 2014

Page 4 of 14

2.3

Optional Field Changes

Along with the mandatory field changes, there are many optional fields that can be
implemented in order to gain additional functionality and features from upgrading to the Sage
Pay Form v3.00 protocol. All of these optional transaction registration fields are part of the
Crypt field.
Transaction Registration:

BillingAddress2*

BillingState*

BillingPhone*

DeliveryAddress2*

BasketXML

CustomerXML

SurchargeXML

VendorData

ReferrerID

Language

Website

Sage Pay Response:

FraudResponse

Surcharge

* Non-optional fields must contain a value, even if that value is blank.

Technical Guide Migrating from v2.22 to v3.00

Version 1.00 26 March 2014

Page 5 of 14

2.4

Optional PayPal Field Changes

In addition to the mandatory and optional field changes, there is 1 transaction registration field,
and 2 Sage Pay response fields that are required in order to process PayPal transactions.
These changes are mandatory for PayPal transactions. These fields may already be present
within your implementation as part of the older protocol implementations. There are also 3
fields are typically mandatory of a transaction but will not be returned as part of a PayPal
transaction. All of these PayPal fields are part of the Crypt field.
Transaction Registration:

BillingAgreement

Sage Pay Response:

BankAuthCode (Not Returned for PayPal Transactions)

DeclineCode (Not Returned for PayPal Transactions)

ExpiryDate (Not Returned for PayPal Transactions)

AddressStatus

PayerStatus

Technical Guide Migrating from v2.22 to v3.00

Version 1.00 26 March 2014

Page 6 of 14

2.5

Transaction Registration Field Changes

Name

Mandatory

Format

Max
Length

Allowed
Values

Description

Must be 3.00

This field already exists and is the version of the protocol you are integrating with. It must be set to
3.00.

VPSProtocol

Yes

4 Chars

BillingSurname

Yes

20 chars

BillingFirstnames

Yes

20 chars

BillingAddress1

Yes

100 Chars

BillingAddress2

No*

100 Chars

BillingCity

Yes

40 Chars

BillingPostCode

Yes

10 Chars

BillingCountry

Yes

2 Chars

ISO 3166-1 country code

BillingState

No*

2 Chars

State code for US customers only

BillingPhone

No*

20 Chars

DeliverySurname

Yes

20 Chars

Technical Guide Migrating from v2.22 to v3.00

Version 1.00 26 March 2014

Page 7 of 14

DeliveryFirstnames

Yes

20 Chars

DeliveryAddress1

Yes

100 Chars

DeliveryAddress2

No*

100 Chars

DeliveryCity

Yes

40 Chars

DeliveryPostCode

Yes

10 Chars

DeliveryCountry

Yes

2 Chars

BasketXML

No

20000
Chars

See Form Protocol

and Integration
Guideline: A1.4

A more flexible version of the current basket field which can be used instead of. If this field is supplied
then the Basket field should not be supplied. Located within the Crypt field.

CustomerXML

No

2000 Chars

See Form Protocol

and Integration
Guideline: A1.5

This can be used to supply information on the customer for purposes such as fraud screening.
Located within the Crypt field.

SurchargeXML

No

800 Chars

See Form Protocol

and Integration
Guideline: A1.2

Use this field to override default surcharge settings in MySagePay for the current transaction.
Percentage and fixed amount surcharges can be set for different payment types. Located within the
Crypt field.

VendorData

No

200 Chars

Technical Guide Migrating from v2.22 to v3.00

Version 1.00 26 March 2014

ISO 3166-1 country code of the cardholders delivery address

Use this to pass data you wish to be displayed against the transaction in MySagePay.

Page 8 of 14

ReferrerID

No

Language

No

Website

BillingAgreement

40 Chars

This can be used to send the unique reference for the Partner that referred the Vendor to Sage Pay.

2 Chars

The language the customer sees the payment pages in is determined by the code sent here. If this is
NULL then the language default of the shoppers browser will be used. If the language is not
supported then the language supported in the templates will be used Currently supported languages
in the Default templates are : French, German, Spanish, Portuguese, Dutch and English

No

100 Chars

Reference to the website this transaction came from. This field is useful if transactions can originate
from more than one website. Supplying this information will enable reporting to be performed by
website.

Yes

1 Char

ISO639

(PayPal Only)

0
1

This field must be set for PAYPAL REFERENCE transactions. You will need to contact PayPal
directly in order to apply for Reference transactions and have the service confirmed before attempting
to pass the Billing Agreement field and a value of 1 for successful repeat payments.
All non-PayPal transactions can be repeated without this flag.

* Non-optional fields must contain a value, apart from the postcode. The postcode can be blank for countries that do not have postcodes ( e.g. Ireland) but is required in all countries that do have them.
Providing a blank field when information is required will cause an error.

Technical Guide Migrating from v2.22 to v3.00

Version 1.00 26 March 2014

Page 9 of 14

2.6
Name

Say Pay Response Field Changes

Mandatory Format

Max
Length

Allowed Values

Description

ExpiryDate

Yes

4 chars

Expiry date of credit card used, in the format MMYY. Not returned for PayPal transactions.

BankAuthCode

Yes

6 Chars

The authorisation code returned from the bank. e.g T999777. Not returned for PayPal transactions.

DeclineCode

Yes

2 Chars

The decline code from the bank. These codes are specific to the bank. Please contact them for a description of
each code. e.g. 00. Not returned for PayPal transactions.

FraudResponse

No

Alphanumeric

10
Characters

ACCEPT, CHALLENGE
or DENY.
NOTCHECKED will be
returned if there is no
response from ReD.

ACCEPT means ReD recommends that the transaction is accepted

DENY means ReD recommends that the transaction is rejected
CHALLENGE means ReD recommends that the transaction is reviewed. You have elected to have these
transactions either automatically accepted or automatically denied at a vendor level. Please contact Sage Pay if
you wish to change the behaviour you require for these transactions
NOTCHECKED means ReD did not perform any fraud checking for this particular transaction

Surcharge

No

AddressStatus

Yes

Numeric

(PayPal Only)

Decimal
Amount

Returns the surcharge amount charged and is only present if a surcharge was applied to the transaction.

NONE
CONFIRMED

If AddressStatus is confirmed and PayerStatus is verified, the transaction may be eligible for PayPal Seller
Protection. To learn more about PayPal Seller Protection, please contact PayPal directly or visit:
https://www.paypal.com/uk/cgibin/webscr?cmd=p/gen/ua/policy_spp-outside#spp-policy for furtherinformation.

UNCONFIRMED

PayerStatus

Yes
(PayPal Only)

Technical Guide Migrating from v2.22 to v3.00

Version 1.00 26 March 2014

VERIFIED
UNVERIFIED

Page 10 of 14

3.0 Crypt Field Changes

Changes will need to be made to the Crypt field in order to migrate to v3.00 of the Sage Pay
Form protocol.
The XML contents need to be encrypted using AES-128 encryption with 128-bit block size in
CBC mode with PCKS#5 (AES-128-CBC-PKCS#5). This encryption scheme is very popular
within the industry and can be implemented for all major programming languages.
Additional information, with an example walkthrough of the Crypt field generation can be
found within the Form Protocol and Integration Guideline: A1.1 The Crypt Field. For each of
the integration kits, there is also example source code that implements AES encryption.

http://www.sagepay.co.uk/support/find-an-integration-document/form-integration

Information on the AES algorithm can be found below, and although not necessary to read,
can provide valuable insight as to the strengths and implementations of this encryption
scheme.

Keep Your Data Secure with the New Advanced Encryption Standard http://msdn.microsoft.com/en-us/magazine/cc164055.aspx

How secure is AES against brute force attacks? http://www.eetimes.com/document.asp?doc_id=1279619

Advanced Encryption Standard https://en.wikipedia.org/wiki/Advanced_Encryption_Standard

Announcing the Advanced Encryption Standard (AES) http://csrc.nist.gov/publications/fips/fips197/fips-197.pd

Technical Guide Migrating from v2.22 to v3.00

Version 1.00 26 March 2014

Page 11 of 14

4.0 Appendix: XML Examples

The following section demonstrates the example XML data that represents the transaction
registration and Sage Pay response values as part of the Form protocol. The following
examples cover the mandatory changes required, as well as other optional scenarios in order
to give a working example of the features of v3.00.

4.1

Mandatory Transaction Registration Field Changes

The VPSProtocol, BillingSurname, BillingFirstname, BillingAddress1, BillingCity,

BillingPostCode, BillingCountry, DeliverySurname, DeliveryFirstnames,
DeliveryAddress1, DeliveryCity, DeliveryPostCode, and DeliveryCountry fields in red
represents the mandatory changes that are necessary to be compatible with v3.00 of the Sage
Pay Form protocol. The VPSProtocol, TxType, and Vendor fields are the only fields not part
of the Crypt field, indicated by the grey background colour, while the remainder of the XML
will be sent encrypted.
VPSProtocol=3.00&TxType=PAYMENT&Vendor=tonestest&VendorTxCode=tonestest1394184637894-393502&Amount=31.35&Currency=GBP&Description=The best DVDs from
tonestest&SuccessURL=http://integrationkits.cloudapp.net/javakit/form/success/&FailureURL=http://integrationkits.cloudapp.net/javakit/form/failure/&BillingSurname=Surname&BillingFirstnames=Fname
Mname&BillingAddress1=BillAddress Line 1&BillingCity=BillCity&BillingPostCode=W1A
1BL&BillingCountry=GB&DeliverySurname=Surname&DeliveryFirstnames=Fname
Mname&DeliveryAddress1=BillAddress Line
1&DeliveryCity=BillCity&DeliveryPostCode=W1A
1BL&DeliveryCountry=GB&CustomerName=Fname Mname
Surname&CustomerEMail=customer@example.com&SendEMail=1&eMailMessage=Thanks for
your order&BillingAddress2=BillAddress Line 2&BillingPhone=44 (0)7933 000
000&DeliveryAddress2=BillAddress Line 2&DeliveryPhone=44 (0)7933 000
000&Basket=2:Shaolin
Soccer:3:8.29:1.66:9.95:29.85:Delivery:1:1.50:0:1.50:1.50&AllowGiftAid=0&ApplyAVS
CV2=0&Apply3DSecure=0

4.2

Mandatory Sage Pay Response Field Changes

The BankAuthCode, DeclineCode, and ExpiryDate fields in red represent the mandatory
changes that are necessary to be compatible with v3.00 of the Sage Pay Form protocol. All of
the example fields will be returned as part of the Crypt field.
VendorTxCode=tonestest-1394184637894-393502&VPSTxId={9CA3B265-9FDF-E550-756562678E44A7B8}&Status=OK&StatusDetail=0000 : The Authorisation was
Successful.&TxAuthNo=6529795&AVSCV2=SECURITY CODE MATCH
ONLY&AddressResult=NOTMATCHED&PostCodeResult=NOTMATCHED&CV2Result=MATCHED&GiftAid
=0&3DSecureStatus=OK&CAVV=00000101147993000000000000000000&CardType=VISA&Last4Dig
its=0000&Amount=33.85&DeclineCode=00&BankAuthCode=999777&ExpiryDate=1215

Technical Guide Migrating from v2.22 to v3.00

Version 1.00 26 March 2014

Page 12 of 14

4.3

Optional Transaction Registration Fields

The VPSProtocol, BillingSurname, BillingFirstname, BillingAddress1, BillingCity,

BillingPostCode, BillingCountry, DeliverySurname, DeliveryFirstnames,
DeliveryAddress1, DeliveryCity, DeliveryPostCode, and DeliveryCountry fields in red
represents the mandatory changes that are necessary to be compatible with v3.00 of the Sage
Pay Form protocol. The SurchargeXML field is optional and is represented in green. The
CustomerXML field is optional and is represented in orange.
As part of the v3.00 protocol, there can only one of the two basket fields: the older Basket
field, or the newer BasketXML field. The BasketXML field is optional and is represented in
blue.
The VPSProtocol, TxType, and Vendor fields are the only fields not part of the Crypt field,
indicated by the grey background colour, while the remainder of the XML will be sent
encrypted.
VPSProtocol=3.00&TxType=PAYMENT&Vendor=tonestest&VendorTxCode=tonestest1394184637894-393502&Amount=31.35&Currency=GBP&Description=The best DVDs from
tonestest&SuccessURL=http://integrationkits.cloudapp.net/javakit/form/success/&FailureURL=http://integrationkits.cloudapp.net/javakit/form/failure/&BillingSurname=Surname&BillingFirstnames=Fname
Mname&BillingAddress1=BillAddress Line 1&BillingCity=BillCity&BillingPostCode=W1A
1BL&BillingCountry=GB&DeliverySurname=Surname&DeliveryFirstnames=Fname
Mname&DeliveryAddress1=BillAddress Line
1&DeliveryCity=BillCity&DeliveryPostCode=W1A
1BL&DeliveryCountry=GB&CustomerName=Fname Mname
Surname&CustomerEMail=customer@example.com&SendEMail=1&eMailMessage=Thanks for
your order&BillingAddress2=BillAddress Line 2&BillingPhone=44 (0)7933 000
000&DeliveryAddress2=BillAddress Line 2&DeliveryPhone=44 (0)7933 000
000&BasketXML=<basket><item><description>Shaolin
Soccer</description><quantity>5</quantity><unitNetAmount>8.29</unitNetAmount><uni
tTaxAmount>1.66</unitTaxAmount><unitGrossAmount>9.95</unitGrossAmount><totalGross
Amount>49.75</totalGrossAmount></item><deliveryGrossAmount>1.50</deliveryGrossAmo
unt>&SurchargeXML=<surcharges><surcharge><paymentType>SOFORT</paymentType><fixed>
2.50</fixed></surcharge><surcharge><paymentType>VISA</paymentType><fixed>2.50</fi
xed></surcharge><surcharge><paymentType>GIROPAY</paymentType><fixed>1.50</fixed><
/surcharge></surcharges>&
CustomerXML=<customer><customerMobilePhone>07843106217</customerMobilePhone><prev
iousCust>0</previousCust></customer>

4.4

Optional Sage Pay Response Fields

The BankAuthCode, DeclineCode, and ExpiryDate fields in red represent the mandatory
changes that are necessary to be compatible with v3.00 of the Sage Pay Form protocol. The
Surcharge field is optional and is represented in green, and requires the SurchargeXML to
be submitted as part of the transaction registration.
If ReD Fraud Screening is enabled, the only change is the inclusion of the optional
FraudResponse field which is represented in purple.
All of the example fields will be returned as part of the Crypt field.
VendorTxCode=tonestest-1394184637894-393502&VPSTxId={9CA3B265-9FDF-E550-756562678E44A7B8}&Status=OK&StatusDetail=0000 : The Authorisation was
Successful.&TxAuthNo=6529795&AVSCV2=SECURITY CODE MATCH
ONLY&AddressResult=NOTMATCHED&PostCodeResult=NOTMATCHED&CV2Result=MATCHED&GiftAid
=0&3DSecureStatus=OK&CAVV=00000101147993000000000000000000&CardType=VISA&Last4Dig
its=0000&Amount=33.85&FraudResponse=CHALLENGE&
Surcharge=2.50&DeclineCode=00&BankAuthCode=999777&ExpiryDate=1215

Technical Guide Migrating from v2.22 to v3.00

Version 1.00 26 March 2014

Page 13 of 14

4.5

Optional PayPal Transaction Registration

The VPSProtocol, BillingSurname, BillingFirstname, BillingAddress1, BillingCity,

BillingPostCode, BillingCountry, DeliverySurname, DeliveryFirstnames,
DeliveryAddress1, DeliveryCity, DeliveryPostCode, DeliveryCountry, and
BillingAgreement fields in red represents the mandatory changes that are necessary to be
compatible with v3.00 of the Sage Pay Form protocol.
The VPSProtocol, TxType, and Vendor fields are the only fields not part of the Crypt field,
indicated by the grey background colour, while the remainder of the XML will be sent
encrypted.
VPSProtocol=3.00&TxType=PAYMENT&Vendor=tonestest&VendorTxCode=tonestest1394630132545-975554&Amount=21.40&Currency=EUR&Description=The best DVDs from
tonestest&SuccessURL=http://integrationkits.cloudapp.net/javakit/form/success/&FailureURL=http://integrationkits.cloudapp.net/javakit/form/failure/&BillingSurname=Surname&BillingFirstnames=Fname
Mname&BillingAddress1=BillAddress Line 1&BillingCity=BillCity&BillingPostCode=W1A
1BL&BillingCountry=GB&DeliverySurname=Surname&DeliveryFirstnames=Fname
Mname&DeliveryAddress1=BillAddress Line
1&DeliveryCity=BillCity&DeliveryPostCode=W1A
1BL&DeliveryCountry=GB&CustomerName=Fname Mname
Surname&CustomerEMail=customer@example.com&SendEMail=1&eMailMessage=Thanks for
your order&BillingAddress2=BillAddress Line 2&BillingPhone=44 (0)7933 000
000&DeliveryAddress2=BillAddress Line 2&DeliveryPhone=44 (0)7933 000
000&AllowGiftAid=0&ApplyAVSCV2=0&Apply3DSecure=0&BillingAgreement=1&BasketXML=<ba
sket><item><description>Shaolin
Soccer</description><quantity>2</quantity><unitNetAmount>8.29</unitNetAmount><uni
tTaxAmount>1.66</unitTaxAmount><unitGrossAmount>9.95</unitGrossAmount><totalGross
Amount>19.90</totalGrossAmount></item><deliveryGrossAmount>1.50</deliveryGrossAmo
unt></basket>

4.6

Optional PayPal Response Fields

The AddressStatus, and PayerStatus fields in red represent the mandatory changes that are
necessary to process PayPal transactions using v3.00 of the Sage Pay Form protocol. The
DeclineCode, and BankAuthCode, and ExpiryDate are no longer required and are indicated
here by a strikethrough.
All of the example fields will be returned as part of the Crypt field.
Status=OK&StatusDetail=0000 : The Authorisation was
Successful.&VendorTxCode=tonestest-1394630132545-975554&VPSTxId={18854041-39A5FAF6-A61C-1BE6E78523D3}&TxAuthNo=6556541&Amount=21.40& AVSCV2=DATA NOT
CHECKED&AddressResult=NOTPROVIDED&PostCodeResult=NOTPROVIDED&CV2Result=NOTPROVIDE
D&GiftAid=0&3DSecureStatus=NOTCHECKED&AddressStatus=CONFIRMED&PayerStatus=VERIFIE
D&CardType=PAYPAL&Last4Digits=0000&DeclineCode=00&BankAuthCode=999777&ExpiryDate=
1215

Technical Guide Migrating from v2.22 to v3.00

Version 1.00 26 March 2014

Page 14 of 14