This is the HTML template we use for accepting the card payments. It is written using a server side scripting extension to HTML. This form template can be downloaded and customised to your in house look and feel if you cannot achieve this with our formatting parameters. However, we will need to host this on our server. It is available here. We would strongly recommend that you get your site working with our default template before requesting this.

This is the HTML template we use for displaying error messages, you can supply your own by using this parameter. NOTE : if this URL is wrong then there will be no template for displaying the error message to that effect, you have been warned...

There are a number of options settings which can be listed.
NOTE : different options should be comma delimited. e.g. test_status=true,dups=false.

A set of parameters that allow you to tailor the text against entry fields, useful for change prompts, foreign language prompts etc.

NOTE :case is important

A set of parameters that allow you to tailor the text against credit card types - or make them unavailable. The parameters are :

NOTE : case is important

A set of parameters that allow you to tailor the text shown in the event of an error. Useful for tailoring error message text and foreign language errors.

NOTE : case is important

The type of card the customer is using to pay. The possible values are :

The SECPay secure server will then take the customer's payment details and carry out an initial validation, it will also take the billing address details if requested. The authorisation form then does checks on the validity of the card number, expiry date and issue number (where relevant). If it does not pass these checks then the form will be re-presented to the customer with an indication of the problem field and the customer will be asked to correct the problem.

Once the initial checks succeed the payment details will be sent through our firewall to a very secure machine in an encrypted form. They will be then be forwarded over a secure private network to the bank. The bank will process these details and respond appropriately.

The bank may reject the card for several reasons. The most common ones are, insufficient funds, cancelled card, or fraudulent claims (where the card has been contrived to pass standard checks but does not actually exist).

back to index

This is a structured field and can either be supplied in the format defined below or as XML.

The order field has the following internal structure. It consists of a set of product identifier and amount pairs with a multiplier attached to the amount. as "prod,amountxquantity" The string requires some means of being delimited. Delimiters MUST NOT appear in the actual data (e.g. in the product code) or your string will not be parsed correctly and you will loose information. There are four delimiters, ';', ',', '=' and 'x'. An optional parameter 'delimit' is available at the start of the order string and can be used to change the defaults. For example, "prod=funny_book,item_amount=18.50x1;prod=sad_book,item_amount=16.50x2" can be fully specified as : "delimit=;,=x;prod=funny_book,item_amount=18.50x1;prod=sad_book,item_amount=16.50x2". The delimiters can be changed to allow strange things like this : "delimit=#+:*;prod:funny,;=book+item_amount:18.50*1#prod:sad,book+item_amount:16.50*2". Giving silly characters in the product description. It is still your responsibility to ensure the resulting string is well formed. The only way to be sure is to use XML!

The first member of each pair is called "prod" and is your product number or other identifier. The second member is either "amount" or item_amount which is the either the order line total, or the unit cost each item and may have the number of items appended preceded by an 'x'. There are three special prod values which can be passed, and will be stored by the system as specifics which are

SHIPPING, DISCOUNT and TAX can be used. If tax is not included in the price then a special value of "TAX" or "TAX @ 17.5%" can be used. Also their is a special code for discounts of "DISCOUNT".

Importantly, the sum of all the values should equal the total amount supplied for authorisation. It is your responsibility to ensure this as SECPay does not verify that the total for the order lines match the amount supplied for authorisation.

The pair of values is separated by ',' (comma) character, each pair is separated by an ';' (semicolon) character. If a multiplier is used then an 'x' character should follow the amount and be followed by a number.

An XML example is (please preserve the class parameters and case on tags) :

<order class='com.secpay.seccard.Order'>
  <orderLines class='com.secpay.seccard.OrderLine'>
    <OrderLine>
      <prod_code>funny_book</prod_code>
      <item_amount>18.50</item_amount>
      <quantity>1</quantity>
    </OrderLine>
    <OrderLine>
      <prod_code>scary_book</prod_code>
      <item_amount>10.00</item_amount>
      <quantity>5</quantity>
    </OrderLine>
  </orderLines>
</order>

Please note that as HTML and XML have the same quoting conventions (either single or double quotes) if you use the fragment above then you must use double quotes for the HTML, i.e.

<input type="hidden" name="order" value='XML GOES HERE using double quotes'>
or
<input type="hidden" name="order" value="XML GOES HERE using single quotes"> 

This facility is supplied as a convenience for the customer so that all details can be viewed in a single place on our web site. We can take no responsibility for it's accuracy or completeness.

back to index

The shipping details can alternatively be supplied as a single string, called 'shipping' with normal URL encoding, note that if a single string is used then the fields should be separated with commas. A minimal string would normally include the telephone number and the email to answer queries.

shipping=name=Fred+Bloggs,email=somebody@secpay.com,etc

back to index

The billing details can alternatively be supplied as a single string, called 'billing'' with normal URL encoding, note that if a single string is used then the fields should be separated with commas. A minimal string would normally include the telephone number and the email to answer queries.

billing=name=Fred+Bloggs,email=somebody@secpay.com, etc

An XML Example is (note there is a 'billing' equivalent of course) :

<shipping class='com.secpay.seccard.Address'>
  <name>Fred Bloggs</name>
  <company>Acme Co</company>
  <addr_1>1 The Road</addr_1>
  <addr_2>The Cresent</addr_2>
  <city>Metropolis</city>
  <state>Sunny State</state>
  <country>Atlantis</country>
  <post_code>AA23 1BB</post_code>
  <tel>01732 300200</tel>
  <email>sales\@secpay.com</email>
  <url>http%3A//www.secpay.com/</url>
</shipping>

