Technical Guide Update Sage Pay Form Protocols Migrating from v2.23 to v3.00

Transcription

1 Technical Guide Update Sage Pay Form Protocols Migrating from v2.23 to v3.00

2 Table of Contents 1.0 Summary Introduction Audience Migrating from v2.23 to v Migration Summary Mandatory Field Changes Optional Field Changes Optional PayPal Field Changes Transaction Registration Field Changes Say Pay Response Field Changes Crypt Field Changes 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 11 Version March 2014 Page 2 of 11

3 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.23 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.23 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. Version March 2014 Page 3 of 11

4 2.0 Migrating from v2.23 to v Migration Summary When upgrading from Sage Pay Form v2.23 to Sage Pay Form v3.00 there is 1 required change to the transaction registration value (which could increase to 8 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 may 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. Transaction Registration: VPSProtocol Sage Pay Response: BankAuthCode DeclineCode ExpiryDate * Mandatory changes are highlighted in red in the table below 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: BasketXML CustomerXML SurchargeXML VendorData ReferrerID Language Website Sage Pay Response: FraudResponse Surcharge Version March 2014 Page 4 of 11

5 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 Version March 2014 Page 5 of 11

6 2.5 Transaction Registration Field Changes Name Mandatory Format Max Length Allowed Values Description VPSProtocol Yes 4 Chars Must be 3.00 This field already exists and is the version of the protocol you are integrating with. It must be set to BasketXML No 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 SurchargeXML No 800 Chars See Form Protocol and Integration Guideline: A1.2 This can be used to supply information on the customer for purposes such as fraud screening. Located within the Crypt field. 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 Use this to pass data you wish to be displayed against the transaction in MySagePay. ReferrerID No 40 Chars This can be used to send the unique reference for the Partner that referred the Vendor to Sage Pay. Language No ISO639 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 Website 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. BillingAgreement Yes (PayPal Only) 1 Char 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. Version March 2014 Page 6 of 11

7 2.6 Say Pay Response Field Changes Name 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 T 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 Numeric Decimal Amount Returns the surcharge amount charged and is only present if a surcharge was applied to the transaction. AddressStatus Yes (PayPal Only) NONE CONFIRMED UNCONFIRMED 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: for furtherinformation. PayerStatus Yes VERIFIED (PayPal Only) UNVERIFIED Version March 2014 Page 7 of 11

8 3.0 Crypt Field Changes Changes may need to be made to the Crypt field in order to migrate to v3.00 of the Sage Pay Form protocol. This is because v2.23 is backwards compatible, and the Crypt field changes might have already taken place previously. In order to determine if you need to make any changes to the way your system processes the Crypt field, you can look for character or %40 at the beginning of your current Crypt field. If there is either of these symbols, you are already using AES. If not, you will have to upgrade your encryption scheme to AES. 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. 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 - How secure is AES against brute force attacks? - Advanced Encryption Standard - Announcing the Advanced Encryption Standard (AES) - Version March 2014 Page 8 of 11

9 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 v Mandatory Transaction Registration Field Changes The VPSProtocol field in red represents the mandatory change that is 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=tonestest &Amount=31.35&Currency=GBP&Description=The best DVDs from tonestest&successurl= 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&Customer =customer@example.com&Send =1& Message=Thanks for your order&billingaddress2=billaddress Line 2&BillingPhone=44 (0) &DeliveryAddress2=BillAddress Line 2&DeliveryPhone=44 (0) &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 &VPSTxId={9CA3B265-9FDF-E E44A7B8}&Status=OK&StatusDetail=0000 : The Authorisation was Successful.&TxAuthNo= &AVSCV2=SECURITY CODE MATCH ONLY&AddressResult=NOTMATCHED&PostCodeResult=NOTMATCHED&CV2Result=MATCHED&GiftAid =0&3DSecureStatus=OK&CAVV= &CardType=VISA&Last4Dig its=0000&amount=33.85&declinecode=00&bankauthcode=999777&expirydate=1215 Version March 2014 Page 9 of 11

10 4.3 Optional Transaction Registration Fields The VPSProtocol field in red represents the mandatory change that is necessary to be compatible with 3.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=tonestest &Amount=31.35&Currency=GBP&Description=The best DVDs from tonestest&successurl= 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 for your order&billingaddress2=billaddress Line 2&BillingPhone=44 (0) &DeliveryAddress2=BillAddress Line 2&DeliveryPhone=44 (0) &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> </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 &VPSTxId={9CA3B265-9FDF-E E44A7B8}&Status=OK&StatusDetail=0000 : The Authorisation was Successful.&TxAuthNo= &AVSCV2=SECURITY CODE MATCH ONLY&AddressResult=NOTMATCHED&PostCodeResult=NOTMATCHED&CV2Result=MATCHED&GiftAid =0&3DSecureStatus=OK&CAVV= &CardType=VISA&Last4Dig its=0000&amount=33.85&fraudresponse=challenge& Surcharge=2.50&DeclineCode=00&BankAuthCode=999777&ExpiryDate=1215 Version March 2014 Page 10 of 11

11 4.5 Optional PayPal Transaction Registration The VPSProtocol, and BillingAgreement fields in red represents the mandatory change that is 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=tonestest &Amount=21.40&Currency=EUR&Description=The best DVDs from tonestest&successurl= 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 for your order&billingaddress2=billaddress Line 2&BillingPhone=44 (0) &DeliveryAddress2=BillAddress Line 2&DeliveryPhone=44 (0) &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 &VPSTxId={ A5- FAF6-A61C-1BE6E78523D3}&TxAuthNo= &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 Version March 2014 Page 11 of 11