Payment Response Guide. Version 4.3 September 2012 Business Gateway

Transcription

1 Version 4.3 September 2012 Business Gateway

2

3 Table of Contents About this Book... 2 Copyright... 2 Introduction... 3 What is Payment Response?... 3 The Payment Response Process... 4 Reference... 5 Setting Up... 5 Payment Message...6 Testing Shopper Response Dynamic Payment Response Recurring Payment Responses

4 About this Book This document describes how to set up and use the Payment Response feature. It is intended for all customers using the Hosted Payment Page service (HTML redirect). To get the most from this guide, you will need to know how to use an HTML or text editor. Version Change description Date Affected Pages 4.3 Fixed errors. Added information about American Express SafeKey. September 2012 All pages 4.2 Fixed errors. May 2012 All pages 4.1 Added information about the.net requestvalidationmode attribute. February 2012 Page Gateway and guide name added to navigation path. December 2011 All pages 3.1 Payment Page updates. October 2011 Pages WorldPay rebrand. July 2011 All pages Copyright WorldPay (UK) Limited While every effort has been made to ensure the accuracy of the information contained in this publication, the information is supplied without representation or warranty of any kind, is subject to change without notice and does not represent a commitment on the part of WorldPay (UK) Limited. WorldPay (UK) Limited, therefore, assumes no responsibility and shall have no liability, consequential or otherwise, of any kind arising from this material or any part thereof, or any supplementary materials subsequently issued by WorldPay (UK) Limited. WorldPay (UK) Limited has made every effort to ensure the accuracy of this material. 2

5 Introduction What is Payment Response? After a payment has been processed, either through to success or to cancellation, information about that payment is sent to you by using the Payment Response feature. The Payment Response feature posts the payment information from our server to a URL on your server via HTTP(s). This enables you to validate the information, update the order and if required display your own shopper result pages. Benefits The Payment Response enables you to: Get more information about the payment than you would receive in the merchant confirmation . Send the shopper additional information about their order in your own result pages or an order confirmation . Use the information received to trigger actions in your own order system. Pass your own order variables through our payment service and then back to your server. Check and validate all the payment data that WorldPay received and processed. Examine any available fraud check results, such as those arising from verification of Address, Security Code and Authentication information. Maintain any recurring payment agreements. 3

6 The Payment Response Process The following diagram explains the life cycle of a standard transaction and how the Payment Response feature is used within this process. Fig 1. Diagram showing the Payment Response Process 1. Order: The shopper places an online order with the merchant. 2. Purchase Token: The merchant produces a purchase token containing details about the order, which is then sent along with the shopper's browser to a payment page located on our payment service. The shopper then enters their card details into the payment page and we check these details with the card issuer. 3. Result Pages: If the card issuer authorises the transaction, or the shopper cancels the payment we will display a result page to the shopper. 4. Confirmation For successful transactions, we send an to the merchant and shopper, confirming the details of the transaction. 5. Payment message: By enabling Payment Response for your installation, we will also send you a payment message via HTTP(s) to your server. This message contains information about the transaction and can include your own variables. 6. Shopper response: Upon receiving the payment message you can use a script to send a response to the shopper's browser via WorldPay. If the shopper response fails to display your own result pages to the shopper's browser, then the default pages will be displayed. 4

7 Reference This section provides detailed information about the Payment Response feature for your reference. It includes detailed descriptions of: Setting Up Payment Message Testing Setting Up Shopper Response Dynamic Payment Response Recurring Payment Responses This section provides details on configuring your server to receive the Payment Message, creating a server-side script to examine the message and how to enable the payment response for an installation. Use Enabling Payment Response - change your installation to enable Payment Response. Configuring your server - configure your server to accept the Payment Message. Enabling Payment Response The payment response feature is set to OFF by default. To enable this feature: 1. Log in to the Merchant Interface. 2. Select Installations from the left hand navigation. 3. Choose an installation and select the Integration Setup button for either the TEST or PRODUCTION environment. 4. Check the Enable Payment Response checkbox. 5. Enter the Payment Response URL of the server-side script that is hosted on your web server. 6. Select the Save Changes button. If your Payment Response URL starts with you will need to make sure that your server supports either SSL 3.0 or TLS