Please note that as HTML and XML have the same quoting conventions (either single or double quotes) if you use the fragment above then you must use double quotes for the HTML, i.e.

<input type="hidden" name="order" value='XML GOES HERE using double quotes'>
or
<input type="hidden" name="order" value="XML GOES HERE using single quotes"> 

This facility is supplied as a convenience for the customer so that all details can be viewed in a single place on our web site. We can take no responsibility for it's accuracy or completeness.

back to index

Returned if the options parameter test_status was set to either 'true' or 'false'

back to index

Synchronous calls can be made to SECPay using cgi/servlet/asp functions as long as it is capable of issuing a post action. Parameters will need to be URL encoded and appended as part of the call.

back to index

For tighter integration with your server side processing, SECPay provide a set of library functions as a client side API which can be wrapped with your own code, and will make a synchronous and private connection with our secure server for authorisation.

SECPay can supply a client side API that can be used to call our secure server from either another web server or from a client machine for batch authorisation.

There are number of functions in the SECBatch API which are of the format:

<functionname>(parameters)

<functionname>Full(merchant, file)

The libraries, and full documentation are available for download for a number of platforms in the section on batch processing, as this uses the same technology.

Processes which can be carried out using the API's are as follows

An additional call is available for pre-authorisation of the card, this call will return a result string that must be parsed, please download secbatch and check the supplied examples.

preAuth(card_no, card_type, expiry, start, issue, result)

This call is simply a wrapper around an https service supplied by SECPay. This service is available at the following URL (please supply your own parameters).

https://www.secpay.com/java-bin/PreAuth?card_no=CN&card_type=CT&expiry=EX&issue=IS&start=SD

It is your responsibility to integrate these functions with your applications, though we can undertake this work on a consultancy paid basis. Please contact us if you require us to quote for this work.

back to index

SECPay provide client-side example programs for sites that collect their own credit card details and wish to forward them to us for verification. Using a remote procedure call or a command line set of parameters. The API will take it's parameters from the function call or iteratively read a set of parameters from a file and repeatedly call the SECPay server.

secbatch <merchant id> <parameters>

or

secbatch <merchant id> <filename>

Where the file consists of a set of comma separated records with the following fields or parameters:

Format : secbatch <merchant> {other args}
Where other args are : <trans_id> <caller ip> <card name> <card number> <amount> <expiry> <issue> <start date> <order details> <shipping details> <billing details> <option list>
or : <file>

Full parameter definition can be found in the section on parameters.

SECBatch can be downloaded from one of the links below. SECVPN is the preferred version for the future. SECVPN will benefit from all future exhancements and can easily be used as a COM object on Microsoft operating systems. It can also be called from Perl using the new JPL interface shipped with the newest Perl releases.

back to index

Applet Card Validation

back to index

Post Code Format Verification

As a very small first step in this direction there is now a service available to check for well formed UK postcodes. It is available at :

https://www.secpay.com/java-bin/PreAuth?postcode=TN92LE

Or alternatively if more convenient ;

https://www.secpay.com/java-bin/PreAuth?incode=TN9&outcode=2LE

back to index

Note that a merchant of 'test' will allow you to test connectivity. For full testing use 'secpay' or register and use your own merchant id. This is a simple call :

Simple call (with source).

Form based call: This form has all of its fields exposed, and will work. Normally a lot of the fields would be hidden from the customer. The example can be called from here formexample.html or view the source here formexample.txt

back to index

SECPay now support a complete XML call (over https) and response facility. It is very easy to use and is useful for those customers that have their own secure server and some XML expertise.

There is an XML equivalent of each servlet. For example the main validation servlet ValCard has an associated servlet called XMLValCard. All XML calls are made to the XML equivalents. XML requests are called XMLRequest and all Responses are called XMLResponse, regardless of what is called. These XML objects are therefore flexible, extensible and orthogonal with all other call methods. A detailed DTD is not therefore supplied, in a sense this whole document is the DTD.

The call must be an HTTPS call and must be a POST. As this type of call will normally be done programatically the XML need not be contained within an HTML form field. In fact it is preferred if it is not. However some users may wish to use a containing field, any name would do but 'xml' might be sensible.

A Simple Request might be :

		<XMLRequest><merchant>secpay</merchant><trans_id>xmltest</trans_id><amount>10.50</amount><options>test_status=true,dups=false</options><card_no>4444333322221111</card_no><expiry>1204</expiry><customer>Fred Bloggs</customer></XMLRequest>
	  

Important Note: Please ensure that all of the XMLRequest is on a single line with no spaces between the elements.

The Response would be :

		<XMLResponse>
			<valid>true</valid>
			<trans_id>xmltest</trans_id>
			<code>A</code>
			<auth_code>9999</auth_code>
			<amount>10.50</amount>
			<test_status>true</test_status>
			<hash>ff358bda726d08448b9d2df43eed9d51</hash>
		</XMLResponse>
		

Obviously other parameters and objects can be included, for example the shipping and billing addresses and a number of order lines could be included. Addresses and order lines must have the format defined above.

back to index

Some old browsers did not include the Thawte root certificate, IE 3.0 is an example. If you have trouble communicating with our secure site using an old browser then please install the Thawte root from here.

Another problem that may be experienced is with root rollover in Netscape 3. The Thawte root certificate will expire on July 27 1998 in this browser, this is only a warning. To remove this warning follow these instructions :

1. Choose Options, Security Preferences. 
2. Select the "Site Certificates" tab.
3. Find the entry marked "Thawte Server CA".  Delete that certificate. 
4. Close that dialog box. 
5. Now point your browser at http://www.thawte.com/roots/index.html This will contain a zip file containing the root certificates.
6. Install the new certificate.