SEPA · Bank participation · API responses

Check a bank's SEPA participation with the IBAN-Test API

Use an IBAN validation response to inspect a bank's participation in SEPA Direct Debit Core, Direct Debit B2B, Credit Transfer and Instant Credit Transfer. Read each scheme separately and preserve the distinction between confirmed and unknown.

This guide explains the response fields and includes a Python example for inspecting either a live response or a saved JSON file. It checks bank participation, not whether a particular account can execute a payment.

What the four fields mean

The IBAN-Test API checks participation against the European Payments Council's participant registers. The schemes describe different payment services; confirmation for one does not establish participation in the others. See the EPC participant registers for the underlying scheme lists.

1. Validate the IBAN

Use the normal IBAN-validation endpoint. There is no separate SEPA call to add to this workflow:

POST https://www.iban-test.eu/api/v2/iban/validate
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{"iban":"DE89 3704 0044 0532 0130 00"}

The IBAN above is an example, not a payment instruction. Check the HTTP status and validation result first. A usable valid-IBAN response has code: 2100 and error: false. The SEPA fields then appear under details.sepa, when supplied by the API. The separate BIC-validation and German bank-account-validation endpoints do not return these SEPA fields.

2. Keep “confirmed” and “unknown” distinct

Each scheme contains status and reason:

• confirmed: the API found an unambiguous current register match for that scheme.
• unknown: the API could not confirm participation. This is not a statement that the bank does not support the scheme.

The following excerpt is deliberately illustrative. It shows why four separate columns are more useful than a single “SEPA supported” flag:

{
  "sddCore": {"status": "confirmed", "reason": "matched"},
  "sddB2b":  {"status": "unknown",   "reason": "no_match"},
  "sct":     {"status": "confirmed", "reason": "matched"},
  "sctInst": {"status": "unknown",   "reason": "stale_data"}
}

In this fixture, Core and SCT are confirmed. B2B remains unconfirmed and the instant-transfer result depends on outdated data. None of those unknown values changes the original IBAN-validation result.

3. Run the example offline

Extract the download and run:

python3 sepa_check.py --response example-response.json

This sends no network request and needs no token. The program prints a JSON summary with iban_status, bank information and four separate scheme results. source: "offline_file" identifies the input source. The supplied file names a fictional bank and must not be used as evidence about any real institution.

If a saved response lacks the SEPA fields, the helper returns unknown with missing_response_data. That reason is a local marker added by the example, not an IBAN-Test API reason code. Unexpected status values or malformed scheme objects stop the program instead of being silently accepted.

4. Check a live response

python3 sepa_check.py --iban "DE89 3704 0044 0532 0130 00"

The program prompts for your token without echoing it. Alternatively, provide IBAN_TEST_API_TOKEN through your execution environment's secret configuration. A live run makes one IBAN-validation request and counts against your API quota. The helper uses a timeout, verifies TLS, does not follow redirects and does not automatically retry.

Use py -3 instead of python3 on Windows when appropriate. The command exits with code 0 for a valid IBAN, even when one or more schemes are unknown; 2 for a business-invalid IBAN; and 1 for an operational or input error. Inspect the scheme fields separately rather than treating exit code 0 as “all schemes confirmed”.

Understand an unknown result

Store the status and reason together. In a user interface, display “Participation could not be confirmed” for unknown results and route cases according to your application's review process. Do not automatically label the IBAN invalid or claim the bank cannot handle that payment type.

Separate API failures from participation results

An HTTP authentication error, exhausted quota or server failure is not an unknown bank-participation result. The example stops before interpreting schemes when the request itself fails. Likewise, a checksum-invalid IBAN produces no scheme decision. This avoids turning an unavailable service into a misleading bank capability statement.

Run python3 -m unittest -v to execute the bundled offline tests. For a larger input list, start with the CSV and Python guide and retain a separate status/reason pair for each scheme when extending its output.

Technical reference: IBAN-Test API documentation and SEPA reason codes. An IBAN check and confirmed bank participation do not verify account ownership, account existence, a mandate, available funds or payment success.

Create an API account Compare API quotas