8 Configuring your server to receive the Payment Message To use the payment response feature you must configure your web server to receive the Payment Message via the POST request method. Due to the number of different Web servers and possible versions available, we cannot provide you with detailed information about how to configure your server to use the POST request method. However, we recommend that you have the latest service packs installed and that your firewall has been enabled for us to connect to your server-side script. Creating a payment response server-side script You can create a payment response server-side script to examine the information provided in the Payment Message using any scripting language. If you are using Microsoft.NET 1.1 to create the payment response serverside script, you must disable the Request Validation feature. Refer to: for more information on how to disable this feature. The payment response server-side script can be used to trigger actions in your order system or shopping cart facility and can send a shopper response to the shopper's browser via WorldPay. If your system requires a full redirect to your own Webpage, you can include a META refresh (with a short delay) in the output of your payment response script (shopper response). Payment Message Purpose The Payment Message is a collection of parameters and related values detailing a shopper s authorised or cancelled transaction. The Payment Message is sent to a server-side script located on your server using the POST request method and via HTTP(s). Below is an example of what the body of Payment Message looks like for an authorised transaction: region=cambridgeshire&authamountstring=%26%23163%3b10.99&_sp.chare nc=utf- 8&desc=&tel= &address1=WorldPay+Ltd&countryMatch=S&car tid=test&address2= the+science+park&address3=milton+road&lang=en&callbackpw=your_ password&rawauthcode=a&transstatus=y&amountstring=%26%23163%3b10.9 9&authCost=10.99&currency=GBP&installation=211616&amount=10.99&cou ntrystring=united+kingdom&displayaddress=worldpay+ltd%0a the+science+park%0amilton+road%0acambridge%0acambridgeshire&tr anstime= &name=card+holder&testmode=100&routekey=visa- SSL&ipAddress= &fax=&rawAuthMessage=cardbe.msg.authori sed&instid=211616&avs=0001&compname=admin+- +Company+Name&authAmount=10.99&postcode=CB4+0WE&cardType=Visa&cost =10.99&authCurrency=GBP&country=GB&charenc=UTF- 6

9 8& =support%40worldpay.com&address=WorldPay+Ltd%0A The+Science+Park%0AMilton+Road%0ACambridge%0ACambridgeshire&tr ansid= &msgtype=authresult&town=cambridge&authmode=a This section provides details of what is included in the Payment Message and how you can add your own variables. Use Parameter descriptions - description of the parameters included in the Payment Message. Changing the Request Method - Use the GET Request Method to receive the Payment Message. Adding your own variables - pass your own variables from the purchase token back to you in the Payment Message. Payment Message Header - description of what is included in the Payment Message Header. Parameter descriptions for the HTTP(s) Payment Message The table below details all of the possible parameters that are posted to you in the body of the Payment Message: parameter name description Parameters generated by the Purchase Token instid The ID for the installation. cartid desc Your own reference number for the order. A textual description of the payment (up to 255 characters). Note: For recurring payment response the desc parameter will include the word FuturePay as well as the payment number and FuturePay Agreement ID. For examples that show how the desc parameter is formatted for a one-time payment and a payment made within a FuturePay agreement, see Callback Examples. cost A decimal number giving the cost of the purchase in terms of the major currency unit e.g would mean 12 pounds and 56 pence if the currency were GBP (Pounds Sterling). 7

10 Note: This is a legacy parameter. Do not use this parameter in server-side scripts. amount amountstring currency authmode testmode name address1 address2 address3 town A decimal number giving the cost of the purchase in terms of the major currency unit e.g would mean 12 pounds and 56 pence if the currency were GBP (Pounds Sterling). An HTML string produced from the amount and currency that were submitted to initiate the payment. 3 letter ISO code for the currency of this payment. Specifies the authorisation mode used. The values are "A" for a full auth, or "E" for a pre-auth. A value of 100 specifies a test payment and a value of 0 (zero) specifies a live payment. Specify the test result you want by entering REFUSED, AUTHORISED, ERROR or CAPTURED in the name parameter. The Shopper's full name, including any title, personal name and family name. Note: If your purchase token does not contain a name value, the name that the cardholder enters on the payment page will be returned to you. The first line of the shopper's address. Separators (including new line) used in this parameter are encoded as ASCII characters. The second line of the shopper's address. The third line of the shopper's address. Shopper s city or town. region Shopper s country/region/state or 8

11 area. postcode Shopper's postcode. country countrystring tel Shopper's country, as 2 character ISO code, uppercase. The full name of the country, derived from the country code submitted or supplied by the shopper in the language used by the shopper on the payment page. Shopper's telephone number. fax Shopper's fax number. Shopper's address. delvname delvaddress1 delvaddress2 delvaddress3 delvtown Shopper's delivery name. Note: The withdelivery parameter must be submitted in the purchase token for you to receive this parameter in the Payment Message. Shopper's delivery address1. Note: The withdelivery parameter must be submitted in the purchase token for you to receive this parameter in the Payment Message. Shopper's delivery address 2. Note: The withdelivery parameter must be submitted in the purchase token for you to receive this parameter in the Payment Message. Shopper's delivery address 3. Note: The withdelivery parameter must be submitted in the purchase token for you to receive this parameter in the Payment Message. Shopper's delivery town or city. Note: The withdelivery parameter must be submitted in the purchase token for you to receive this parameter in the Payment Message. 9

