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

Validates Ukrainian Tax Identification Numbers using the ukraine_tax_id library.

This validator wraps the ukraine_tax_id library (developed by the same author) to provide validation for both EDRPOU (legal entities) and ITIN (individuals) tax IDs.

Tax ID Types

EDRPOU: 8-digit code for legal entities (companies, organizations)
ITIN: 10-digit code for individuals (Individual Taxpayer Identification Number)

Validation Rules

EDRPOU: Exactly 8 digits with checksum validation
ITIN: Exactly 10 digits with checksum validation, includes birth date and gender
Only numeric characters allowed
Checksum must be valid per Ukrainian tax authority algorithms

Examples

iex> QRNBU.Validators.TaxID.validate("12345678")
{:ok, "12345678", :edrpou}

iex> QRNBU.Validators.TaxID.validate("1234567890")
{:ok, "1234567890", :itin}

iex> QRNBU.Validators.TaxID.validate("123")
{:error, "Invalid tax ID length"}

iex> QRNBU.Validators.TaxID.validate("1234567X")
{:error, "Tax ID must contain only digits"}

References

Ukrainian State Tax Service regulations
Uses ukraine_tax_id library: https://hex.pm/packages/ukraine_tax_id

Summary

Functions

determine_type(tax_id)

Determines the type of tax ID without full validation.

parse_itin(itin)

Parses an ITIN to extract birth date and gender information.

validate(tax_id)

Validates a Ukrainian tax identification number (EDRPOU or ITIN).

validate_edrpou(edrpou)

Validates specifically an EDRPOU (8-digit legal entity code).

validate_itin(itin)

Validates specifically an ITIN (10-digit individual taxpayer code).

Functions

determine_type(tax_id)

@spec determine_type(String.t()) :: :edrpou | :itin | :unknown

Determines the type of tax ID without full validation.

Returns :edrpou, :itin, or :unknown.

parse_itin(itin)

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

Parses an ITIN to extract birth date and gender information.

Returns {:ok, %{birth_date: Date.t(), gender: :male | :female}} or {:error, reason}.

Examples

iex> QRNBU.Validators.TaxID.parse_itin("3456789012")
{:ok, %{birth_date: ~D[2003-12-31], gender: :female}}

validate(tax_id)

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

Validates a Ukrainian tax identification number (EDRPOU or ITIN).

Automatically detects the type based on length:

8 digits → EDRPOU (legal entity)
10 digits → ITIN (individual)

Returns {:ok, normalized_tax_id, type} where type is :edrpou or :itin, or {:error, reason} if validation fails.

validate_edrpou(edrpou)

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

Validates specifically an EDRPOU (8-digit legal entity code).

Returns {:ok, edrpou} or {:error, reason}.

validate_itin(itin)

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

Validates specifically an ITIN (10-digit individual taxpayer code).

Returns {:ok, itin} or {:error, reason}.