API Documentation

Only accepts GET.

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

Input:

• country: The two letter ISO country code.
• bankcode: 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: The domestic account number.
• bic: (optional) 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 parameter 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.

Output:

• 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.
• 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.

• ibanrueck_return_code: reserved for future use.

• 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 who pay their calculations retroactively.

A dummy function for calculating an IBAN. Will always calculate the same IBAN, no matter what account data you send. Calling this function is free.

Purpose: Full-text search of banks in supported countries. The restriction to a given country is optional - if the second parameter is the empty string (or an asteristk, *, in the URL), the function searches all supported countries. Likewise optional are the bank code and search term parameters.

Examples:

• https://sepatools.eu/find_bank/Deutsche/DE/100/23.json
  find_bank("Deutsche", "DE", "100", "23", "username", "password")
  finds banks in the country "DE" (Germany) whose names contain "Deutsche", and whose bank codes contain the number sequence "100", returning at most 23 entries.

• https://sepatools.eu/find_bank/*/*/DEGUDEFF/20.json
  find banks whose BIC contains "DEGUDEFF" and return at most 20 entries.

Input Parameters:

search_terms:
Search terms. If one or more whole words are given, then the search is fast and encompasses bank names and addresses. If partial words are entered, then the search takes longer and only searches bank names. This parameter can also be left empty by entering "" (or "*" in the URL). In this case, the search should be limited using some other field, for example the bank code field (see below).

country:
A two-letter ISO country code. This field can also be left blank (or set to "*" in the URL). If a country is specified, the search will be limited to that country. Otherwise, all supported countries will be searched.
bankcode_or_bic:
(Optional.) String of characters, or empty ("" or "*"). If a non-empty string is entered, the search will return banks whose bank codes contain the search string.
max_items:
Maximal number of search results.

Output Fields:

result: Empty if no error has occured. Otherwise, an error message.
banks: A list of banks. Information about each bank is delivered with the following data structure:
name: Bank name.
bic: BIC.
bankcode: Domestic bank code.
address: Bank address, if known.
in_scl_directory:"yes" or "no".
"sct":"yes" if in_scl_directory is "yes" and a SEPA Credit Transfer is supported.
"sdd":"yes" if in_scl_directory is "yes" and a SEPA Direct Debit is supported.
"b2b":"yes" if in_scl_directory is "yes" and a B2B SEPA transaction is supported.

Example:
Step 1: .../get_swiss_banks/list.json
Returns a list of all Swiss banks, however without BC-numbers.

Step 2: .../get_swiss_banks/AEK+BANK+1826+Genossenschaft.json

Delivers a list of all BC-Numbers of AEK BANK 1826 Genossenschaft. The bank name entered must exactly match a bank name delivered in step one.

Purpose: Many account holders are not aware of their BC-Numbers. This function can be used to implement choice menu (Step 1: Choose a bank; Step 2: Select a possible BC-number).

Input Parameters:

• bank: Should contain "list" when calling up the list of all Swiss banks. In a second step, call the function with the selected bank name in this parameter to get a list of all of the selected bank's BC-numbers.

Output Fields:

• result: Empty if no error has occured. Otherwise, an error message.
• banks: A list of banks. Information about each bank is delivered with the following data structure:

name: Bank name.
bic: If the function was called with a non-empty bank name field, this field contains the BIC code. Otherwise, empty.
bankcode: If the function was called for a particular bank (i.e. the first parameter was non-empty), this field contains the BC-number(s). Otherwise, empty.
address: Bank address, if known.
balance: Your iban-bic.com account balance (number of remaining transactions).

Only accepts GET.

Purpose: Creates a QR code which, when scanned, can be used to automatically populate a SEPA transfer form.

Input:

• recipient
• iban
• amount (in EUR)
• memo: remittance information
• label (optional): printed in human-readable form underneath the QR Code. If label is left empty, the bitmap will be square; otherwise, a bit of extra space is added at the bottom for printing the given text.
• bic: (optional) If you leave the BIC code empty, the server will attempt to fill it automatically using the IBAN; if you specify a BIC code, the specified BIC code is used.

Output:

• image: the QR code bitmap as base64-encoded string. It can be used inside the HTML "img" tag as is (e.g., ), or you can base64-decode the part after "data:image/png;base64," and write the result into a PNG file
• md5sum: the result of the Linux command "md5sum" when applied to the PNG file.
• result: 'passed' if the IBAN is successfully validated and no other error has occured. Otherwise, this field contains an error message.
• balance: the 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.

Input: an IBAN containing one or two underscores (_) as place holders.

Output: all possible, formally correct IBANs which fit the given pattern. For example, for "DE12500_0_170648489890", this function delivers the information that only one formally correct IBAN, "DE12500105170648489890", fits the given pattern.

Example:
supported_countries("IBAN AND some_BICs AND (account_validated OR bankcode_validated)", "DE", "benutzername", "passwort") returns, in German ("DE"), a list of countries which are supported by the interface such that IBANs can be calculated, BICs (possible more than one BIC candidate) are returned for those bank codes for which a BIC is defined, and the domestic account number or the bank code are validated (or both).

Purpose: Returns countries which are currently supported by the interface, and what their names are in a given language. You may specify what conditions must be met for a country to be considered "supported".

Input Parameters:

supported_condition: 
Your definition of "supported", that is, a condition which countries must meet to be listed. You may use the following keywords, and you can combine them with parentheses, AND, and OR:
    IBAN: IBANs can be calculatede for this country.
    unique_BIC: returns a unique BIC for any bank code for which a BIC is defined.
    some_BICs: returns one or more BIC candidates for any bank code for which a BIC is defined. If more than one BIC candidate is returned, you need to find out yourself which one to use. However, the most likely one will be listed first. Countries which fulfil not just the condition some_BICs but even the condition unique_BIC are considered to also fulfil some_BICs.
    name_based_BICs: like for "some_BICs", none, one, or several BIC codes could be returned. However, unlike "some_BICs", these BIC candidates are not taken directly from a directory that maps bank codes to BICs, but they have been determined by joining two directories based on the bank names. This makes the BIC information slightly less reliable. Countries which fulfil "some_BICs" are also considered to fulfil "name_based_BICs". That is, if you require that at least "name_based_BICs" is fulfilled, you will not exclude the better-supported countries fulfilling "some_BICs" or "unique_BIC".
    account_validated: for all domestic account numbers which contain a check sum, this check sum is validated.
    bankcode_validated: the bank code is validated by looking it up in a directory of bank codes.
If you leave the parameter "supported_condition" empty, the default condition "IBAN AND some_BICs AND (account_validated OR bankcode_validated)" is used.

language: 
The two-letter country code for the desired language (for the list of country names); instead of the two-letter code, you may also use a number from this list:
    English = 0 or EN
    German = 1 or DE
    Dutch = 3 or NL
    Polish = 4 or PL
    French = 5 or FR
    Spanish = 6 or ES
    Italian = 7 or IT
    Turkish = 8 or TR
    Croatian = 9 or HR
    Serbian = 10 or RS

Only accepts GET.

Validates the given IBAN. Not only the IBAN checksum but also the contained domestic account number and bank code are checked for most countries. For details on the supported countries, click here.
The return values (see below) include a list of BIC candidates. If you would like to validate whether a given BIC belongs to a given IBAN, please pass only an IBAN but not the BIC as a parameter and then check whether your given BIC is among the returned candidates. For a less stringent check, you may also pass your BIC code using the optional second parameter. If you do so, that BIC will only be checked for existence in the SCL Reachability Directory - its connection to the given IBAN will not be checked.

Input:

• iban: the IBAN to validate.
• bic: optional: a BIC code which, if supplied, is checked for existence. Please keep in mind that even if you do not supply a BIC, a list of possible BIC candidates which are linked to the given IBAN will be returned.

Output:

• iban: the IBAN that was validated.
• result: 'passed' or 'failed' - for a valid or invalid IBAN - or 'BIC not found' in case a non-existing BIC code was supplied as the second parameter.
• return_code: a condensed representation of the results of various checks. Not all checks have necessarily been done (see the other fields to find out). The condensed representation is a number which is 0 if all supported checks were done and passed. Otherwise, it is the sum of one or more of the following numbers: 1=automatically appended a subaccount number; 2=account number does not contain a checksum; 4=did not check the checksum; 8=did not check the bank code; 32=warning: a subaccount number might need to be appended, but you need to check if this is really the case; 128=checksum error in account number; 256=bank code not found in directory; 512=wrong length for IBAN; 1024=wrong length for bank code; 2048=IBAN checksum error (digits 3 and 4); 4096=missing input data (such as country code); 8192=this country is not (yet?) supported.
  This condensed return code can be used for a simple check such as: if the sum is less than 32, the result can be assumed to be correct; if it is in the range from 32 to 127, it might be correct but should be checked; if it is 128 or higher, there seems to be a more serious error. There is one exception to this rule: if it is 65536, this means that the return code is not set at all. This should not happen - please notify us if it does.
• 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 are associated with the given national bank code. May be empty or may contain one or more elements. Each element contains the attributes bic, wwwcount, sampleurl, zip code, and city. If a wwwcount greater than zero is given, the BIC was harvested from the Web (and found on as many pages as indicated by wwwcount, for example at the URL given by sampleurl). If wwwcount is zero, 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. 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. Part of the BIC for NL (where no bank code exists).
• bank: bank name, if known
• bank_address: some address data, if known
• bank_url: URL of website, if known
• branch: branch name, if known
• branch_code: branch code, if known
• in_scl_directory: if at least one BIC is returned, 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: the national bank account number
• account_validation_method: name of the validation algorithm for the national account number
• account_validation: for German or Swiss account numbers, an explanation (in German)
• length_check: 'passed' or 'failed' - for the right number of characters for the given country
• account_check (not provided for every country): 'passed' or 'failed' (checksum validation; if the algorithm is unknown, or if there is no checksum, the result is 'passed' or empty).
• bank_code_check (not provided for every country): lookup of national bank code was successful ('passed') or not ('failed')
• iban_checksum_check: 'passed' or 'failed' (correctness of the two digits right after the country code in the IBAN)
• data_age (not given for all countries): age of the BIC and other bank-related data (not defined 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: an explanation of the IBANformat string, for example: 'B = sort code (BLZ), C = account No.'
• balance: the 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.

A dummy function which will accept any IBAN and tell you that it's valid. Calling this function is free.