12 delvregion delvpostcode Shopper's delivery county/state/region. Note: The withdelivery parameter must be submitted in the purchase token for you to receive this parameter in the Payment Message. Shopper's delivery postcode. Note: The withdelivery parameter must be submitted in the purchase token for you to receive this parameter in the Payment Message. delvcountry Shopper's delivery country, as 2 character ISO code, uppercase. Note: The withdelivery parameter must be submitted in the purchase token for you to receive this parameter in the Payment Message. delvcountrystring The full name of the country, derived from the country code submitted or supplied by the shopper for the delivery address in the language used by the shopper on the payment page. Note: The withdelivery parameter must be submitted in the purchase token for you to receive this parameter in the Payment Message. compname Name of the company associated with this installation. Payment Response parameters transid The ID for the transaction. transstatus transtime authamount Result of the transaction - "Y" for a successful payment authorisation, "C" for a cancelled payment. Note: There is also a value "N", which indicates a declined recurring payment (FuturePay) transaction. Time of the transaction in milliseconds since the start of 1970 GMT. This is the standard system date in Java, and is also 1000x the standard C time_t time. Amount that the transaction was 10

13 authorised for, in the currency given as authcurrency. authcost Amount that the transaction was authorised for, in the currency given as authcurrency. Note: This is a legacy parameter. Do not use this parameter in any server-side scripts. authcurrency The currency used for authorisation. authamountstring HTML string produced from authorisation amount and currency. rawauthmessage The text received from the bank summarising the different states listed below: cardbe.msg.authorised - Make Payment (test or live) trans.cancelled - Cancel Purchase (test or live) rawauthcode A single-character bank authorisation code. This is retained for backward compatibility. 'A' means 'authorised' and is directly equivalent to transstatus='y'. callbackpw The Payment Response password set in the Merchant Interface. cardtype The type of payment method used by the shopper. countrymatch A single character describing the result of the comparison of the cardholder country and the issue country of the card used by the shopper (where available). Note that this parameter is retained for backward compatibility - equivalent information is now provided as part of the AVS results. The result possible values are: Y - match N - no match (i.e. mismatch) B - comparison not available I - contact country not supplied S - card issue country not available 11

14 AVS A 4-character string giving the results of 4 internal fraud-related checks. The characters respectively give the results of the following checks: 1st character - Card Verification Value check 2nd character - postcode AVS check 3rd character - address AVS check 4th character - country comparison check (see also countrymatch) The possible values for each result character are: 0 - Not supported 1 - Not checked 2 - Matched 4 - Not matched 8 - Partially matched wafmerchmessage If you have the Risk Management service enabled, you will receive one of the fraud messages listed below: waf.warning = Warning waf.caution = Caution For more detailed explanation about the fraud message, refer to the Risk Management Service Guide. authentication If you have enrolled to the Verified By Visa, MasterCard SecureCode or American Express SafeKey authentication schemes you will receive one of the authentication messages listed below: ARespH.card.authentication.0 = Cardholder authenticated ARespH.card.authentication.1 = Cardholder/Issuing bank not enrolled for authentication ARespH.card.authentication.6 = Cardholder authentication not available ARespH.card.authentication.7 = Cardholder did not complete authentication ARespH.card.authentication.9 = Cardholder authentication failed 12

15 For more detailed explanation about the authentication messages, refer to the Card Authentication Guide. ipaddress charenc _SP.charEnc The IP address from which the purchase token was submitted. The character encoding used to display the payment page to the shopper. As charenc. Recurring Payment parameters futurepayid futurepaystatuschange The ID for the Recurring Payments agreement. The status of the agreement, set to either Merchant Cancelled or Customer Cancelled depending if the merchant or the shopper has cancelled the agreement. The following are not included in the Payment Message: MD5 signature and signaturefields. The optional parameters: authvalidfrom and authvalidto. Any of your own variables labelled with the prefix C_. Any payment page appearance parameters including: fixcontact, hidecontact, lang, nolanguagemenu, withdelivery, subst. For a full list of parameters used by the Payment Service, refer to the Hosted Payment Page (HTML Redirect) Guide. Callback Examples Example: One-time payment The following callback example shows a message returned for an authorised one-time payment. POST /fail?installation=xxxxxx&msgtype=authresult HTTP/1.0Content- Type: application/x-www-form-urlencoded; charset=utf-8host: 973User-Agent: WJHRO/1.0 (WorldPay Java HTTP Request Object)region=new+format+region&authAmountString=%26%23163%3B10.00 &_SP.charEnc=UTF- 13

