Payment Response

Payment Response Guide
Version 4.3 September 2012

Business Gateway
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 ................................................................................................................................. 17
Shopper Response .............................................................................................................. 26
Dynamic Payment Response............................................................................................... 28
Recurring Payment Responses ........................................................................................... 30
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 18
4.0
Gateway and guide name

added to navigation path.
December 2011
All pages
3.1
Payment Page updates.
October 2011
Pages 6-7
3.0
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.
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 email.
Send the shopper additional information about their order in your own result pages or
an order confirmation email.
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.
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 Email: For successful transactions, we send an email 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.
Reference
This section provides detailed information about the Payment Response feature for your
reference. It includes detailed descriptions of:
Setting Up
Payment Message
Testing
Shopper Response
Dynamic Payment Response
Recurring Payment Responses
Setting Up
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 HTTPS:// you will need to make
sure that your server supports either SSL 3.0 or TLS 1.0.
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:
http://www.asp.net/faq/requestvalidation.aspx 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 shoppers
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=UTF8&desc=&tel=0870+366+1233&address1=WorldPay+Ltd&countryMatch=S&car
tId=test&address2=270289+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%0A270289+The+Science+Park%0AMilton+Road%0ACambridge%0ACambridgeshire&tr
ansTime=1331631533596&name=CARD+HOLDER&testMode=100&routeKey=VISASSL&ipAddress=62.249.232.76&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=UTF6
8&email=support%40worldpay.com&address=WorldPay+Ltd%0A270289+The+Science+Park%0AMilton+Road%0ACambridge%0ACambridgeshire&tr
ansId=129170095&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
Your own reference number for the

order.
desc
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. 12.56 would mean
12 pounds and 56 pence if the
currency were GBP (Pounds Sterling).
Note: This is a legacy parameter. Do

not use this parameter in server-side
scripts.
amount
A decimal number giving the cost of

the purchase in terms of the major
currency unit e.g. 12.56 would mean
12 pounds and 56 pence if the
currency were GBP (Pounds Sterling).
amountString
An HTML string produced from the

amount and currency that were
submitted to initiate the payment.
currency
3 letter ISO code for the currency of

this payment.
authMode
Specifies the authorisation mode

used. The values are "A" for a full
auth, or "E" for a pre-auth.
testMode
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.
name
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.
address1
The first line of the shopper's address.

Separators (including new line) used
in this parameter are encoded as
ASCII characters.
address2
The second line of the shopper's

address.
address3
The third line of the shopper's

address.
town
Shoppers city or town.
region
Shoppers country/region/state or
area.
postcode
Shopper's postcode.
country
Shopper's country, as 2 character ISO

code, uppercase.
countryString
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.
tel
Shopper's telephone number.
fax
Shopper's fax number.
email
Shopper's email address.
delvName
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.
delvAddress1
Shopper's delivery address1. Note:

The withDelivery parameter must be
Payment Message.
delvAddress2
Shopper's delivery address 2. Note:

Payment Message.
delvAddress3
Shopper's delivery address 3. Note:

Payment Message.
delvTown
Shopper's delivery town or city. Note:

Payment Message.
delvRegion
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.
delvPostcode
Shopper's delivery postcode. Note:

Payment Message.
delvCountry
Shopper's delivery country, as 2

character ISO code, uppercase. Note:
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
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.
transTime
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.
authAmount
Amount that the transaction was
10
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
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:
wafMerchMessage
0 - Not supported
1 - Not checked
2 - Matched
4 - Not matched
8 - Partially matched
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
Cardholder/Issuing bank not
enrolled for authentication
Cardholder authentication not
available
Cardholder did not complete
authentication
Cardholder authentication failed
12
For more detailed explanation about

the authentication messages, refer to
the Card Authentication Guide.
ipAddress
The IP address from which the

purchase token was submitted.
charenc
The character encoding used to

display the payment page to the
shopper.
_SP.charEnc
As charenc.
Recurring Payment parameters

futurePayId
The ID for the Recurring Payments

