View Source QRNBU.Versions.V003 (NBU payment QR v0.3.3)

NBU QR Code Version 003 structure with validation and encoding.

V003 is the extended Base64URL format with 17 fields including category purpose, field lock, and invoice timestamps.

Fields

Required Fields

:recipient - Name of the recipient (validated by RecipientValidator)
:iban - Bank account IBAN (validated by IBANValidator)
:recipient_code - Recipient's identification code (validated by RecipientCodeValidator)
:purpose - Payment purpose description (validated by PurposeValidator)

Optional Fields

:amount - Payment amount as Decimal (validated by AmountValidator)
:reference - Payment reference number (validated by ReferenceValidator)
:unique_recipient_id - Unique recipient identifier (validated by UniqueRecipientIDValidator)
:category_purpose - Categorized purpose of payment (validated by CategoryPurposeValidator)
:display - Display text for the QR code (validated by DisplayValidator)
:field_lock - Field edit control bitmap as integer 0x0000-0xFFFF (validated by FieldLockValidator)
:invoice_validity - Invoice expiration datetime (validated by InvoiceValidityValidator)
:invoice_creation - Invoice creation datetime (validated by InvoiceCreationValidator)
:digital_signature - Digital signature string (validated by DigitalSignatureValidator)
:function - Payment function code: :uct, :ict, or :xct (default: :uct)
:encoding - Character encoding: :utf8 or :cp1251 (default: :utf8)

Examples

iex> QRNBU.Versions.V003.new(%{
...>   recipient: "ТОВ Компанія",
...>   iban: "UA213223130000026007233566001",
...>   recipient_code: "12345678",
...>   purpose: "Оплата товарів"
...> })
{:ok, %QRNBU.Versions.V003{...}}

iex> QRNBU.Versions.V003.new(%{
...>   recipient: "ТОВ Компанія",
...>   iban: "UA213223130000026007233566001",
...>   amount: Decimal.new("100.50"),
...>   recipient_code: "12345678",
...>   purpose: "Оплата товарів",
...>   category_purpose: "Товари",
...>   field_lock: 0x1234,
...>   invoice_validity: ~N[2025-12-31 23:59:59],
...>   invoice_creation: ~N[2025-01-08 10:30:00]
...> })
{:ok, %QRNBU.Versions.V003{...}}

Summary

Types

t()

Functions

encode(v003)

Encodes a V003 structure into the NBU QR code data string.

new(attrs)

Creates a new V003 QR code structure with validation.

Types

t()

@type t() :: %QRNBU.Versions.V003{
  amount: Decimal.t() | nil,
  category_purpose: String.t() | nil,
  digital_signature: String.t() | nil,
  display: String.t() | nil,
  encoding: :utf8 | :cp1251,
  field_lock: non_neg_integer() | nil,
  function: :uct | :ict | :xct,
  iban: String.t(),
  invoice_creation: NaiveDateTime.t() | nil,
  invoice_validity: NaiveDateTime.t() | nil,
  purpose: String.t(),
  recipient: String.t(),
  recipient_code: String.t(),
  reference: String.t() | nil,
  unique_recipient_id: String.t() | nil
}

Functions

encode(v003)

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

Encodes a V003 structure into the NBU QR code data string.

Returns the Base64URL encoded format with https://qr.bank.gov.ua/ prefix.

Parameters

v003 - V003 structure to encode

Returns

{:ok, String.t()} - Encoded QR data string
{:error, String.t()} - Encoding error

Examples

iex> {:ok, v003} = QRNBU.Versions.V003.new(%{...})
iex> QRNBU.Versions.V003.encode(v003)
{:ok, "https://qr.bank.gov.ua/MQpVQ1QKVUFICgo..."}

new(attrs)

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

Creates a new V003 QR code structure with validation.

Parameters

attrs - Map with required and optional fields

Returns

{:ok, %QRNBU.Versions.V003{}} - Valid V003 structure
{:error, String.t()} - Validation error message

Examples

iex> QRNBU.Versions.V003.new(%{
...>   recipient: "ТОВ Компанія",
...>   iban: "UA213223130000026007233566001",
...>   recipient_code: "12345678",
...>   purpose: "Оплата товарів"
...> })
{:ok, %QRNBU.Versions.V003{}}

iex> QRNBU.Versions.V003.new(%{
...>   recipient: "",
...>   iban: "invalid",
...>   recipient_code: "123",
...>   purpose: ""
...> })
{:error, "Recipient name is required"}