16 8&desc=&tel=&address1=new+format+address1&countryMatch=N&cartId= &address2=new+format+address2&address3=new+format+address 3&town=city&region=county&callbackPW=&lang=en&rawAuthCode=A&transS tatus=y&amountstring=%26%23163%3b10.00&authcost=10.00&currency=gbp &installation=205844&amount=10.00&wafmerchmessage=waf.warning&coun trystring=united+kingdom&displayaddress=new+format+address1%0anew+ format+address2%0anew+format+address3%0anew+format+town%0anew+form at+region&transtime= &name=authorised&testmode=0&ipadd ress= &fax=&rawauthmessage=cardbe.msg.authorised&insti d=205844&avs=2004&compname=bg+address+change&authamount=10.00&post code=postcode&cardtype=visa&cost=10.00&authcurrency=gbp&country=gb &charenc=utf- 8& =test%40test.worldpay.com&address=new+format+address1%0Anew +format+address2%0anew+format+address3&transid= &msgtype= authresult&town=new+format+town&authmode=a Example: Payment made within a FuturePay agreement For an authorised payment made within a FuturePay agreement, the desc parameter includes the following: The Payment X of FuturePay agreement ID XXXXXXX string, where: X is the payment number made within the agreement. XXXXXXX is the FuturePay Agreement Id. The &futurepayid= parameter. The following example shows a FuturePay callback message, with the sensitive data removed: POST /fail?installation=xxxxxx&msgtype=authresult HTTP/1.0Content- Type: application/x-www-form-urlencoded; charset=utf-8host: 800User-Agent: WJHRO/1.0 (WorldPay Java HTTP Request Object)region=&authAmountString=%26%23163%3B59.99&_SP.charEnc=UTF- 8&desc=Payment+X+of+FuturePay+agreement+ID+XXXXXXX&tel=0770+XXX+XX XX&address1=&countryMatch=S&cartId=CartId&address2=&address3=&lang =en&callbackpw=&rawauthcode=a&amountstring=%26%23163%3b59.99&trans Status=Y&authCost=59.99&currency=GBP&installation=XXXXXX&amount=59.99&countryString=United+Kingdom&displayAddress=20+Test+Road&name= Mr+Smith&testMode=0&transTime= &routeKey=ECMC- SSL&ipAddress=&fax=&rawAuthMessage=cardbe.msg.authorised&instId=XX XXXX&AVS=0111&compName=Company+Ltd&futurePayId=XXXXXXX&authAmount= 59.99&postcode=XXXXXX&cardType=MasterCard&cost=59.99&authCurrency= GBP&country=GB&charenc=UTF- 8& =mail%40test.com&address=20+Test+Road&transId=XXXXXX&msgTyp e=authresult&town=&authmode=a 14