agreement.
futurePayStatusChange
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.0ContentType: application/x-www-form-urlencoded; charset=UTF-8Host:
www.worldpay.comContent-Length: 973User-Agent: WJHRO/1.0 (WorldPay
Java HTTP Request
Object)region=new+format+region&authAmountString=%26%23163%3B10.00
&_SP.charEnc=UTF13
8&desc=&tel=&address1=new+format+address1&countryMatch=N&cartId=15
615166165&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=1313762603546&name=AUTHORISED&testMode=0&ipAdd
ress=192.168.90.15&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=UTF8&email=test%40test.worldpay.com&address=new+format+address1%0Anew
+format+address2%0Anew+format+address3&transId=1300002227&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.0ContentType: application/x-www-form-urlencoded; charset=UTF-8Host:
www.website.co.ukContent-Length: 800User-Agent: WJHRO/1.0
(WorldPay Java HTTP Request
Object)region=&authAmountString=%26%23163%3B59.99&_SP.charEnc=UTF8&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=1343438417376&routeKey=ECMCSSL&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=UTF8&email=mail%40test.com&address=20+Test+Road&transId=XXXXXX&msgTyp
e=authResult&town=&authMode=A
14
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:
http://www.myserver.com/mycallbackscript.cgi?transaction=<WPDISPLA
Y ITEM=transId>&reference=<WPDISPLAY ITEM=cartId>&name=<WPDISPLAY
ITEM=name-urlenc>
For an authorised transaction the URL this will be converted to:

http://www.myserver.com/mycallbackscript.cgi?msgType=authResult&in
stallation=38290&transaction=12227758&reference=Test
Item&name=john smith
For a cancelled transaction it will be converted to:

http://www.myserver.com/mycallbackscript.cgi?msgType=authResult&in
stallation=38290&transaction=&reference=Test Item&name=john smith
For parameters like name, address1, address2, town, region and email 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=abcdef123456
15
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=204793
HTTP/1.0
Content-Length: 658
Content-Type: application/x-www-form-urlencoded; charset=ISO-88591
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-8859-1, 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
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 email - to change your installation to enable the failure email.
Failure Messages - to view or edit the description of the failure messages included in
the failure email.
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 email

If the payment response feature did not complete 100% successfully, we can notify you of the
failure via a Payment Response failure email. The payment response failure email 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 email, 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 email:

4. Enter the Payment Response failure email address of person to whom the
notification must be sent.
17
As a default the failure email will include the Payment Message and any error logs created. If
you no not wish to receive these attachments in your failure email:
4. Uncheck the Attach Payment Message to the failure email checkbox.
Failure messages
The table below details all of the possible failure messages that are included in the Payment
Response failure email:
failure messages
meaning
A non-empty path is required,
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.
A value is required
Broken pipe,
Cannot create output stream,
Socket closed
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
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 .
Payment Response obtained

HTTP '301' response
HTTP '302' response
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
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 "ContentType:" 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>.

HTTP '401' 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.

HTTP '403' response
Either your server is configured to refuse

connections from our IP address range, or
the Payment Response URL is slightly
wrong.

HTTP '404' response
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.

HTTP '405' response
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.

HTTP '500' response
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
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
http://www.asp.net/faq/requestvalidation.as
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".
HTTP '501' response
The Payment Response has requested the

server to do something it cannot. The
server in question may need upgrading.

HTTP '502' response

requested data from another server and
received an error from that server.

HTTP '503' response
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.

HTTP '504' response
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.

HTTP '506' - '599' response
There are user-defined failure messages,

possibly useful for testing purposes but
should be disabled before being deployed
in a live environment.
Cannot send requests to

relative URLs
Your Payment Response URL is of the

form directory/script.cgi. Please check that
your Payment Response URL begins with
http://[server name]/ or https://[server
name]/ as required.
Destination address is
prohibited
Your Payment Response URL is pointing to

your installation folder located on our
server, this is not permitted.
Failed to do merchant HTTP

request. Check that you have the
correct URL and that the
merchant server is up and
Either the server cannot handle any more

connections at the time the Payment
Response was attempted, or the server is
20
running.
no longer running.
- Connection refused
running.
- Connection reset by peer

running.
java.net.UnknownHostExceptio
n: www.myserver.com
running.
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
http://www.faqs.org/rfcs/rfc1713.html.
The clock on the server hosting your

Payment Response server-side script is set
incorrectly.
- javax.net.ssl.SSLException:
Unrecognized SSL handshake
running.
We are unable to determine how to reach

the server where your Payment Response
server-side script is hosted.
- No route to host
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 https://.
We are unable to reach your Payment

Response server-side script within 30
21

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: ""
You have specified the character ":" in your

