DE ♦ EN

IBAN-BIC.com (Theano GmbH)  » Web Service  » Documentation  » Documentation: calculate_iban

Forgot password?

Contact
us

New customer? Register

The calculate_iban Function

Example:
calculate_iban("DE", "50010517", "0648479930", "username", "password, "", 0)

Purpose: Calculates an IBAN for the given domestic account number.

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

Input Parameters:

  • country: xsd:string
    The two letter ISO country code.
  • bankcode: xsd:string
    Domestic sort code/bank code/BC number (Switzerland).
    Note: For certain countries the 'bankcode' field is blank. The complete account number including the bank code should then be passed with the 'account' parameter. See examples for all countries.
  • account: xsd:string
    The domestic account number.
  • user: xsd:string
    The user name with which you log in to iban-bic.com.
  • password: xsd:string
    Your password.
  • bic: xsd:string
    The BIC (or at least a sufficiently long prefix).
    Note: Parameter relevant only for GB, IE, NL where the BIC is partially coded in to the IBAN; parameter ignored for all other countries. If this field is left blank for GB, IE, or NL, the server will attempt to fill in this field, however this data may not always be available or reliable.
  • legacy_mode: xsd:int
    (CH only) If set to 1 for Switzerland, the calculator calculates the IBAN itself, instead of using the external Java program provided by Swiss Interbank Clearing. The external Java program validates account numbers, but is slower and requires all characters to be entered correctly (such as dots, hyphens etc.). The legacy mode internal calculation is faster, but does not validate account numbers and is more likely to produce incorrect results.

Output Fields:

tns:IBANCalcResStruct with the following fields:

  • result: 'passed' if all possible validations proceeded without error. Otherwise, 'failed'.
  • 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 = Account number has incorrect length.
      • 1024 = Bank code has incorrect length.
      • 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.
  • iban: the calculated IBAN.
    Note: if the domestic account number/bank code had the correct length, an IBAN may be provided even if the account number validation fails.
  • checks: an array of the checks performed (can contain elements such as 'length', 'bank_code', 'account_number').
  • 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.
  • 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-Nummer for Switzerland. There are separate SOAP functions provided for obtaining Dutch BICs and Swiss BC numbers.
  • alternative_bank_code: A handful of banks embed a bank code in the IBAN different from the bank code communicated to clients. If this is the case, this field contains the alternative possibility. Otherwise, it is empty.
  • 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.
  • 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.
  • account_number: Domestic account number.
  • alternative_account_number: (DE only) Occasionally, a subaccount number must be appended to a German account number before it is embedded in an IBAN. If this is the case, the extended account number appears in this field.
  • 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', 'failed for bank code' or 'failed for account number' - shows if the account number/bank code had the correct length for the given country.
  • account_check: (not provided for all countries) 'passed' or 'failed'; for DE additional possible value of 'passed after correction' - in that case see 'alternative_account_number'. The field 'account_check' 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'); if an alternative bank code may be necessary for the IBAN, this information is added after the word 'passed' in this field.
  • bic_plausibility_check: (NL only). Checks frequency that account numbers of a given bank have the given prefix. Since this gives no guarantee, this check is ignored for the overall pass/fail decision reported in the result field. The frequency can help determine the likelihood that the correct BIC was provided.
  • data_age: (not provided for all countries.) Age of BIC and other bank data. (undefined for data harvested from the web). 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 with a subscription which includes an unlimited number of calculations.