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 that 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 that 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 that 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

Shopper’s city or town.

region

Shopper’s 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 that 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 that the withDelivery parameter must be submitted in the purchase token for you to receive this parameter in the Payment Message.

delvAddress2

Shopper's delivery address 2. Note that the withDelivery parameter must be submitted in the purchase token for you to receive this parameter in the Payment Message.

delvAddress3

Shopper's delivery address 3. Note that the withDelivery parameter must be submitted in the purchase token for you to receive this parameter in the Payment Message.

delvTown

Shopper's delivery town or city. Note that the withDelivery parameter must be submitted in the purchase token for you to receive this parameter in the Payment Message.

delvRegion

Shopper's delivery county/state/region. Note that 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 that 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 that 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 that 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 that 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 authorised for, in the currency given as authCurrency.

authCost

Amount that the transaction was authorised for, in the currency given as authCurrency.  Note that 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

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

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.0Content-Type: 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=UTF-8&desc=&tel=&address1=new+format+address1&countryMatch=N&cartId=15615166165&address2=new+format+address2&address3=new+format+address3&town=city&region=county&callbackPW=&lang=en&rawAuthCode=A&transStatus=Y&amountString=%26%23163%3B10.00&authCost=10.00&currency=GBP&installation=205844&amount=10.00&wafMerchMessage=waf.warning&countryString=United+Kingdom&displayAddress=new+format+address1%0Anew+format+address2%0Anew+format+address3%0Anew+format+town%0Anew+format+region&transTime=1313762603546&name=AUTHORISED&testMode=0&ipAddress=192.168.90.15&fax=&rawAuthMessage=cardbe.msg.authorised&instId=205844&AVS=2004&compName=BG+Address+change&authAmount=10.00&postcode=postcode&cardType=Visa&cost=10.00&authCurrency=GBP&country=GB&charenc=UTF-8&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 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: www.website.co.ukContent-Length: 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+XXXX&address1=&countryMatch=S&cartId=CartId&address2=&address3=&lang=en&callbackPW=&rawAuthCode=A&amountString=%26%23163%3B59.99&transStatus=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=ECMC-SSL&ipAddress=&fax=&rawAuthMessage=cardbe.msg.authorised&instId=XXXXXX&AVS=0111&compName=Company+Ltd&futurePayId=XXXXXXX&authAmount=59.99&postcode=XXXXXX&cardType=MasterCard&cost=59.99&authCurrency=GBP&country=GB&charenc=UTF-8&email=mail%40test.com&address=20+Test+Road&transId=XXXXXX&msgType=authResult&town=&authMode=A