Initiating Purchase Transaction Parameters

instId

integer

Your Installation Id.

cartId

255 char

Your own reference number for this purchase. It is returned to you along with the authorisation results by whatever method you have chosen for being informed (email and / or Payment Notifications).

amount

Decimal

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

currency

3 char

3 letter ISO code for the currency of this payment - please refer to the appendix Currency Codes.

Also note that at your request we can assign mandatory status to the postcode parameter to help prevent fraud. When this parameter is set to mandatory, a shopper has to supply postcode details and a card security code in the payment pages.

address

255 char

Yes

The shopper's address. Encode newlines as "
" (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.

country

2 char

Yes

The shopper's country, as 2 character ISO code, uppercase. Please refer to the appendix Country Codes.

If this is not supplied in the order details then it must be entered in the payment pages by the shopper.

desc

255 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.

resultFile

string

-

The name of one of your uploaded files, which will be used to format the result. Please refer to Configuring Your Installation. If this is not specified, resultY.html or resultC.html are used as described in Payment Result - to You.

accId<n>

integer

-

This specifies which merchant code should receive funds for this payment. By default our server tries accId1.

authMode

char

-

This specifies the authorisation mode to use. This is only needed if you have merchant codes with different authorisation modes, in order to specify which type of merchant code to use. If there is no merchant code with a matching authMode then the transaction is rejected. The values are "A" for a full auth, or "E" for a pre-auth. In the payment result this parameter can also take the value "O" when performing a post-auth.

testMode

integer

-

A value of 100 or 101 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 will be presented with a page asking you if you want to redirect the order details to the Test Environment - select the Redirect button if you do.

If you submit the order details to the live, production environment our systems will attempt to debit merchant codes (accounts).

Reversing transactions such as these, and adjusting accounts, will cause unnecessary work for us as well as yourself.

Set this parameter to 0 (zero) or omit it for a live transaction.

Please also refer to the Test and Go Live Guide.

authValidFrom

integer

-

This specifies a time window within which the purchase must (or must not) be completed, eg. 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 will time-out their session if it is idle for too long).

authValidTo

integer

name

40 char

-

The shopper's full name, including any title, personal name and family name.

Note that if you do not pass through a name, and use Payment Notifications (Callbacks), the name that the cardholder enters on the payment page will be returned to you as the value of name in the Payment Notifications message.

Also note that 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 please refer to the Test and Go Live Guide.

postcode

12 char

Can be set to mandatory

The shopper's postcode.

Note that at 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.

tel

30 char

-

The shopper's telephone number.

fax

30 char

-

The shopper's fax number.

email

80 char

-

The shopper's email address.

parameter name

type

description

fixContact

needs no value

If 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.

hideContact

needs no value

If 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.instr.new, cont.heading

lang

6 char

The 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.

noLanguageMenu

needs no value

NEW GATEWAY ONLY: This suppresses display of the language menu if you have a choice of languages enabled for your installation 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.

withDelivery

needs no value

NEW GATEWAY ONLY: Display input fields for delivery address and mandate that they be filled in.