17 Changing the Request Method The Payment Message is always sent to your server using the POST request method. If your payment response server-side script uses the GET request method and requires the data to be included in the URL query string, you will need to change your Payment Response URL to include WPDISPLAY ITEM tags. A WPDISPLAY ITEM tag enables you to add a range of parameters to the end of your payment response URL. For a full list of all the parameters that can be included, refer to Parameter descriptions for the Payment Message. The example below shows how to add multiple WPDISPLAY ITEM tags to your payment response URL: Y ITEM=transId>&reference=<WPDISPLAY ITEM=cartId>&name=<WPDISPLAY ITEM=name-urlenc> For an authorised transaction the URL this will be converted to: stallation=38290&transaction= &reference=test Item&name=john smith For a cancelled transaction it will be converted to: stallation=38290&transaction=&reference=test Item&name=john smith For parameters like name, address1, address2, town, region and where the shopper has entered the value, we recommend that you add a -urlenc modifier to the WPDISPLAY ITEM tag, as shown above. This encodes certain characters so that they can be correctly sent and decoded by you payment response server-side script. The characters that require to be encoded are less than ASCII 34 ("), greater than ASCII 122 (z), and characters in the following list:!#$%^&()+=[]\`':;?@/<> Adding your own variables If you require additional parameters to be added to the HTTP(s) Payment Message, you will need to add your own variables to the purchase token. To send your own variables in the purchase token, they must have a prefix of either, M_, MC_ or CM_, for example: <input type="hidden" name="mc_myvariable" value="abcdef123456"> This will then return in the body of Payment Message: &MC_myVariable=abcdef

18 For further information about how to add your own variables to the purchase token, please refer to the Hosted Payment Page (HTML Redirect) Guide. If you customise your payment page to include paymenttopfields.html, paymentmiddlefields.html or paymentbottomfields.html and these files have input fields to collect additional information during the payment process. If the shopper cancels the purchase, the additional information collected will not be returned to you in the Payment Message. The values collected using your own variables are not stored by us once the Payment Message has been sent to your server. The Payment Message Header The header section of the Payment Message includes details of the encoding and protocols used to produce the message. Example of a Payment Message header: Send: POST /cgi-bin/test.cgi?msgtype=authresult&installation= HTTP/1.0 Content-Length: 658 Content-Type: application/x-www-form-urlencoded; charset=iso Host: test.worldpay.com:5095 User-Agent: WJHRO/1.0 (WorldPay Java HTTP Request Object) Send: Details of the Request Method, the URL query string for the location of your payment response server-side script and the protocol of how it is sent. We insert the msgtype and installation parameters to the end of the URL query string. Content-Type: Details the encoding of the message and the character set used. The charset value may not always be set ISO , as it is set to the charset used to display the payment page to the shopper. Content-Length: A count of the number of characters that is contained in the body of the Payment Message. Host: The name and port of the web server that the Payment Message is sent to. User-Agent: We use a non standard user-agent to send you the Payment Message and therefore, may have an impact on the configuration of some server-side scripting. 16

19 If you are using the User-Agent to control what is displayed to the shopper in the Shopper Response, we recommend that you capture the User-Agent that the shopper is using and include this value in your purchase token using a M_ variable. Testing Purpose This section provides details on how you can test if you are receiving the Payment Message and how you can check its content. Use Enabling the failure - to change your installation to enable the failure . Failure Messages - to view or edit the description of the failure messages included in the failure . Suspension of Payment Response - to view the explanation for when is the Payment Response feature suspended and to reactivate the Payment Response after a number of failures. Checking the Transaction Status - to check if a shopper's transaction has been authorised. Validate the Payment Response - to check if the Payment Message was sent from our server and review the fraud indicators. Enabling the failure If the payment response feature did not complete 100% successfully, we can notify you of the failure via a Payment Response failure . The payment response failure includes the Transaction ID, Cart ID, Installation ID and the failure message reported from your server. If there is no Transaction ID included in the , then no authorisation took place. This is due to the shopper cancelling the purchase or, if you have enabled the recurring payment response, the recurring payment agreement being cancelled. To enable the payment response failure 1. Log in to the Merchant Interface. 2. Select Installations from the left hand navigation. 3. Choose an installation and select the Integration Setup button for either the TEST or PRODUCTION environment. 4. Enter the Payment Response failure address of person to whom the notification must be sent. 5. Select the Save Changes button. 17

20 As a default the failure will include the Payment Message and any error logs created. If you no not wish to receive these attachments in your failure 1. Log in to the Merchant Interface. 2. Select Installations from the left hand navigation. 3. Choose an installation and select the Integration Setup button for either the TEST or PRODUCTION environment. 4. Uncheck the Attach Payment Message to the failure checkbox. 5. Select the Save Changes button. Failure messages The table below details all of the possible failure messages that are included in the Payment Response failure failure messages meaning A non-empty path is required, A value is required Broken pipe, Cannot create output stream, Socket closed These are caused because the full Payment Response URL cannot be determined. This may be because you are using a Dynamic Payment Response but did not specify the Payment Response URL in your purchase token. Alternatively, the Dynamic Payment Response URL specified in the purchase token was empty. The connection to the Payment Response server has been broken mid-stream. This may be due to a time-out expiring, or an actual server failure. Payment Response suspended due to previous failure Payment Response obtained HTTP '301' response Payment Response obtained HTTP '302' response Payment Response obtained There is a serious problem with your Payment Response URL as it has not responded successfully after 200 attempts. We will no longer send the Payment Message to Payment Response URL, until after you have unchecked the Suspend Payment Response checkbox in the Merchant Interface - Integration Setup page. The requested resource has been redirected to a new URL as specified in the returned Location: header. Redirection using the Payment Response is not permitted. Your server did not understand the request. 18

21 HTTP '400' response This can be caused by an incorrectly typed Payment Response URL in the Merchant Interface - Integration Setup page, or your server not accepting the "Content- Type:" in the Payment Message header. This may also be caused because you are using <wpdisplay item> syntax as part of the Payment Response URL, and your web server is only permitting correctly formatted URLs to be used. We therefore, recommend that you include a -urlenc modifier suffix to the <wpdisplay item>. Payment Response obtained HTTP '401' response Payment Response obtained HTTP '403' response Payment Response obtained HTTP '404' response Payment Response obtained HTTP '405' response Payment Response obtained HTTP '500' response If your Payment Response URL requires a username and password for authenticating access, one or both of these are incorrect. Alternatively, you are using Oracle WebDB listener and your Payment Response server-side script is failing to log in to a database successfully. Either your server is configured to refuse connections from our IP address range, or the Payment Response URL is slightly wrong. Your Payment Response server-side script does not exist at the URL specified. Please check that the Payment Response URL is correct and that the server-side script is present in the intended location. The Payment Response server-side script is not supported. Please contact your Internet Service Provider to ensure the script you have uploaded to their server can be used. Your Payment Response URL could be contacted but the Payment Response server-side script failed to complete successfully. This generic error is often the result of an error within the Payment Response server-side script or in the returning of improperly formatted headers. One reason is that the parameter names in the Payment Message are case sensitive and your Payment Response server-side script is incorrectly referencing such parameters. 19

22 If you are using Microsoft.NET for your Payment Response script, you may receive this because Request Validation is objecting to the values of amountstring and authamountstring. Please see px for more information on how to disable this feature. Also, if you are using.net version 4.0, you will need to set requestvalidationmode="2.0". Payment Response obtained HTTP '501' response Payment Response obtained HTTP '502' response Payment Response obtained HTTP '503' response Payment Response obtained HTTP '504' response Payment Response obtained HTTP '506' - '599' response Cannot send requests to relative URLs Destination address is prohibited Failed to do merchant HTTP request. Check that you have the correct URL and that the merchant server is up and The Payment Response has requested the server to do something it cannot. The server in question may need upgrading. The Payment Response server-side script requested data from another server and received an error from that server. The server hosting your Payment Response server-side script is over tasked and cannot process the request. The server may be down for maintenance, or there may just be too many users currently on the site. Our connection to the server hosting the Payment Response server-side script was broken. This is due to our connection being inactive for longer than permitted (the time limit will usually be set by your ISP) or there is server/network problem. There are user-defined failure messages, possibly useful for testing purposes but should be disabled before being deployed in a live environment. Your Payment Response URL is of the form directory/script.cgi. Please check that your Payment Response URL begins with name]/ or name]/ as required. Your Payment Response URL is pointing to your installation folder located on our server, this is not permitted. Either the server cannot handle any more connections at the time the Payment Response was attempted, or the server is 20

