The validate_iban Function

Example:
validate_iban("IE92BOFI90001710027952", "username", "password")

Purpose:

• Validates the given IBAN, including its contained domestic account number and bank code, insofar as possible.
• Adds information such as BIC code, bank name, bank address, bank URL.
• Helps prevent fraud by checking the IBAN against a list of publicly visible IBANs which can be found on the WWW (and might therefore be used by fraudsters instead of their own IBANs) and against a list of IBANs for which a fraud suspicion has been reported.

Test Data: for testing your client implementation, you might want to use these test data (including test data for fraud prevention).

Access: Same user id and password as for premium user log in on iban-bic.com.

Input Parameters:

• iban: xsd:string
  The IBAN to be validated
• user: xsd:string
  The user name with which you log in to iban-bic.com.
• password: xsd:string
  Your password.
• account_holder: xsd:string
  Optional: name of the account holder. If specified, the function will look up if another user has labeled this IBAN/account holder combination as existing and correct.

Output Fields:

tns:IBANValResStruct with the following fields:

• iban: The IBAN that was checked.
• result: 'passed' or 'failed' - for a formally correct or incorrect IBAN
• return_code: a condensed numerical representation of the results of various checks. Not all checks are always carried out.
  Possible values:

  • 0 = all supported checks were done and passed.
  • Otherwise, the sum of one or more of the following numbers:
    
    • 1 = a subaccount number was automatically appended.
    • 2 = Account number does not contain a checksum.
    • 4 = Checksum was not checked.
    • 8 = Bank code was not checked.
    • 32 = Warning: a subaccount number may need to be appended, but the necessity of this could not be automatically verified. Please verify manually.
    • 128 = Checksum error in account number.
    • 256 = Bankcode not found in directory.
    • 512 = IBAN has incorrect length.
    • 1024 = Bank code has incorrect length.
    • 2048 = The IBAN checksum is incorrect (3rd and 4th characters of the IBAN)
    • 4096 = Missing input data (for example, the country code).
    • 8192 = Country not yet supported.

  Interpretation: if the sum is

  • < 32. Result can be assumed correct;
  • 32 ≤ sum ≤ 127. Result might be correct but should be verified;
  • ≥ 128. There may be a more serious error.
  • = 65536. The return code is not set at all, which should not happen - please notify us of this error.

• checks: an array of the checks performed (can contain elements such as 'length', 'bank_code', 'account_number', 'iban_checksum').
• bic_candidates: an array of BICs that can be associated with the given domestic bank code. May be empty or may contain one or more elements. Each BIC element is itself a complex data type that has the attributes 'bic', 'wwwcount', 'sampleurl', and 'city'.
  Interpretation: If
  • wwwcount > 0. The BIC was harvested from the web (and found on as many pages as indicated by 'wwwcount', for example on the page indicated by 'sampleurl').
  • wwwcount = 0. The BIC comes from a national bank or the ECB.
  • If 'city' is given, this also indicates that the BIC comes from a national bank or the ECB.
    Note: The given city does not necessarily reflect the location of the given branch - it can also be the location of the headquarters.

• all_bic_candidates: an array of BIC candidates which includes the BICs listed above, plus possible some more BIC codes which were excluded from the previous array based on some heuristics. Use this array for a somewhat softer check of the validity of a BIC code.
• country: the ISO country code (first two letters of the IBAN)
• bank_code: the domestic bank code, if it exists. Returns first 4 characters of the BIC for NL (where no domestic bank codes exist), or the BC-Number for Switzerland.
• bank: Bank name, if known.
• bank_address: Bank address, if known.
• bank_url: URL of bank website, if known.
• branch: Branch name, if known.
• branch_code: Branch code, if known.
• in_scl_directory: if at least one BIC is returned (that is, if the array bic_candidates, which is mentioned above, contains at least one element), this field is set to 'yes' or 'no', depending on whether the first returned BIC is listed in the German Bundesbank's SCL directory. If no BIC is returned, this field is left blank.
• sct: if in_scl_directory is set to 'yes', this field is set to 'yes' if a SEPA Credit Transfer is supported for the first returned BIC. If no SCT is supported, the field is set to 'no'. If no BIC is returned, the field is left blank.
• sdd: if in_scl_directory is set to 'yes', this field is set to 'yes' if SEPA Direct Debit is supported for the first returned BIC. If no SDD is supported, the field is set to 'no'. If no BIC is returned, the field is left blank.
• cor1: if in_scl_directory is set to 'yes', this field is set to 'yes' if Core 1 Direct Debit is supported for the first returned BIC. If no Core 1 is supported, the field is set to 'no'.
• b2b: if in_scl_directory is set to 'yes', this field is set to 'yes' if SEPA Business to Business is supported for the first returned BIC. If no B2B is supported, the field is set to 'no'. If no BIC is returned, the field is left blank.
• scc: if in_scl_directory is set to 'yes', this field is set to 'yes' if SEPA Card Clearing is supported for the first returned BIC. If no SCC is supported, the field is set to 'no'.
• account_number: Domestic account number.
• account_validation_method: name of the validation algorithm for the domestic account number
• account_validation: (DE and CH only) An explanation of the account number validation (in German)
• length_check:'passed' or 'failed' - shows if the IBAN is of the correct length for the given country.
• account_check: (not provided for all countries) 'passed' or 'failed'. Gives the result of the checksum validation of the account number. If the algorithm is unknown, or if no checksum exists, the result is empty or 'passed'.
• bank_code_check: (not provided for all countries) Directory lookup of domestic bank code was successful ('passed') or not ('failed').
• iban_checksum_check: 'passed' or 'failed'. Correctness of the 3rd and 4th characters of the IBAN, i.e. the IBAN checksum.
• data_age: (not provided for all countries.) Age of BIC and other bank data. (undefined for data harvested from the web). Format: yyyymmdd.
• iban_www_occurrences: the number of times we have encountered this IBAN in our monthly web crawl. If greater than zero, the following 7 fields give more details.
• www_seen_from: the first date when we encountered this IBAN online. This is most likely later than when it actually appeared online.
• www_seen_until: the last date when we encountered this IBAN online. It might or might not be still online.
• iban_url: the most prominent URL where we have found this IBAN. See below for how we assess prominence. If iban_www_occurrences is 1 and iban_url contains "IBAN_BLACKLISTED", the IBAN is not necessarily publicly visible but has been reported as suspicious by an unknown user.
• url_rank: the number of other websites which receive more traffic than the website specified in iban_url.
• url_category: the category of the most prominent website in natural language, if known.
• url_min_depth: the smallest nesting depth of the page where the IBAN was found.
• url_prominence: this field is reserved for a prominence score.
• iban_reported_to_exist: if nonzero: this IBAN was reported by another user to exist and to belong to the account holder you specified.
• iban_last_reported: the latest date when this IBAN was reported to exist, in the format YYYYMMDD.
• IBANformat: A string describing the IBAN format for the given country, for example: 'DEkk BBBB BBBB CCCC CCCC CC'.
• formatcomment: Key to the IBANformat string, for example: 'B = sort code (BLZ), C = account No.'
• balance: Number of remaining calculations you can do before having to recharge your account. This does not apply to customers who pay their calculations retroactively.