DE ♦ EN

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

Forgot password?

Contact
us

New customer? Register

Convert BBANs (domestic account numbers) to IBANs: https://rest.sepatools.eu/calculate_iban

URL: rest.sepatools.eu/calculate_iban/{country}/{bankcode}/{account}[/{bic}[/{legacy_mode}]]

Example:
https://rest.sepatools.eu/calculate_iban/IE/900017/10027952

Purpose:

  • Converts a given combination of country code, bank code, and account number to an IBAN.
  • Adds information such as BIC code, bank name, bank address, bank URL.

Testing the call mechanism for free: for your first implementation steps, we recommend using the endpoint rest.sepatools.eu/calculate_iban_dummy/IE/900017/10027952, which expects the same parameters, runs on the same servers, uses the same authentication mechanism, and returns the same data structure as validate_iban but is free to call. The dummy endpoint always returns the same data, no matter what parameters are passed, with these exceptions: if you enter the account data for DE, bank code 10077777, account 209299700 or DE, bank code 52051373, account 5120710131 or DE, bank code 52051373, account 5120710132 or AT, bank code 11000, account 237571500, you get the results for the passed parameters even from the dummy endpoint.

Test Data: for testing your client implementation, you might want to use these test data.

Authentication: Basic Authentication using the user name and password you defined when signing up on iban-bic.com.

Supports GET and POST.

Input

Input Parameters:

  • country: The two-letter ISO country code.
  • bankcode: Domestic bank code/sort code (GB, IE)/BC number (Switzerland).
  • account: The domestic account number.
  • bic: The BIC (or at least a sufficiently long prefix).
    This parameter is relevant only for GB, IE, NL where the BIC is partially coded in to the IBAN; the parameter is 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: (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: calculated IBAN and validation results

The following output fields contain the IBAN and validation results:

  • iban: The calculated IBAN.
  • 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.
      • 64 = The bank has published an "IBAN Rule" which states that for this account number/bank code combination, no IBAN should be generated.
      • 128 = Checksum error in account number.
      • 256 = Bankcode not found in directory.
      • 512 = IBAN 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.

  • ibanrueck_return_code: reserved for future use.
  • checks: an array of the checks performed (can contain elements such as 'length', 'bank_code', 'account_number').
  • 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.
  • 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)
  • 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.'

Output: account and bank information (BIC code, bank address, etc.)

The following output fields contain additional information about the calculated IBAN, such as its BIC code and bank data:

  • 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-Number for Switzerland.
    • >
  • 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.
  • 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.
  • 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.
  • data_age: (not provided for all countries.) Age of BIC and other bank data. (undefined for data harvested from the web). Format: yyyymmdd.

Output: your account balance

The following output field contains your user account balance on iban-bic.com:

  • balance: Number of remaining API calls you can do before having to recharge your account. This does not apply to customers who pay their calculations retroactively.