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

Validates payment purpose/description according to NBU QR code specifications.

Rules

V001/V002: Maximum 140 characters
V003: Maximum 280 characters
Cannot be empty or contain only whitespace
Should contain valid printable characters

Examples

iex> QRNBU.Validators.Purpose.validate("Оплата за товари згідно рахунку №123", version: 2)
{:ok, "Оплата за товари згідно рахунку №123"}

iex> QRNBU.Validators.Purpose.validate("Payment for services rendered under contract", version: 3)
{:ok, "Payment for services rendered under contract"}

iex> QRNBU.Validators.Purpose.validate("", version: 2)
{:error, "Purpose cannot be empty"}

iex> long_purpose = String.duplicate("Х", 141)
iex> QRNBU.Validators.Purpose.validate(long_purpose, version: 2)
{:error, "Purpose exceeds maximum length of 140 characters for version 2"}

Summary

Types

options()

version()

Functions

max_length(version)

Gets the maximum length for purpose based on version.

normalize(purpose)

Normalizes purpose by trimming and removing extra whitespace.

truncate(purpose, opts \\ [])

Truncates purpose to maximum length for the specified version.

validate(purpose, opts \\ [])

Validates payment purpose/description for NBU QR code.

validate_with_suggestion(purpose, opts \\ [])

Validates and suggests if a purpose might need a category purpose code (V003).

Types

options()

@type options() :: [{:version, version()}]

version()

@type version() :: 1 | 2 | 3

Functions

max_length(version)

@spec max_length(version()) :: pos_integer()

Gets the maximum length for purpose based on version.

Examples

iex> QRNBU.Validators.Purpose.max_length(1)
140

iex> QRNBU.Validators.Purpose.max_length(2)
140

iex> QRNBU.Validators.Purpose.max_length(3)
280

normalize(purpose)

@spec normalize(String.t()) :: String.t()

Normalizes purpose by trimming and removing extra whitespace.

Examples

iex> QRNBU.Validators.Purpose.normalize("  Payment   for   goods  ")
"Payment for goods"

truncate(purpose, opts \\ [])

@spec truncate(String.t(), options()) :: String.t()

Truncates purpose to maximum length for the specified version.

Useful for gracefully handling slightly too-long input.

Examples

iex> long_purpose = String.duplicate("А", 150)
iex> QRNBU.Validators.Purpose.truncate(long_purpose, version: 2)
String.slice(long_purpose, 0, 139)

iex> QRNBU.Validators.Purpose.truncate("Short purpose", version: 2)
"Short purpose"

validate(purpose, opts \\ [])

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

Validates payment purpose/description for NBU QR code.

Options:

version: QR code version (1, 2, or 3). Defaults to 2.

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

validate_with_suggestion(purpose, opts \\ [])

@spec validate_with_suggestion(String.t(), options()) ::
  {:ok, String.t()} | {:warning, String.t(), String.t()} | {:error, String.t()}

Validates and suggests if a purpose might need a category purpose code (V003).

Returns {:ok, purpose} or {:warning, purpose, suggestion} for V003.