Send order details

Prerequisite: You've been given a Username, Password and Installation ID by the account holder.

The first step in the process.

Complete example of a HTML form

Here's an example of a HTML form with all possible data that can be sent in an order. The first five parameters (including testMode) are always mandatory:

<form action="" method=POST> <!-- Specifies the URL for our test environment -->
  <input type="hidden" name="testMode" value="100"> <!-- 100 instructs our test system -->
  <input type="hidden" name="instId" value="The installation ID "> <!-- A mandatory parameter -->
  <input type="hidden" name="cartId" value="The ID for the product "> <!-- A mandatory parameter - reference for the item purchased -->
  <input type="hidden" name="amount" value="The cost of the product "> <!-- A mandatory parameter -->
  <input type="hidden" name="currency" value="currency code e.g. GBP, USD "> <!-- A mandatory parameter. ISO currency code -->
<!-- The below parameters are all optional in this submission, but some become mandatory on the payment page -->
  <input type="hidden" name="address1" value="1st line of address">
  <input type="hidden" name="address2" value="2nd line of address">
  <input type="hidden" name="address3" value="3rd line of address">
  <input type="hidden" name="town" value="Town">
  <input type="hidden" name="region" value="Region/County/State">
  <input type="hidden" name="postcode" value="Post/Zip Code">
  <input type="hidden" name="country" value="Country">
  <input type="hidden" name="desc" value="Description of purchase">
  <input type="hidden" name="resultfile" value="Final landing Page for shopper">
  <input type="hidden" name="accId1" value="Tells us which merchant code to use (if more than one)">
  <input type="hidden" name="authMode" value="Specifies an authorisation mode e.g. Pre-authorisation">
  <input type="hidden" name="authValidFrom" value="Time window for purchase to complete (from)">
  <input type="hidden" name="authValidTo" value="Time window for purchase to complete (to)">
  <input type="hidden" name="name" value="Shopper's full name"> <!-- Accepts test values to simulate transaction outcome-->
  <input type="hidden" name="tel" value="Shopper's telephone number">
  <input type="hidden" name="fax" value="Shopper's fax number">
  <input type="hidden" name="email" value="Shopper's email address">
<!-- The below optional parameters control the behaviour of the payment pages -->
  <input type="hidden" name="fixContact" value="Prevents contact details from being edited">
  <input type="hidden" name="hideContact" value="Hides contact details">
  <input type="hidden" name="hideCurrency" value="Hides the currency drop down">
  <input type="hidden" name="lang" value="Shopper's language choice">
  <input type="hidden" name="noLanguageMenu" value="Hides the language menu">
  <input type="hidden" name="withDelivery" value="Displays and mandates delivery address fields">
<!-- This optional parameter is for testing, only relevant if you're creating your own messages files -->
  <input type="hidden" name="subst" value="Lets you see the names of message properties">
<!-- The below optional parameters can be used in the payment pages -->
  <input type="hidden" name="amountString" value="HTML string produced from the amount and currency submitted">
  <input type="hidden" name="countryString" value="Full name of the country produced from the country code">
  <input type="hidden" name="compName" value="Name of the company">
<!-- The below optional parameters instruct us to return data in the transaction result -->
  <input type="hidden" name="transId" value="Worldpay's ID for the transaction">
  <input type="hidden" name="futurePayId" value="Worldpay's ID for a FuturePay (recurring) agreement, if applicable">
  <input type="hidden" name="transStatus" value="Result of this transaction">
  <input type="hidden" name="transTime" value="Time of this transaction">
  <input type="hidden" name="authAmount" value="Amount the transaction was authorised for">
  <input type="hidden" name="authCurrency" value="The currency used for authorisation">
  <input type="hidden" name="authAmountString" value="HTML string produced from auth amount and currency">
  <input type="hidden" name="rawAuthMessage" value="Text received from bank">
  <input type="hidden" name="rawAuthCode" value="Single character authorisation code">
  <input type="hidden" name="callbackPW" value="Payment Responses password, if set">
  <input type="hidden" name="cardType" value="Type of card used by the shopper">
  <input type="hidden" name="countryMatch" value="Result of comparison between shopper's country and card issuer country">
  <input type="hidden" name="AVS" value="Address Verification Service result">
<!-- The below optional parameters are prefixes for types of custom parameter -->
  <input type="hidden" name="C_" value="Prefix for parameters only used in the result page">
  <input type="hidden" name="M_" value="Prefix for parameters only used in the payment responses">
  <input type="hidden" name="MC_" value="Prefix for parameters used in the both the result page and payment responses">
  <input type="hidden" name="CM_" value="Prefix for parameters used in the both the result page and payment responses">
  <input type=submit value=" Buy This "> <!-- Creates the button. When clicked, the form submits the purchase details to us. -->

Parameters explained

Mandatory parameters

These parameters must be sent in every order submission:

Parameter nameTypeDescription
instIdIntegerThe Id of the installation. A unique reference assigned for the website. It tells us which payment methods and currencies are supported by this installation.
cartId255 charThe reference number for this purchase. It is returned with the authorisation results by whatever method (email and/or Payment Responses).
amountDecimalA 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: The decimal separator must be a dot (.), regardless of the typical language convention for the chosen currency. The decimal separator does not need to be included if the amount is an integral multiple of the major currency unit. Do not include other separators, for example between thousands.

currency3 char3 letterISO currency codefor this payment.

Optional parameters

These parameters are optional for the order details submission, but some of them become mandatory at the next step - the payment page:

Parameter nameTypeMandatory in payment page?Description
address184 charYesThe first line of the shopper's address. Encode newlines as "&#10;" (the HTML entity for ASCII 10, the new line character).
If this is not supplied in the order details then it must be entered in the payment pages by the shopper.
address284 charNoThe second line of the shopper's address. Encode newlines as "&#10;" (the HTML entity for ASCII 10, the new line character).
address384 charNoThe third line of the shopper's address. Encode newlines as "&#10;" (the HTML entity for ASCII 10, the new line character).
town30 charYesThe town or city. Encode newlines as "&#10;" (the HTML entity for ASCII 10, the new line character).
If this is not supplied in the order details then it must be entered in the payment pages by the shopper.
region30 charNoThe shopper’s region / county / state. Encode newlines as "&#10;" (the HTML entity for ASCII 10, the new line character).
postcode12 charCan be set to mandatoryThe shopper's postcode.

Note: With your request, we can assign mandatory status to this parameter. That is, if it is not supplied in the order details then the shopper must enter it in the payment pages.

country2 charYesThe shopper's countryISO 2 character code, in upper case.
If this is not supplied in the order details then the country must be chosen in the payment pages by the shopper.
desc255 char-A textual description of this purchase, up to 255 characters. This is used in web-pages, statements and emails for yourself and the shopper.
resultFilestring-The name of one of your uploaded files, used to display the final result page to the shopper. If this is not specified, resultY.html or resultC.html is used as described inTell your shopper about payment results.
accId[n]string-This is the Merchant Code that receives funds for this payment. By default , our server tries accId1.
authModechar-This is the authorisation mode to use. If there is no merchant code with a matching authMode then the transaction is rejected. The values are "A" for a full authorisation, or "E" for a pre-authorisation. In the payment result, this parameter may take the value "O" when performing a post-authorisation.
testModeinteger-A value of '100' specifies that this is a test payment. Specify the test result you want by entering REFUSED, AUTHORISED, ERROR, or CAPTURED in the name parameter.
When you submit order details using the testMode parameter and the URL for the Live Production Environment, you are presented with a page asking you if you want to redirect the order details to the Test Environment – select Redirect if you do.
If you submit order details to the Live production environment, our systems attempt to debit merchant codes (accounts).
Reversing transactions such as these, and adjusting accounts, causes unnecessary work for us as well as you.
Set this parameter to '0' (zero) or omit it for a Live transaction.
Refer to the Test and Go Live Guide.
authValidFrominteger-This specifies a time window within which the purchase must (or must not) be completed. For example, if the purchase is a time-limited special offer. Each of these parameters is a time in milliseconds since 1 January 1970 GMT - a Java long date value (as from System.currentTimeMillis() or Date.getTime()), or 1000* a C time_t).
If from<to, then the authorisation must complete between those two times. If to<from, then the authorisation must complete either before the 'to' time or after the 'from' time. Either may be zero or omitted to give the effect of a simple "not before" or "not after" constraint. If both are zero or omitted, there are no restrictions on how long a shopper can spend making their purchase (although our server times out their session if it is idle for too long).
name40 char-The shopper's full name, including any title name, personal name and family name.

Note: If you do not pass through a name, and use Payment Responses, the name that the cardholder enters on the payment page is returned to you as the value of name in the Payment Responses message.

Note: If you are sending a test submission you can specify the type of response you want from our system by entering REFUSED, AUTHORISED, ERROR or CAPTURED as the value in the name parameter. You can also generate an AUTHORISED response by using a real name, such as, J. Bloggs. For more information, refer to the Test and Go Live Guide.

tel30 char-The shopper's telephone number.
fax30 char-The shopper's fax number.
email80 charYesThe shopper's email address.

Display parameters

Parameters that control the behaviour of the payment pages:

Parameter nameTypeDescription
fixContactneeds no valueIf present, this causes contact details to be displayed in non-editable format. You must ensure that all mandatory contact details are submitted in your initial request.
hideContactneeds no valueIf present, this causes contact details to be hidden. You must ensure that all mandatory contact details are submitted in your initial request.
Existing merchants should set the following message files to empty strings for the feature to work: cont.instr.existing,, cont.heading
hideCurrencyneeds no valueIf present, this causes the currency drop down to be hidden, fixing the currency that the shopper must purchase in.
lang6 charThe shopper's language choice, as a 2-character ISO 639 code, with optional regionalisation using 2-character country code separated by hyphen. For example "en-GB" specifies UK English. The shopper can always choose a language on our pages or via browser preferences but if your site has already made this choice then you can make things more convenient by submitting it to us.
noLanguageMenuneeds no valueSuppresses the display of the language menu if you have a choice of languages enabled but want the choice to be defined by the value of the lang parameter that you submit. Please contact your local Technical Support department if you would like this facility enabled on your account.
withDeliveryneeds no valueDisplays input fields for delivery address and mandates that they be filled in.

The subst parameter

The subst parameter is intended for use during testing. It is only relevant if you are creating your own messages files.

Parameter nameTypeDescription
subststring: "yes" or "no"If the value is "no" then message substitution is turned 'off'. You see the names of the message properties from the file used to create the page. This situation persists until you submit a payment with subst=yes, or your session is ended.

Payment page parameters

These parameters can be used in the payment pages:

Parameter nameTypeDescription
amountStringVariable length char stringAn HTML string produced from the amount and currency that were submitted to initiate this purchase.
countryStringVariable length char stringThe full name of the country, derived from the country code submitted to initiate this purchase or supplied by the shopper.
compNameVariable length char stringName of the company associated with this installation.

Payment result parameters

In addition to all of the above, these parameters can be used in the payment results. At the payment result stage of processing, the contact details for the shopper are those that were used for authorising the payment.

The parameters authAmount, authCurrency, etc., are set to those of the actual transaction carried out. These could be different than the values submitted to us when the transaction was initiated, as the shopper may have chosen a different currency on the payment page.

Note: The length of characters is the maximum length that we can accept – anything longer is truncated to this length.

Parameter nameTypeDescription
transIdinteger - 16 digitsWorldpay ID for this transaction.
futurePayIdinteger - 16 digitsWorldpay ID for a FuturePay agreement (where relevant).
transStatus1 charResult of this transaction - "Y" for a successful payment authorisation, "C" for a cancelled payment (note that you never see a declined payment, because the shopper is always given the option of retrying with another means of payment, or else cancelling the payment).
transTimelong integerThe time of this 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.
authAmountdecimalThe amount that this transaction was authorised for, in the currency given as authCurrency.
authCurrency3 charThe currency used for authorisation.
authAmountStringVariable length char stringHTML string produced from authorisation amount and currency.
rawAuthMessagestringThe text received from the bank (typically including an authorisation code, or a reason for failure).
rawAuthCode1 charA single-character bank (or internal Worldpay) authorisation code. This is retained for backward compatibility. 'A' means 'authorised' and is directly equivalent to transStatus='Y'. Failed transactions may have a variety of auth codes which are usually explained more fully in the rawAuthMessage parameter.
callbackPWstringThe Payment Responses password, if you have set it in our database via theBusiness Manager. This is only available in the parameters sent in the Payment Responses message. It is not available for substitution into the page sent to the shopper.
cardTypestringThe type of card used by the shopper.
countryMatch1 charA single character describing the result of the comparison of the shopper's contact country (where supplied) 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 (see AVS below).
  • Y - Match
  • N – No match (that is, mismatch)
  • B – Comparison not available
  • I - Contact country not supplied
  • S - Card issue country not available
AVS4 charThe Address Verification System (AVS) provides the ability to check the shopper's billing address and postcode against the card issuer's details. The AVS results combine the results of the AVS check with the results of a CVV check.
CVV is a three-digit number printed at the end of the signature strip on the vast majority of credit/debit cards. The CVV is a unique number that cannot be replicated by fraudsters, and for this reason, it is commonly known as the 'security code'.
The results of the Security Code and Address Verification are provided as a four character string in which each character reports the result of a particular verification/check.
The characters 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(please also refer to countryMatch)
The possible values for each result character are:
  • 0 - Not supported
  • 1 - Not checked
  • 2 - Matched
  • 4 - Not matched

    Custom parameters

    You can create your own custom parameters and then use them in your own versions of the resultY.html (authorised) or resultC.html (cancelled by shopper) confirmation pages.

    Your custom parameters can also be passed through our payment service and returned to a server in aPayment Response message.

    Create custom parameters

    When you create custom parameters you must give them different prefixes, depending on their use:

    Custom parameter prefixWhere usedConditions
    "C"Custom parameters to be used only in the shopper's result page should have names starting with "C".Available for use in the result pages, but are not available to your Payment Responses script.
    "M"Custom parameters that you want to return only in aPayment Response messageshould have names starting with "M".Available to your Payment Responses script, but are not available for use in the result pages.
    "MC" or "CM"For when you want to use a parameter for both the shopper's result page and in aPayment Response message.Available to both your Payment Responses script and the result pages.