Developers

CardValidate2

Important note.

All BankVal web services are available on both the main and backup servers at our primary data centre. This configuration is mirrored at our secondary data centre. The two data centres are geographically independent. Using this configuration, the BankVal web service has been available continuously since launch in 2003.

In general:

  • Call the service at the primary data centre at www.unifiedservices.co.uk
  • In the unlikely event of a failure, call the service at the secondary data centre at www.unifiedsoftware.co.uk

1 Cardvalidate2 - REST


CardValidate2 functionality:

  • The cardvalidate2 method verifies a card number and returns the card type, card issuer and country of issue.

Please note that cardvalidate2 does NOT check that the card actually exists, that there are sufficient funds available, that the card has been reported as stolen, etc.


To make sure you utilise our backup system, follow these three steps:-

  • 1. Attempt to access the service on unifiedservices.co.uk
  • 2. Check the http response code
  • 3. If this is < 200 or > 399, access the backup service on unifiedsoftware.co.uk

URI for Cardvalidate2

  • GET https://www.unifiedservices.co.uk/services/bankvaluk/cardvalidate2/userid/<userid>/pin/<pin>
    /cardnumber/<cardnumber>/<format>/
  • If http response code is < 200 or > 399 then call:-
  • GET https://www.unifiedsoftware.co.uk/services/bankvaluk/cardvalidate2/userid/<userid>/pin/<pin>
    /cardnumber/<cardnumber>/<format>/

where:

  • <userid> and <pin> are your user ID and 5 digit PIN obtained upon registration at:
    www.unifiedsoftware.co.uk/free-trial/free-trial-home.html
  • <cardnumber> > is the card number to be validated.
  • <format> specifies the format of the returned data. Valid formats are csv, xml and json. (csv uses the "|" delimiter)

Results

If card number is valid:-

  • The string VALID is returned, accompanied by information about the card

Sample valid response in xml format :-

<cardvalidate2>

  • <result>VALID<result>
  • <country>UNITED KINGDOM</country>
  • <countrycode></countrycode>
  • <type>VISA CREDIT</type>
  • <finame>BARCLAYS BANK PLC</finame>

</cardvalidate2>


Sample valid response in json format :-

  • {"result":"VALID",
  • "country":"UNITED KINGDOM",
  • "countrycode":"",
  • "type":"VISA CREDIT",
  • "finame":"BARCLAYS BANK PLC",
  • }

Sample valid response in csv format :-

  • VALID|UNITED KINGDOM||VISA CREDIT|BARCLAYS BANK PLC|

If sort code and account number are not valid or if an error occurs:-

  • Result field - contains an error message
  • Remaining fields are empty

Error messages :-

Error Messages

INVALID - Modulus Check Failed - The card number failed the modulus check / was not in a recognisable card number format.

INVALID - Result Format - format parameter was not ‘xml’, ‘json’ or ‘csv’.

ERROR - Invalid User ID/PIN - The User ID or PIN has not been recognised.

ERROR - UserID Expired - Trial user ID has expired.

ERROR - Insecure Connection - An attempt was made to access BankVal's cardvalidate2 method using insecure HTTP protocol instead of HTTPS.


<< Back to Top >>


2 CardValidate2 - SOAP


CardValidate2 functionality:

  • BankVal UK‘s cardvalidate2 method may be used to validate credit and debit card numbers, and retrieve important information about the card issuer, card type and country of issue.

Choose SOAP style:

There are two main ways of implementing SOAP, Document Literal and RPC. For help choosing the best solution for your implementation, please contact support@unifiedsoftware.co.uk.



<< Back to Top >>


2.1 CardValidate2 - SOAP Document Literal


CardValidate2 functionality:

  • Cardvalidate2 may be used to validate credit and debit card numbers, and retrieve important information about the card issuer, card type and country of issue.

WSDL files

The WSDL file on the primary data centre is at https://www.unifiedservices.co.uk/services/bankvaluk/cardvalidate2.php?wsdl

The WSDL file on the backup data centre is at https://www.unifiedsoftware.co.uk/services/bankvaluk/cardvalidate2.php?wsdl


Request

Parameters

Description

userid

BankVal UK User ID.

pin

5 digit PIN.

cardnumber

Card Number to be validated.


Response

Field

Description

result

Result string contains on of the following messages:-
VALID - Card number is valid.
INVALID - Modulus Check Failed - The card number failed the modulus check / was not in a recognisable card number format.
ERROR - Invalid User ID/PIN - The User ID or PIN has not been recognised.
ERROR - UserID Expired - Trial user ID has expired.
ERROR - Insecure Connection - An attempt was made to access BankVal's cardvalidate2 method using insecure HTTP protocol instead of HTTPS.

country

Country of issue.

countrycode

Country code of issue.

type

Debit / credit.

finame

Name of card issuer.



<< Back to Top >>


2.2 Cardvalidate2 - SOAP RPC


Cardvalidate2 functionality:

  • BankVal UK‘s cardvalidate2 method may be used to validate credit and debit card numbers, and retrieve important information about the card issuer, card type and country of issue.

Please note that cardvalidate2 does NOT check that the card actually exists, that there are sufficient funds available, that the card has been reported as stolen, etc.

Parameter Format for CardValidate2

ReturnMessage = cardvalidate2(QueryString)

where:-

QueryString = userID|PIN|card number

All possible ReturnMessage values are shown below

ReturnMessage meanings

Note the delimiters "|" - these are included in all responses from cardvalidate2, even if the individual fields are not populated.

VALID - followed by card information in the following format:

  • VALID|<country of issue>|<country code>|<card type>|<card issuer>|
  • Note the trailing "|" character.
  • Example: VALID|UNITED KINGDOM||VISA DEBIT|BARCLAYS BANK PLC|

INVALID - Modulus Check Failed|||||- The card number failed the modulus check / was not in a recognisable card number format.

ERROR - Invalid User ID/PIN||||| - The User ID or PIN has not been recognised.

ERROR - UserID Expired||||| - Trial user ID has expired

ERROR - Insecure Connection||||| - An attempt was made to access BankVal's cardvalidate2 method using the insecure HTTP protocol instead of HTTPS


WSDL files

The WSDL file on the primary data centre is at https://www.unifiedservices.co.uk/bankvaluk3.wsdl

The WSDL file on the backup data centre is at https://www.unifiedsoftware.co.uk/bankvaluk3.wsdl


<< Back to Top >>