The AFD Postcode Plus iOS API is easy to use and quick to implement in any Objective C application, while balancing that with providing full flexibility. A static library (libAFDPcplus.a) provides access to Postcode Plus functionality once added to your project.
For rapid development and for a quick start, take a look at our sample program here to see how Postcode Plus is integrated. Once you run that in XCode you will need to copy your licence file to the applications Documents folder on your device (unless using evaluation data). The data files (pcplus.afd, pcplusi.afd, etc.) will also need to be present. To simplify this, transfer the licence file using the SaveLicense method supplying it a Base64 encoded string and obtain the latest data files automatically by using the update functionality if you have an Internet connection.
To integrate Postcode Plus into your own Project simply add the libAfdPcplus.a library and the AfdPcplus.h header file to your project. Then create an instance of the AfdPcplus class to access AFD Postcode Plus functionality.
If you are transferring evaluation data files to the device and using the simulator the following code may be helpful, this retrieves the Documents folder into which the licence file should be placed:
NSArray *paths =
NSSearchPathForDirectoriesInDomains(NSDocumentDirectory,
NSUserDomainMask, YES);
NSString * documentsDirectoryPath = [paths objectAtIndex:0]
When deploying evaluation data to an actual device, the licence and data files can be saved to the Documents folder by any means. To transfer the file easily by iTunes do the following:
For non-evaluation purposes we recommend using the automatic update functionality to obtain the latest data files and using the SaveLicense method to save the licence from a Base64 encoded string.
A sample application demonstrating AFD Postcode Plus functionality is provided with the SDK.
To use this load the project in XCode, select the device (or the simulator) to deploy too and then click Run to start the application on the selected device.
For Evaluation data, copy that data to the Documents folder on the device.
This can be done by copying it to the Documents folder for the simulator or using iTunes File Sharing on a real device (see the previous section “Getting Started”).
For Full data, either transfer the pcplus.lic licence file to the device or use the SaveLicense method to generate the file from a Base64 string that AFD will have supplied. Then use the CheckForUpdates function to obtain the latest data.
The AddressGetFirst and AddressGetNext methods enable address records to quickly be located.
This is typically done as follows:
See the appropriate function and property references for full details of these methods and properties.
An example lookup is as follows:
// Create an instance of the AfdPcplus object
AFDPcplus *details = [AfdPcplus new];
// Set the search criteria
[details clear];
[details setSearchLookup:@”B6 4AA”];
// Do the lookup
NSInteger retVal = [details AddressGetFirst:0];
// Display any error
if (retVal < 0) {
UIAlertView *alert = [[UIAlertView alloc]
initWithTitle:@"Error"
message:[details ErrorText: retVal]
delegate:nil cancelButtonTitle:@"OK" otherButtonTitles:nil];
[alert show];
[alert release];
return;
}
// Retrieve the results
while (retVal >= 0) {
if (retVal != AFD_RECORD_BREAK) {
NSString* listItem = [details getAddressList];
// do something with this data
}
retVal = [AddressGetNext];
}
The RetrieveRecord method enables records to be quickly retrieved again, (from a list displayed to the user, for example) using its record key.
This is typically done as follows:
See the appropriate function and property references for full details of this method and properties.
An example retrieve is as follows, were recordKey is the result of calling getRecordKey for the record originally retrieved:
// Create an instance of the AfdPcplus object
AFDPcplus *details = [AfdPcplus new];
// Do the lookup
NSInteger retVal = [details JumpToRecord:recordKey];
// Display any error
if (retVal < 0) {
UIAlertView *alert = [[UIAlertView alloc]
initWithTitle:@"Error"
message:[details ErrorText: retVal]
delegate:nil cancelButtonTitle:@"OK" otherButtonTitles:nil];
[alert show];
[alert release];
return;
}
// Retrieve the result
NSString* organisation = [details getOrganisation];
NSString* property = [details getProperty];
NSString* street = [details getStreet];
NSString* locality = [details getLocality];
NSString* town = [details getTown];
NSString* postcode = [details getPostcode];
// do something with this data
To use full data with AFD Postcode Plus, a License will need to be purchased from AFD. This is provided in two forms, a file pcplus.lic and a Base64 encoded version to make entry or transfer easier.
Either save the pcplus.lic file in the applications documents folder, or use the SaveLicense method to pass the supplied base64 encoded text string to apply the license.
The process to do this is typically as follows:
An example of doing this is as follows:
NSInteger applied = [details SaveLicense: licenseString];
if (applied == 1) {
// success
}
else {
// license string not valid
}
To update Postcode Plus data, the data files (pcplus.afd, pcplusi.afd, etc.) need to be replaced in the applications Documents folder with the latest versions available from our server.
This can be done automatically using instance functions of the AfdPcplus class provided for updating.
The process to do this is typically as follows:
An example of doing this is as follows:
NSInteger needUpdate = [details CheckForUpdate];
If (needUpdate == 1) {
startedDownload = [details DownloadUpdate];
if (startedDownload == 1) {
while (isDownloadComplete == 0) {
// wait for download to complete – can carry on with other
tasks
}
}
Clears the search properties ready to start a new search
-(void) Clear
This function takes no parameters and returns no value.
Starts a lookup or search and returns the first record Prior to calling this function, call Clear and set the appropriate search parameters to specify the fields you wish to search for (e.g. setSearchLookup).
-(NSInteger) AddressGetFirst:(NSInteger)flags;
flags is an NSInteger and specifies options for the search. These are as follows:
The function returns one of the following values:
If AFD_SUCCESS is returned you can then call any of the properties to obtain the fields for the returned record, e.g. getAddressList.
If AFD_SUCCESS or AFD_RECORD_BREAK is returned you should call AddressGetNext to retrieve each subsequent record until AFD_END_OF_SEARCH is returned.
Continues a lookup or search, returning the next matching record
-(NSInteger) AddressGetNext
This function takes no parameters.
The function returns one of the following values:
If AFD_SUCCESS is returned you can then call any of the properties to obtain the fields for the returned record, e.g. getAddressList.
If AFD_SUCCESS or AFD_RECORD_BREAK is returned you should continue to call AddressGetNext to retrieve each subsequent record until AFD_END_OF_SEARCH is returned.
Returns data for the record key supplied
-(NSInteger) JumpToRecord:(NSString)recordKey;
The recordKey parameter is the key of the record to be retrieved. This would have been returned by using the getRecordKey method following a previous call to AddressGetFirst or AddressGetNext. Note this key should not be stored as it is not maintained across data updates; it is designed for reretrieving a record following a list being provided to the user.
The function returns one of the following values:
If AFD_SUCCESS is returned, any of the properties can then be called to obtain the fields for the returned record, e.g. getStreet.
Used to retrieve text to display a friendly error message to go with an error code returned from the search or validation functions (return value less than zero).
-(NSString*) ErrorText:(NSInteger*)errorCode;
errorCode is an NSInteger and should be set to the return value from a previous function call.
On return a description for the error is returned which can be stored or displayed for the user.
Used to save a license file on the device from a Base64 encoded string representation.
-(NSInteger) SaveLicense: (NSString*) base64License;
Base64License is the string containing the base64 encoded license data.
Returns:
Used to check if an update to the Postcode Plus data files is available.
-(NSInteger) CheckForUpdate;
Returns:
Used to start downloading a data update.
-(NSInteger) DownloadUpdate;
Returns:
When the function returns data continues to download in the background so your application can continue running. Poll with IsDownloadComplete periodically to determine when the download has finished.
Used to indicate when a data download has completed downloading
-(NSInteger) IsDownloadComplete;
Returns:
Used to update data files following a successful download and loads the new dataset.
-(NSInteger) ApplyUpdate;
Returns:
Methods are provided to set properties for searches and to get the resulting record details following a match. These are as follows:
| Field Name | Description |
|---|---|
| Search Fields (Any of these can be set prior to a call to AddressGetFirst) | |
| setSearchLookup | Specify fast-find string to look for, e.g. a postcode or street, town. No other search fields should be set when this is used. |
| setSearchPostcodeFrom | Set Postcode to search from (range) |
| setSearchPostcodeTo | Set Postcode to search to (range) |
| setSearchOrganisation | Set Organisation Name to search for |
| setSearchProperty | Set Property or Building Name to search for |
| setSearchStreet | Set Street Name to search for |
| setSearchLocality | Set Locality name to search for |
| setSearchTown | Set Post Town to search for |
| setSearchCounty | Set County Name to search for (searches all county types) |
| setSearchSTDCode | Set Dialling Code to search for |
| setSearchGridE | Set Grid Easting to search around (for radial searches) |
| setSearchGridN | Set Grid Northing to search around (for radial searches) |
| setSearchMiles | Set distance in miles to search around (for radial searches) |
| setSearchKm | Set distance in kilometres to search around |
| setSearchJustBuilt | Set Just Built date to search for (in format YYYYMMDD) |
| setSearchUDPRN | Set UDPRN to search for. No other search fields should be set when this is used. |
| Formatted Address Fields | |
| getRecordKey | Returns a record key to use for subsequent retrieval of the record with AddressRetrieve. Note this should not be stored as it does not persist across data updates. |
| getPostcode | Returns the Postcode |
| getPostcodeFrom | Returns the original postcode if the postcode searched for has been changed (re-coded). |
| getOrganisation | Returns the Organisation Name |
| getProperty | Returns the Building Name |
| getStreet | Returns the House Number and Street Name |
| getLocality | Returns the Locality Name |
| getTown | Returns the Post Town for this address |
| getAddressList | Returns a formatted line for list insertion containing elements of the Address record. Useful when displaying a list of results for the user to choose from. |
| Raw Address Fields (unformatted with house number in a separate field) | |
| getPAFDepartment | The department name |
| getPAFOrganisation | The organisation name |
| getPAFSubBuilding | The sub building name |
| getPAFBuilding | The building name |
| getPAFNumber | Property number |
| getPAFPOBox | PO Box number |
| getPAFDepStreet | The dependent street name |
| getPAFStreet | The street name |
| getPAFDblDepLoc | The double dependent locality name |
| getPAFDepLoc | The dependent locality name |
| County Fields | |
| getCountyPostal | Postal County (held by Royal Mail) |
| getCountyOptional | Postal Counties including optional ones (no longer held by Royal Mail) |
| getCountyAbbreivatedPostal | Postal County, abbreviated were an official abbreviation exists |
| getCountyAbbreviatedOptional | Optional County, abbreviated were an official abbreviation exists |
| getCountyTraditional | Traditional County Name |
| getCountyAdministrative Administrative County Name | |
| Additional Postal Fields | |
| getDPS | Postal County (held by Royal Mail) |
| getPostcodeFrom | Returns the original postcode if the postcode searched for has been changed (re-coded). |
| getPostcodeType | L for Large User Postcode, S for Small User. |
| getMailsortCode | Used for obtaining bulk mail discounts. |
| getUDPRN | Royal Mail Unique Delivery Point Reference Number assigned to this letter box. |
| getJustBuilt | AFDJustBuilt – Contains the date of inclusion on PAF for properties thought to be recently built. The date is stored numerically in descending format in the form YYYYMMDD. YYYY is the year, MM is the month and DD is the day. For example 20080304 is 04/03/2008. |
| getHouseholds | Number of households behind the delivery point |
| Geographical Fields | |
| getGridE | Grid Easting as a 6 digit reference |
| getGridN | Grid Northing as a 6/7 digit reference |
| getLatitude | Latitude representation of Grid Reference in Decimal Format (WGS84) |
| getLongitude | Longitude representation of Grid Reference in Decimal Format (WGS84) |
| getUrbanRuralCode | Provides a code which indicates if an area is mainly urban or rural and how sparsely populated those area’s are. [3] |
| getUrbanRuralName | Provides a description which goes along with the UrbanRuralCode. [3] |
| getSOALower | Lower level Super Output Area (Data Zone in Scotland, Super Output Area in Northern Ireland) |
| getSOAMiddle | Middle level Super Output Area (Intermediate Geography in Scotland, not applicable for Northern Ireland). |
| Administrative Fields | |
| getWardCode | Code identifying the electoral ward for this postcode |
| getWardName | Name identifying the electoral ward for this postcode |
| getAuthorityCode | Local/Unitary Authority for this Postcode (same as the start of the ward code). |
| getAuthorityName | Local / Unitary Authority for this postcode |
| getConstituencyCode | Code for the Parliamentary Constituency for this postcode |
| getConstituencyName | Name of the Parliamentary Constituency for this postcode |
| getEERCode | Code identifying the European Electoral Region for this postcode |
| getEERName | Name identifying the European Electoral Region for this postcode |
| getLEACode | Code identifying the Local Education Authority for this postcode |
| getLEAName | Name identifying the Local Education Authority for this postcode |
| getTVRegion | ISBA TV Region (not TV Company) |
| Postcode Level Property Indicator Fields | |
| getOccupancy | Indication of the type of occupants of properties found on the selected postcode [1] |
| getAddressType | Indication of the type of property level data to capture to have the full address for a property on the selected postcode. [2] |
| NHS Fields | |
| getNHSCode | National Health Service Area Code |
| getNHSName | National Health Service Area Name |
| getNHSRegionCode | National Health Service Region Code |
| getNHSRegionName | National Health Service Region Name |
| getPCTCode | National Health Service Primary Care Trust Code for England (Local Health Board Code in Wales, Community Health Partnership in Scotland) |
| getPCTName | Name matching the PCT Code field |
| Censation Fields | |
| getCensationCode | Censation Code assigned to this Postcode |
| getAffluence | Affluence description |
| getLifeStage | LifeStage description |
| getAdditionalCensusInfo | Additional information derived from the Census. |
Notes:
[1] Possible Occupancy values and descriptions are as follows (information in brackets not part of the description):
[2] Possible Address Type values and descriptions are as follows (information in brackets not part of the description):
[3] The Urban Rural Code differs from England and Wales, Scotland and Northern Ireland. The possible codes and there meanings are as follows:
The AFD BankFinder iOS API is easy to use and quick to implement in any Objective C application, while balancing that with providing full flexibility. A static library (libAfdBank.a) provides access to BankFinder functionality once added to your project.
We recommend that for the most rapid development and to help you know where to start that you take a look at our sample program here to see how BankFinder is integrated. Once you run that in XCode you will need to copy your licence file to the applications Documents folder on your device (unless using evaluation data). The data file (bacs.afd and bacsi.afd) will also need to be present. To simplify this you can transfer the licence file using the SaveLicense method supplying it a Base64 encoded string and you can obtain the latest data files automatically by using the update functionality if you have an Internet connection.
When you are ready to integrate BankFinder into your own Project simply add the libAfdBank.a library and the AfdBank.h header file to your project. You can then create an instance of the AfdBank class to access AFD BankFinder functionality.
If you are transferring evaluation data files to the device and using the simulator the following code may be helpful, this retrieves the Documents folder into which the licence file should be placed:
NSArray *paths =
NSSearchPathForDirectoriesInDomains(NSDocumentDirectory,
NSUserDomainMask, YES);
NSString * documentsDirectoryPath = [paths objectAtIndex:0]
When deploying evaluation data to an actual device you can save the licence and data files to the Documents folder by any means you wish.
To transfer the file easily by iTunes do the following:
For non-evaluation purposes we recommend using the automatic update functionality to obtain the latest data files and using the SaveLicense method to save the licence from a Base64 encoded string.
A sample application demonstrating AFD BankFinder functionality is provided with the SDK.
To use this, load the project in XCode, select the device (or the simulator) to deploy too and then click Run to start the application on the selected device.
For Evaluation data, copy that data to the Documents folder on the device. Do this by copying it to the Documents folder for the simulator or using iTunes File Sharing on a real device (see the previous section “Getting Started”).
For Full data, either transfer the afdbank.lic licence file to the device, or use the SaveLicense method to generate the file from a Base64 string that AFD will have supplied. Then use the CheckForUpdates function to obtain the latest data.
The BankGetFirst and BankGetNext methods allow bank records to quickly be located.
This is typically done as follows:
See the appropriate function and property references for full details of these methods and properties.
An example lookup is as follows:
// Create an instance of the AfdBank object
AFDBank *details = [AfdBank new];
// Set the search criteria
[details clear];
[details setSearchLookup:@”560035”];
// Do the lookup
NSInteger retVal = [details BankGetFirst:AFD_ALL_RECORDS];
// Display any error
if (retVal < 0) {
UIAlertView *alert = [[UIAlertView alloc]
initWithTitle:@"Error"
message:[details ErrorText: retVal]
delegate:nil cancelButtonTitle:@"OK" otherButtonTitles:nil];
[alert show];
[alert release];
return;
}
// Retrieve the results
while (retVal >= 0) {
if (retVal != AFD_RECORD_BREAK) {
NSString* bankName = [details getBankOwnerBankFullName];
NSString* branchTitle = [details getBankFullBranchTitle];
NSString* sortCode = [details getBankSortCode];
// do something with this data
}
retVal = [details BankGetNext];
}
The JumpToRecord method enables records to be quickly retrieved again (from a list displayed to the user, for example) using its record key.
This is typically done as follows:
See the appropriate function and property references for full details of this method and properties.
An example retrieve is as follows, where recordKey is the result of calling getRecordKey for the record you originally retrieved:
// Create an instance of the AfdBank object
AFDBank *details = [AfdBank new];
// Do the lookup
NSInteger retVal = [details JumpToRecord:recordKey];
// Display any error
if (retVal < 0) {
UIAlertView *alert = [[UIAlertView alloc]
initWithTitle:@"Error"
message:[details ErrorText: retVal]
delegate:nil cancelButtonTitle:@"OK" otherButtonTitles:nil];
[alert show];
[alert release];
return;
}
// Retrieve the result
NSString* bankName = [details getBankOwnerBankFullName];
NSString* branchTitle = [details getBankFullBranchTitle];
NSString* sortCode = [details getBankSortCode];
// do something with this data
The ValidateAccount method enables bank account details to be validated.
This is typically done as follows:
See the ValidateAccount reference for full details of this method.
An example account validation is as follows:
// Create an instance of the AfdBank object
AFDBank *details = [AfdBank new];
// define variables to pass to the ValidateAccount function
NSInteger flags;
NSString* sortCode;
NSString* accountNumber;
NSInteger typeOfAccountCode;
NSString* rollNumber;
NSInteger needRollNUmber;
NSString* iban;
NSString* countryName;
// Set parameters to validate
flags = AFD_ALL_RECORDS;
sortCode = @“774814”;
accountNumber = @“24782346”;
typeOfAccountCode = 0;
rollNUmber = @””;
needRollNUmber = 0;
iban = @””;
countryName = @””;
// Carry out the validation
NSInteger retVal = [details ValidateAccount :&flags: &sortCode:
&accountNumber: &typeOfAccountCode: &rollNumber: &needRollNumber:
&iban: &countryName];
/* Display the result – note that the sortcode and account number may
have been updated if account translation was necessary (e.g. a nonstandard
length account number was supplied) */
If (retVal >= 0) {
UIAlertView *alert = [[UIAlertView alloc]
initWithTitle:@"Account Details Validated"
message:@”Account Number Valid”
delegate:nil cancelButtonTitle:@"OK" otherButtonTitles:nil];
[alert show];
[alert release];
}
else {
UIAlertView *alert = [[UIAlertView alloc]
initWithTitle:@"Error"
message:[details ErrorText: retVal]
delegate:nil cancelButtonTitle:@"OK" otherButtonTitles:nil];
[alert show];
[alert release];
}
The ValidateCard method enables card numbers to be validated.
This is typically done as follows:
See the ValidateCard reference for full details of this method. An example card validation is as follows:
// Create an instance of the AfdBank object
AFDBank *details = [AfdBank new];
// define variables to pass to the ValidateCard function
NSInteger revisionId;
NSString* cardNumber;
NSString* expiryDate;
// Set parameters to validate
revisionID = 2; // for future proofing
cardNumber = @“ 5155744836273941”;
expiryDate = @“”; // only pass if you wish to do a date range check
on it
// Carry out the validation
NSInteger retVal = [details ValidateCard :&revisionID: &cardNumber:
&expiryDate];
/* Display the result */
If (retVal >= 0) {
UIAlertView *alert = [[UIAlertView alloc]
initWithTitle:@"Card Details Validated"
message[details CardType:retVal]
delegate:nil cancelButtonTitle:@"OK" otherButtonTitles:nil];
[alert show];
[alert release];
}
else {
UIAlertView *alert = [[UIAlertView alloc]
initWithTitle:@"Error"
message:[details ErrorText: retVal]
delegate:nil cancelButtonTitle:@"OK" otherButtonTitles:nil];
[alert show];
[alert release];
}
To use full data with AFD BankFinder you will need to purchase a License from AFD. This is provided in two forms, a file afdbank.lic and a Base64 encoded version to make entry or transfer easier.
Either save the afdbank.lic file in the applications documents folder, or use the SaveLicense method to pass the supplied base64 encoded text string to apply the license for you.
The process to do this is typically as follows:
An example of doing this is as follows:
NSInteger applied = [details SaveLicense: licenseString];
if (applied == 1) {
// success
}
else {
// license string not valid
}
It is important that BankFinder data is always up to date for correct validation. Data files should be updated weekly to ensure you always have the latest data. If that is impractical, applying an update monthly is the mandatory minimum.
To update the BankFinder data the files bacs.afd and bacsi.afd need to be replaced in the applications Documents folder with the latest versions available from our server.
This can be done automatically using instance functions of the AfdBank class provided for updating.
The process to do this is typically as follows:
An example of doing this is as follows:
NSInteger needUpdate = [details CheckForUpdate];
If (needUpdate == 1) {
startedDownload = [details DownloadUpdate];
if (startedDownload == 1) {
while (isDownloadComplete == 0) {
// wait for download to complete – can carry on with other
tasks
}
}
Clears the search properties ready to start a new search
-(void) Clear
This function takes no parameters and returns no value.
Starts a lookup or search and returns the first record
Prior to calling this function, call Clear and set the appropriate search parameters to specify the fields you wish to search for (e.g. setSearchLookup).
-(NSInteger) BankGetFirst:(NSInteger)flags;
flags is an NSInteger and specifies which clearing systems to use. The possible options are:
The function returns one of the following values:
If AFD_SUCCESS is returned you can then call any of the properties to obtain the fields for the returned record, e.g. getBankSortCode.
If AFD_SUCCESS or AFD_RECORD_BREAK is returned you should call BankGetNext to retrieve each subsequent record until AFD_END_OF_SEARCH is returned.
Continues a lookup or search, returning the next matching record
-(NSInteger) BankGetNext
This function takes no parameters.
The function returns one of the following values:
If AFD_SUCCESS is returned you can then call any of the properties to obtain the fields for the returned record, e.g. getBankSortCode.
If AFD_SUCCESS or AFD_RECORD_BREAK is returned you should continue to call BankGetNext to retrieve each subsequent record until AFD_END_OF_SEARCH is returned.
Returns data for the record key supplied
-(NSInteger) JumpToRecord:(NSInteger)recordNumber;
The recordNumber parameter is the key of the record to be retrieved. This would have been returned by using the getRecordKey method following a previous call to BankGetFirst or BankGetNext. Note this key should not be stored as it is not maintained across data updates; it is designed for reretrieving a record following a list being provided to the user.
The function returns one of the following values:
If AFD_SUCCESS is returned, any of the properties can be called to obtain the fields for the returned record, e.g. getBankSortCode.
Used to validate a sortcode and account number (or IBAN) to check it passes validation.
Parameters are all passed by reference and should be initialised to zero or a blank string as appropriate if unused.
flags is an NSInteger and specifies which clearing systems to use. The possible options are:
AFD_ALL_RECORDS - Return all records (both systems)
AFD_UK_ONLY - Only return records on the BACS system
AFD_IRISH_ONLY - Only return records on the IPSO system
On return this value will be one of the following which can be useful when validating through both systems:
sortCode is a NSString used to specify the sort code to be validated. On return it may be updated if account number translation is required, e.g. for non-standard length account numbers. The returned value should be the one submitted to BACS.
accountNumber is a NSString used to specify the account number to be validated. It should be specified along with the sort code. Like the sortcode it may be updated on return if account number translation is required.
typeOfAccountCode is an NSInteger which returns the value required for the type of account code field on BACS. This is normally zero but is required in some cases when account numbers are translated from non-standard lengths.
rollNumber is an NSString which is used to specify the Roll Number for validation. This is required along with the sortcode and account number for credits made to some building society accounts.
needRollNumber is an NSInteger which on return specifies if a roll number is required for the sortcode and account number specified. This will be one of the following values:
iban is an NSString which can be used in-place of passing a sortcode and accountnumber to validate an International Bank Account Number. If a sortcode and account number is validated it will return the corresponding IBAN were possible.
country is an NSString which returns the country name corresponding to an IBAN passed for validation.
If the function returns a positive value (>=0) this should be taken to be valid.
The function returns one of the following values:
Used to validate a card number to check it passes validation.
-(NSInteger) ValidateCard : (NSInteger*)revisionID : (NSString**)cardNumber : (NSString**)expiryDate;
revisionID is an NSInteger and should be set to 2. It is provided for future proofing.
cardNumber is an NSString used to specify the card number you wish to validate.
expiryDate is an NSString used to specify the expiry date you wish to validate.
This is optional but if specified a check will be made that the card is in date.
This should be in the format MM/YY.
On return a positive value indicates the card is valid. The return value will indicate the type of card as follows:
A negative return value indicates an error has occurred and could be any of the following:
Used to retrieve text to display a friendly error message to go with an error code returned from the search or validation functions (return value less than zero).
-(NSString) ErrorText:(NSString)errorCode;
errorCode is an NSInteger and should be set to the return value from a previous function call.
On return a description for the error is returned which can be stored or displayed for the user.
Used to retrieve text to display or store the card type returned from the ValidateCard function.
-(NSString) CardText:(NSString)cardType;
cardType is an NSInteger and should be set to the return value from the ValidateCard function when that function returns a positive value.
On return a description for the card is returned, e.g. Mastercard or Visa Debit.
Used to save a license file on the device from a Base64 encoded string representation.
-(NSString) SaveLicense: (NSString*) base64License;
Base64License is the string containing the base64 encoded license data.
Returns:
Used to check if an update to the BankFinder data files is available.
-(NSString) CheckForUpdate;
Returns:
Used to start downloading a data update.
-(NSString) DownloadUpdate;
Returns:
When the function returns data continues to download in the background so your application can continue running. Poll with IsDownloadComplete periodically to determine when the download has finished.
Used to indicate when a data download has completed downloading
-(NSString) IsDownloadComplete;
Returns:
Used to update data files following a successful download and loads the new dataset.
-(NSString) ApplyUpdate;
Returns:
Methods are provided to set properties for searches and to get the resulting record details following a match. These are as follows:
| Field Name | Description |
|---|---|
| Search Fields (Any of these can be set prior to a call to BankGetFirst) | |
| setSearchLookup | Specify sort code, postcode and fast-find lookup strings here for lookup operations. No other search fields should be set when this is used. |
| setSearchSortCode | Bank’s Sortcode |
| setSearchBankBIC | Bank’s BIC Code |
| setSearchBranchBIC | Branch BIC Code (should be used in conjunction with Bank BIC) |
| setSearchPostcode | Royal Mail Postcode for correspondence for the bank |
| setSearchBranchName | Branch Name |
| setSearchBankName | Owner Bank Name |
| setSearchTown | Town or Location of the bank |
| setSearchPhone | Phone Number |
| SearchText | Specify text to search for within any of the BankFinder fields |
| General Bank Fields | |
| getRecordKey | Returns a record key (integer) to use for subsequent retrieval of the record with JumpToRecord. Note this should not be stored as it does not persist across data updates. |
| getBankSortCode | Bank’s Sortcode |
| getBankBIC | Bank BIC Code [1] |
| getBranchBIC | Branch BIC Code [1] |
| getBankSubBranchSuffix | Allows a branch to be uniquely identified where there is a cluster of branches sharing the same Sort Code [1] |
| getBankShortBranchTitle | The official title of the branch |
| getBankCentralBankCountryCode | The ISO Country code for beneficiary banks in other countries |
| getBankSupervisoryBody | Indicates the supervisory body for an institution that is an agency in any of the clearings. [2] |
| getBankDeletedDate | Specifies the date the branch was closed if it is not active |
| getBankBranchTypeIndicator | The branch type – Main Branch, Sub or NAB Branch, Linked Branch |
| getBankMainBranchSortCode | Set for linked branches in a cluster. It identifies the main branch for the cluster. For IPSO records this is set to the branch that would handle transactions for this sortcode when the branch has been amalgamated with another. |
| getBankMajorLocationName | Where present helps indicate the physical location of the branch. |
| getBankMinorLocationName | Where present helps indicate the physical location of the branch. |
| getBankBranchName | Defines the actual name or place of the branch |
| getBankBranchName2 | An alternative name or place for the branch where applicable. |
| getBankFullBranchTitle | Extended title for the institution |
| getBankOwnerBankShortName | Short version of the name of the Owning Bank |
| getBankOwnerBankFullName | Full version of the name of the Owning Bank |
| getBankOwnerBankCode | The four digit bank code of the Owning Bank [1] |
| getBankProperty | Bank Postal Address: Property (Building) |
| getBankStreet | Bank Postal Address: Street |
| getBankLocality | Bank Postal Address: Locality |
| getBankTown | Bank Postal Address: Town |
| getBankCounty | Bank Postal Address: County (Optional) |
| getBankPostcode | The Royal Mail Postcode for this address |
| getBankSTDCode | STD Code for the Bank Phone number |
| getBankPhone | Phone number |
| getBankFaxSTDCode | STD Code for the Bank Fax Number |
| getBankFax | Fax number (where held) |
| getBankCountryIndicator | Returns ‘U’ if the record is on the BACS system, or ‘I’ if the record is on IPSO. |
| getBankSTDCode2 | STD Code for a secondary Bank Phone number |
| getBankPhone2 | Secondary Phone number (where held) |
| getBankList | Returns a formatted line for list insertion containing elements of the Bank record. Useful when displaying a list of branch results for the user to choose from. |
| BACS Related Fields (Not applicable to IPSO Records) | |
| getBACSStatus | Indicates the BACS Clearing Status [4] |
| getBACSLastChange | Date on which BACS data was last amended |
| getBACSClosedClearing | Indicates the date the branch is closed in BACS clearing if applicable. |
| getBACSRedirectedFromFlag | Set to R if other branches are redirected to this sort code. |
| getBACSRedirectedToSortCode | This specifies the sort code to which BACS should redirect payments addressed to this sort code if applicable. |
| getBACSSettlementBankCode | BACS Bank Code of the bank that will settle payments for this branch. |
| getBACSSettlementBankShortName | Short form name of the settlement bank |
| getBACSSettlementBankFullName | Full form name of the settlement bank |
| getBACSSettlementBankSection | Numeric data required for BACS to perform its settlement. |
| getBACSSettlementBankSubSection | Numeric data required for BACS to perform its settlement. |
| getBACSHandlingBankCode | BACS Bank Code of the member that will take BACS output from this branch. |
| getBACSHandlingBankShortName | Short form name of the handling bank |
| getBACSHandlingBankFullName | Full form name of the handling bank |
| getBACSHandlingBankStream | Numeric code defining the stream of output within the Handling Bank that will be used or payments to this branch. |
| getBACSAccountNumbered | Set to 1 if bank has transferrable account numbers |
| getBACSDDIVoucher | Set to 1 if Paper Vouchers have to be printed for Direct Debit Instructions. |
| getBACSDirectDebits | Set to 1 if branch accepts Direct Debits |
| getBACSBankGiroCredits | Set to 1 if branch accepts Bank Giro Credits |
| getBACSBuildingSocietyCredits | Set to 1 if branch accepts Building Society Credits. |
| getBACSDividendInterestPayments | Set to 1 if branch accepts Dividend Interest Payments. |
| getBACSDirectDebitInstructions | Set to 1 if branch accepts Direct Debit Instructions. |
| getBACSUnpaidChequeClaims | Set to 1 if branch accepts Unpaid Cheque Claims. |
| CHAPS Related Fields (Not applicable to IPSO Records) | |
| getCHAPSPStatus | Indicates the CHAPS Sterling clearing Status [5] |
| getCHAPSPStatusDescription | Provides a description for the status [5] |
| getCHAPSPLastChange | Date on which CHAPS Sterling data was last amended |
| getCHAPSPClosedClearing | Indicates the date the branch is closed in CHAPS Sterling clearing if applicable. |
| getCHAPSPSettlementBankCode | CHAPS ID of the bank that will settle payments for this branch, |
| getCHAPSPSettlementBankShortName | Short form of the name of the settlement bank |
| getCHAPSPSettlementBankFullName | Full form of the name of the settlement bank |
| C&CCC Related Fields (Not applicable to IPSO Records) | |
| getCCCCStatus | Indicates the C&CCC clearing Status [6] |
| getCCCCLastChange | Date on which C&CCC data was last amended |
| getCCCCClosedClearing | Indicates the date the branch is closed in C&CCC clearing if applicable. |
| getCCCCSettlementBankCode | BACS generated code of the bank that will settle payments for this branch. |
| getCCCCSettlement | BankShortName Short form of the name of the settlement bank |
| getCCCCSettlement | BankFullName Full form of the name of the settlement bank |
| getCCCCDebitAgencySortCode | When the Status field is set to ‘D’ this specifies where cheque clearing is handled for this branch. |
| getCCCCReturnIndicator | Set if this is the branch that other banks should return paper to. It will only be set for a sort code of a Member. |
| getCCCCGBNIIndicator | Set if this is the branch that other banks should return paper to. It will only be set for a sort code of a Member. |
| FPS Related Fields (Not applicable to IPSO Records) | |
| getFPSStatus | Indicates the FPS clearing Status [7] |
| getFPSLastChange | Date on which FPS data was last amended |
| getFPSClosedClearing | Indicates the date the branch is closed in FPS clearing if applicable. |
| getFPSRedirectedFromFlag | Set to R if other branches are redirected to this sort code. |
| getFPSRedirectedToSortCode | This specifies the sort code to which FPS should redirect payments addressed to this sort code if applicable. |
| getFPSSettlementBankConnection | Two digit connectivity code (will be 01 FPS Member) |
| getFPSSettlementBankCode | Bank Code of the bank that will settle payments for this branch. |
| getFPSSettlementBankShortName | Short form name of the settlement bank |
| getFPSSettlementBankFullName | Full form name of the settlement bank |
| getFPSHandlingBankConnection | Two digit connectivity code |
| getFPSHandlingBankCode | Bank Code of the bank that will handle payments for this branch. |
| getFPSHandlingBankShortName | Short form name of the handling bank |
| getFPSHandlingBankFullName | Full form name of the handling bank |
| getFPSAccountNumberedFlag | Set to 1 if bank has transferrable account numbers |
| getFPSAgencyType | If getFPSStatus is ‘A’ this will be set to either ‘D’ for a direct agency or ‘I’ for an indirect agency. |
Notes:
Note, that you should only accept account numbers validated on the Irish system if you can clear through both the Irish (IPSO) system as well as the UK (BACS) system.
We serve thousands of organisations and a network of hundreds of partners across multiple industry sectors, enabling them to have full confidence in their contact data.