23 running. no longer running. - Connection refused Failed to do merchant HTTP request. Check that you have the correct URL and that the merchant server is up and running. - Connection reset by peer Failed to do merchant HTTP request. Check that you have the correct URL and that the merchant server is up and running. - java.net.unknownhostexceptio n: An existing connection was forcibly closed by the remote host. This normally results if the Payment Response server-side script on the remote host is suddenly stopped, the host is rebooted, the host or remote network interface is disabled, or the remote host uses a hard close. This failure may also result if a connection was broken due to keep-alive activity detecting a failure while one or more operations are in progress. We were unable to find a DNS entry for your server. It is possible that this was caused by a type of DNS misconfiguration called "Lame delegation". For more details of this and how it can be stopped please see Failed to do merchant HTTP request. Check that you have the correct URL and that the merchant server is up and running. The clock on the server hosting your Payment Response server-side script is set incorrectly. - javax.net.ssl.sslexception: Unrecognized SSL handshake Failed to do merchant HTTP request. Check that you have the correct URL and that the merchant server is up and running. We are unable to determine how to reach the server where your Payment Response server-side script is hosted. - No route to host Failed to do merchant HTTP request. Check that you have the correct URL and that the merchant server is up and running. - Read timed out We are unable to capture any of the intended output of the Payment Response server-side script, because the server has taken too long to respond. This has been occasionally caused where a Payment Response URL is using Failed to do merchant HTTP request. Check that you have the We are unable to reach your Payment Response server-side script within 30 21

24 correct URL and that the merchant server is up and running. - Timed socket connection failure - took more than 30000ms seconds. The most common cause is that your firewall dropped our request. This is similar to "Connection refused" failure message. For input string: "" invalid HTTP status line returned Invalid port number Null or zero length URL SSL V2.0 servers are not supported The maximum limit of bytes has been exceeded Unsupported URL scheme You have specified the character ":" in your Payment Response URL, but have not included the port number after it. The Payment Response server-side script is not returning a suitable status header, i.e. 200 OK. This is typically because the server-side script has crashed completely, or because a "no-parsed-headers" script returned invalid syntax for the first line. The Payment Response URL is not a valid URL. This failure occurs if you have enabled the Payment Response but have not specified a Payment Response URL in the Merchant Interface - Integration Setup page. We are unable to send the HTTP(s) Payment Message to a server that uses SSL 2.0. Please ensure that either the server is upgraded to support SSL 3.0 or TLS 1.0, or that you use http: rather than https: for your Payment Response URL. Your Shopper Response is more than 128KB of data. This may be caused by the use of CSS in the response. If this is the case, you must separate these resources from the output of your Payment Response server-side script by referencing external files, which you can upload to your Installation if required. Your Payment Response URL is syntactically incorrect; e.g. beginning with rather than Alternatively, you are using ftp:// or gopher://. You must use either or 22

25 Suspension of Payment Response Upon a Payment Response failure, we will temporary suspend the feature and start to count the number of consecutive failures. We strongly recommend that you review why the Payment Response has been suspended and fix any errors as soon as possible to avoid shopper dissatisfaction and loss of order details information. When Payment Response feature is temporarily suspended, we will still attempt to send you the Payment Message for the next 200 transactions. If all the 200 attempts fail, the Payment Response feature is fully suspended and you will not receive any further payment messages or failure s. If any of the attempts were successful, the Payment Response feature is automatically reactivated and the failure count is reset to zero. Manually Reactivating the Payment Response Based on the information provided in the failure , you will need to fix the problem with either your payment response server-side script or the server connectivity, before you can reactive the Payment Response. To reactive the Payment Response after it has been suspended: 1. Log in to the Merchant Interface. 2. Select Installations from the left hand navigation. 3. Choose an installation and select the Integration Setup button for the TEST environment. 4. Review the Payment Response failure count to see how many attempts have failed. 5. Un-check the Suspension of Payment Response checkbox. 6. Select the Save Changes button. 7. Submit a test transaction. 8. If this is successfully, the Payment Response is reactivated and the failure count is reset to zero. 9. Repeat the process on the PRODUCTION environment. We recommend that you store critical information about the shopper's order before submitting a Purchase Token, so the information is not lost in the event of a Payment Response Failure. 23