Payment Response URL, but have not
included the port number after it.
invalid HTTP status line

returned

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.
Invalid port number
The Payment Response URL is not a valid

URL.
Null or zero length 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.
SSL V2.0 servers are not

supported
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.
The maximum limit of 131072

bytes has been exceeded
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.
Unsupported URL scheme
Your Payment Response URL is

syntactically incorrect; e.g. beginning with
http:/ rather than http://. Alternatively, you
are using ftp:// or gopher://. You must use
either http:// or https://.
22
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 emails.
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 email, 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:
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.
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
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:
4. Enter a password into the Payment Response Password input field.
6. The password is then included in the Payment Message using the parameter name,
callbackPW.
24
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
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:
4. Check the Enable Shopper Response checkbox.
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
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 http:// 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 https:// 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
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 email and select
that you wish to attach the Payment Message and error logs to the email. 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
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="http://www.myserver.com/mycallbackscript.cgi">
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:
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.
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="http://www.myserver.com/callback.cgi">
29
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
Enabling a Recurring Payment Response

As a default the Recurring Payments (FuturePay) response feature is set to OFF, to enable
this feature:
4. Check the Enable Recurring Payments Response checkbox.
The Enable Payment Response checkbox must also be checked before
the Recurring Payments Response feature is enabled.
Testing a Recurring Payments Response

To test that you are receiving a Payment Message when a Recurring Payments agreement
has been created or cancelled, you will need to first generate a test recurring payment limited
agreement. The generated test recurring payment limited agreement should set the values of
both the amount and option variables to zero and not include any values for the other
recurring payment variables. The agreement can then be created without providing any valid
payment details as the payment is not send for authorisation.
Once the test agreements have been created, you can use the Merchant Interface to cancel
the agreement.
To test your recurring payment response when a payment is declined, make sure that the
amount variable is zero, the testMode variable is set to 100 and the cardholder name is
REFUSED in your test recurring payment limited agreement.
For more information about how to create, test and cancel a recurring payment agreement,
refer to the Recurring Payment Guide.
Checking the different types of the Recurring Payment Response
You will receive a Payment Message for each of the different types of a Recurring Payment
response including:
Creation of the Recurring Payments agreement

When a recurring payment agreement has been created the transStatus parameter is set to Y
and the futurePayId parameter is included in the Payment Message.
Cancellation of a Recurring Payments agreement

When a recurring payment agreement has been cancelled the futurePayStatusChange
parameter will be included in the Payment Message and will have a value of either Merchant
Cancelled or Customer Cancelled.
31
Payment made on a Recurring Payments agreement

When a successful payment attempt has been made on a recurring payment agreement the
desc parameter in the Payment Message will include the word FuturePay as well as the
payment number and the Recurring Payments agreement ID. A successful payment attempt
does not indicate that the payment has been authorised by the card issuer.
Using a dynamic Payment Response with a Recurring Payment

It is possible to have different Payment Response URL's for each of the different types of
Recurring Payments response and for the standard Payment Response. This can be
achieved by including a dynamic URL variable in the purchase token and configuring your
installation to check for changes to Recurring Payments agreement before generating the
Payment Response URL.
Payment Response URL Examples
Example 1
<wpdisplay item=MC_callback-ppe
empty="http://www.myserver.com/callback.cgi">
Example 2
<wpdisplay item=MC_callback-ppe empty="<wpdisplay
item=rawAuthCode-ppe pre='http://www.myserver.com/fppayment.cgi?'
empty='http://www.myserver.com/fpcancel.cgi'>">
In the above example:

If the purchase token has not sent a standard Payment Response URL via the
MC_callback variable, then the code examines if a rawAuthCode is present.
If a value for the rawAuthCode parameter is present then a payment attempt has
been made on the recurring payment agreement and the Payment Response URL http://www.myserver.com/fppayment.cgi, will be used.
If the purchase token did not send the Payment Response URL and there is not
value for the rawAuthCode parameter, the recurring payment agreement has been
cancelled and the Payment Response URL - http://www.myserver.com/fpcancel.cgi,
will be used instead.
For further information about how to enable a dynamic payment response, refer to Dynamic
Payment Response.
32

Payment Response

Uploaded by

Copyright:

Available Formats

Payment Response

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Payment Response

Uploaded by

Copyright:

Available Formats

Payment Response Guide

Version 4.3 September 2012