View Source QRNBU.Validators.IBAN (NBU payment QR v0.3.3)

Validates Ukrainian IBAN (International Bank Account Number) using the iban_ex library.

This validator wraps the iban_ex library (developed by the same author) to provide NBU-specific validation and extraction functions for Ukrainian IBANs.

Specification

Ukrainian IBAN format (29 characters):

Positions 1-2: Country code "UA"
Positions 3-4: Check digits (calculated using MOD-97 algorithm)
Positions 5-10: Bank code (MFO - 6 digits)
Positions 11-29: Account number (19 characters)

Validation Rules

Must be exactly 29 characters
Must start with "UA"
Must contain only alphanumeric characters
Check digits must be valid (MOD-97 algorithm per ISO 13616)

Examples

iex> QRNBU.Validators.IBAN.validate("UA303348510000026206114040874")
{:ok, "UA303348510000026206114040874"}

iex> QRNBU.Validators.IBAN.validate("ua303348510000026206114040874")
{:ok, "UA303348510000026206114040874"}  # Normalized to uppercase

iex> QRNBU.Validators.IBAN.validate("PL60102010260000042270201111")
{:error, "IBAN must be for Ukraine (country code UA)"}

iex> QRNBU.Validators.IBAN.validate("UA30334851")
{:error, "IBAN must be exactly 29 characters for Ukraine"}

References

NBU Resolution No. 97, August 19, 2025
ISO 13616:2020 IBAN standard
Uses iban_ex library: https://hex.pm/packages/iban_ex

Summary

Functions

extract_account_number(iban)

Validates and extracts account number from Ukrainian IBAN.

extract_bank_code(iban)

Validates and extracts bank code (MFO) from Ukrainian IBAN.

parse(iban)

Parses a Ukrainian IBAN into its components using iban_ex.

validate(iban)

Validates Ukrainian IBAN format and checksum using iban_ex library.

Functions

extract_account_number(iban)

@spec extract_account_number(String.t()) :: {:ok, String.t()} | {:error, String.t()}

Validates and extracts account number from Ukrainian IBAN.

Uses iban_ex parsing to extract the 19-character account number.

Examples

iex> QRNBU.Validators.IBAN.extract_account_number("UA303348510000026206114040874")
{:ok, "0000026206114040874"}

extract_bank_code(iban)

@spec extract_bank_code(String.t()) :: {:ok, String.t()} | {:error, String.t()}

Validates and extracts bank code (MFO) from Ukrainian IBAN.

Uses iban_ex parsing to extract the 6-digit bank identifier code.

Examples

iex> QRNBU.Validators.IBAN.extract_bank_code("UA303348510000026206114040874")
{:ok, "334851"}

parse(iban)

@spec parse(String.t()) :: {:ok, map()} | {:error, String.t()}

Parses a Ukrainian IBAN into its components using iban_ex.

Returns a map with all IBAN components: iban, country_code, check_digits, bank_code, and account_number.

Examples

iex> QRNBU.Validators.IBAN.parse("UA303348510000026206114040874")
{:ok, %{
  iban: "UA303348510000026206114040874",
  country_code: "UA",
  check_digits: "30",
  bank_code: "334851",
  account_number: "0000026206114040874"
}}

validate(iban)

@spec validate(String.t()) :: {:ok, String.t()} | {:error, String.t()}

Validates Ukrainian IBAN format and checksum using iban_ex library.

The IBAN is automatically normalized (trimmed and uppercased) before validation.

Returns {:ok, normalized_iban} if valid, {:error, reason} otherwise.