26 Checking the Transaction Status To determine whether a transaction was authorised or cancelled, you should always check the value of the transstatus parameter included in the Payment Message. A value of Y indicates that the transaction has been authorised, whereas, a value of C means that the transaction was cancelled. If the transaction was authorised, you should also check the value of the testmode parameter before processing the shopper's order. If a value is not present or has a value of 0, then the transaction was authorised on the live Production environment and should be processed. Do not rely on the presence or absence of a transaction ID to indicate a successfully authorised live transaction. Validate the Payment Response To validate that the Payment Response has been sent from us and that the payment is not fraudulent, you will need to do some basic checks on the information provided to you in the Payment Message. By using a unique value for the cartid, you can check that the order details that you have recorded and the payment details sent in the Payment Message, relate to each other and are accurate. Adding a password to your Payment Response To help validate that the Payment Message has been sent from us, you can add a Payment Response Password. By adding a password to your payment response, you can enable your payment response server-side script to do a basic security check, before you start processing the shopper's order. To add a Payment Response Password: 1. Log in to the Merchant Interface. 2. Select Installations from the left hand navigation. 3. Choose an installation and select the Integration Setup button for either the TEST or PRODUCTION environment. 4. Enter a password into the Payment Response Password input field. 5. Select the Save Changes button. 6. The password is then included in the Payment Message using the parameter name, callbackpw. 24

27 Checking the Purchase Token IP address By checking the IP address included in the Payment Message with the parameter name, ipaddresss, you can validate the shopper's IP address. Although we cannot provide you with the IP addresses that we sent the Payment Response from, you should check the Payment Message Header that the host name used ends in.worldpay.com, and that it resolves to the same IP address. Checking the fraud indicators To reduce the risk of processing a fraudulent payment, you will need to check the following parameters sent to you in the Payment Message. countrymatch The countrymatch parameter displays the value for the comparison of the cardholder country with the issue country of the card used by the shopper. AVS The AVS parameter displays a value for each of the checks done on the Card Verification Value, postcode, address and country comparison wafmerchmessage The wafmerchmessage parameter is included in the Payment Message, only if the Risk Management service has identified that an authorised transaction should be investigated further. The value waf.caution will be returned if there are inconsistencies in the transaction characteristics that warrant further checks. These inconsistencies are likely to be based on discrepancies in the billing address details (e.g. address verification mismatches). The value waf.warning will be returned if there is a significant discrepancy in the billing address details and/or a Card Security Code mismatch and/or an unusual pattern of shopping activity (e.g. a higher rate of purchases containing the same shopper or card detail than we would normally expect). authentication The authentication parameter is included in the Payment Message, only if you have enrolled into the Verified By Visa, MasterCard SecureCode or American Express SafeKey authentication schemes. For further information about the fraud indicator listed above, refer to Parameter descriptions. We recommend that you record the values of the fraud indicators and IP address and validate the content after the Payment Response process has been completed. 25

28 Shopper Response Purpose The shopper response feature enables you to present a customised response to the shopper's browser after a payment has been authorised or cancelled. This requires that your payment response server-side script generates a valid HTML output, which we then retrieve from your server and display to the shopper. This section provides details of how to display your own response to the shopper. Use Enabling - change your installation to enable shopper response. Creating - requirements for creating a shopper response. Testing - reviewing the look and feel of the shopper response. Enabling the shopper response As a default the shopper response feature is set to OFF, to enable this feature: 1. Log in to the Merchant Interface. 2. Select Installations from the left hand navigation. 3. Choose an installation and select the Integration Setup button for either the TEST or PRODUCTION environment. 4. Check the Enable Shopper Response checkbox. 5. Select the Save Changes button. Creating a Shopper Response To create a shopper response you will need to change your payment response server-side script so that it produces a valid HTML output. If you wish to display a different shopper response for a payment that has been authorised or cancelled, then you will need to check the transstatus returned in the Payment Message, and create a valid HTML output (including the banner WPDISPLAY ITEM tag) for each of the statuses. If your system requires a full redirect to your own Webpage, you can include a META refresh (with a short delay) in the output of your payment response script (shopper response). Including the banner WPDISPLAY ITEM tag The shopper response must include the WPDISPLAY ITEM tag: <WPDISPLAY ITEM=banner>. After a shopper response is retrieved from your server, the <WPDISPLAY ITEM=banner> is used to present the mandatory transaction information to the shopper. Alternatively, you must present the Transaction ID and result of the transaction on any page that you are redirecting your customers to. 26

29 Displaying images The HTML output generated by your payment response server-side script will be presented to the shoppers' browser as if it had come from us. As such, any images that you wish to display will need to be uploaded to your installation folder, and referred to within the HTML output generated as follows, where xxxxx is your installation ID: <img src="/i/xxxxx/imagename.gif"> You could also replace the installation ID with the WPDISPLAY item tag: <wpdisplay item=instid> as we will replace this with the correct installation ID before the response is displayed to the shopper. <img src="/i/<wpdisplay item=instid>/imagename.gif"> This is helpful if you are running the same shopper response across a number of different installations. Including your own resources files and variables You may wish to include your own resource file to the shopper response, i.e Cascading Style Sheet files (.css). We recommend that you upload these files to your installation folder and reference them in the HTML output as follows: <link rel="stylesheet" href="/i/<wpdisplay item=instid>/stylesheetname.css" type="text/css" /> To reference or link to any resource outside of your installations folder, the link included in the HTML output must be absolute, in other words the full URL must be used. If any resources used in the HTML output are fetched from an address the shopper may see a warning message from their browser that states that there is a mixture of secure and insecure items is being used on the page. This warning message may be of concern to shoppers who have just entered their payment details on our payment service. Therefore, we recommend that you try to avoid referencing resources outside of your installation folder or that you reference the resource files from a secure server that has an address. To include additional payment parameters in the Shopper Response, you will need to add your own variables to the purchase token with either the C_ or MC_ prefix. Variables prefixed with M_ are not available for use in the shopper response. For more information refer to: Adding your own variables. To ensure that the character encoding used in your Shopper Response is displayed correctly by the shopper's browser, you should include an appropriate Meta tag in the head of your HTML output. 27

30 Testing the Shopper Response To test that the shopper is receiving your shopper response correctly, generate a test transaction and then review the HTML output after the transaction has been either authorised or cancelled. We do not validate the HTML output generated by your payment response server-side script therefore; you will need to check the shopper response for the following failures: failure meaning The default resulty.html and resultc.html pages are displayed We did not retrieve a shopper response from your server within 2 minutes of the request. The shopper response displays unexpected transaction information at the top of the HTML output. The WPDISPLAY ITEM tag: <WPDISPLAY ITEM=banner> is not included in the HTML output. No images are displayed, or the look and feel looks incorrect. The payment response serverside script has incorrectly referenced files from your installation folder. To get full details about of any shopper response failure, enable the failure and select that you wish to attach the Payment Message and error logs to the . The errors logs will indicate to you what we tried to retrieve from your server and therefore, what has caused the failure. Dynamic Payment Response Purpose This section provides details of how the dynamic payment response feature is used to enable the use of a different payment response server-side script, every time a purchase token is sent through to us. Use Adding a dynamic URL - include a dynamic url variable to your purchase token. Configuring your installation - change the payment response URL to accept the dynamic url variable. 28

31 Adding a dynamic URL to the purchase token It is possible to change the Payment Response URL every single time a purchase token is sent through to us, by including a dynamic URL variable to the purchase token. To include the dynamic URL variable within your purchase token you must prefix the variable name with either "M_" or "MC_" and then include the URL as the value of the variable, for example: <input type="hidden" name="mc_callback" value=" For further information about how to add your own variables to the purchase token, please refer to your integration guide. By including the Payment Response URL within the purchase token, you have created a security risk as someone can now send a spoof Payment Message to the URL. We therefore recommend that you always validate that the Payment Message was actually sent by us. Once included in your purchase token you will need to configure your installation to accept the dynamic URL variable, refer to Configuring your installation to accept a dynamic payment response. Configuring your installation to accept a dynamic payment response When you have included the dynamic url variable into the code that generates your purchase tokens, you will need to change your installation to accept this variable. To change the payment response URL to accept the dynamic url variable: 1. Log in to the Merchant Interface. 2. Select Installations from the left hand navigation. 3. Choose an installation and select the Integration Setup button for either the TEST or PRODUCTION environment. 4. Check the Enable Payment Response checkbox. 5. Enter a WPDISPLAY ITEM tag which includes the dynamic url variable, for example <wpdisplay item=mc_callback>, into the Payment Response URL input field. 6. Select the Save Changes button. To ensure that the dynamic payment response feature always sends you a Payment Message, we recommend that you change the payment response URL to include a -ppe modifier and empty property, for example: <wpdisplay item=mc_callback-ppe empty=" 29

32 This will then send the Payment Message to the default URL stated in the empty property, unless we receive a payment response URL from the purchase token. Recurring Payment Responses Purpose If your installation is set up for Recurring Payments (also known as FuturePay) you can enable the Payment Response feature to inform you if: A payment has been authorised. A payment is declined. The shopper has cancelled the agreement. You have cancelled the agreement. The Recurring Payments Response is an addition to the Payment Response generated by the initial payment and is designed to only inform you of any changes to a Recurring Payments agreement. It will not return any of your own variables that were submitted by the original purchase token and you will not be able to present any response to the shopper. You can also enable the Payment Response feature to inform you when a payment agreement is created, even if an immediate payment is not taken. The Payment Message sent to your server will include additional parameters including the recurring payment ID and details of the agreement status. Therefore you will need to make sure that your server-side script can differentiate between the different types of Payment Messages. For more information about what is sent to you in the Payment Message, refer to Parameter descriptions. For more information about Payment Notifications (Callbacks), refer to the Recurrent Payments Service (FuturePay) Guide. This section provides details of how to enable and test a payment response for a recurring payment. Use Enabling - change your installation to enable recurring payment responses. Testing - create a test recurring payment response and checking for the Payment Message for different states of responses. Using a dynamic Payment Response - enable a dynamic payment response for a Recurring Payments. 30