Node Functions

buildBarcodePayload

Function

buildBarcodePayload(__namedParameters: BarcodeParts, ...legacyOptions: never[]) => string

Build the current barcode payload for the PDF metadata copy: 2|<verifiablReference>|<BASE32 ciphertext>.

Parameter	Type	Description
__namedParameters	BarcodeParts
legacyOptions	never[]

Returns: string

buildScanUrl

Function

buildScanUrl(parts: BarcodeParts, options: ScanUrlOptions) => string

Build the URL encoded into Verifiabl QR codes:

https://v.verifiabl.io/v/<verifiablReference>#2.<BASE32 ciphertext>

The scan URL sends scanners to Verifiabl instead of exposing raw ciphertext in a phone camera preview.

The ciphertext rides in the fragment, which no client transmits to a server, so it cannot reach a request log at Verifiabl or at any intermediary. Every character stays inside the URI-safe set (base64url plus .), which is what keeps scanners treating this as a URL and offering tap-to-open rather than showing it as plain text.

Parameter	Type	Description
parts	BarcodeParts
options	ScanUrlOptions

Returns: string

createBarcodePng

Function

createBarcodePng(parts: BarcodeParts, options: BarcodePngOptions, pixelWidth?: number) => Promise<BarcodePngResult>

Render the branded Verifiabl QR code as a PNG.

The PNG is composited deterministically from a pre-rasterised frame plus exact pixel-aligned QR modules - no vector rasteriser is involved, so there is no native dependency, and the same record produces the byte-identical raster in every Verifiabl SDK.

Because the frame is pre-rasterised, PNG output exists only at the widths in SUPPORTED_PNG_PIXEL_WIDTHS for the vertical layout and SUPPORTED_HORIZONTAL_PNG_PIXEL_WIDTHS for the horizontal layout. Both width sets render the QR code at the same sizes. If you need a different size, prefer createBarcodeSvg (continuously scalable), or scale at placement time: PDF toolchains set the physical size independently of the pixel size.

Rejects with QrCapacityError when the encrypted PII is too long to encode.

Parameter	Type	Description
parts	BarcodeParts
options	BarcodePngOptions
pixelWidth	number	Output bitmap width in pixels (default: 720 for the vertical layout, 1410 for the horizontal layout).

Returns: Promise<BarcodePngResult>

createBarcodeSvg

Function

createBarcodeSvg(parts: BarcodeParts, options: BarcodeSvgOptions) => BarcodeSvgResult

Render the branded Verifiabl barcode as SVG.

Takes the Verifiabl reference from client.registerNonPii and the encrypted PII ciphertext from encryptPii, then returns a standalone SVG suitable for embedding in a payslip PDF.

The QR spans the full badge width (vertical layout) or height (horizontal layout) on a white ground. Place the badge with a clear light margin of at least four QR modules (modulePx in the result; a tenth of the QR’s side covers any realistic record) on every side the badge leaves open: the left, right and bottom for the vertical layout, and the left, top and bottom for the horizontal layout. That margin is the QR quiet zone, which the badge does not carry itself on those sides.

Throws QrCapacityError when the encrypted PII is too long to encode.

Parameter	Type	Description
parts	BarcodeParts
options	BarcodeSvgOptions

Returns: BarcodeSvgResult

encryptPii

Function

encryptPii(plaintext: string, key: Buffer) => EncryptedPii

Encrypt a formatted PII string with AES-256-GCM.

The GCM authentication tag, returned in encryption_metadata, lets the verifier detect any tampering with the ciphertext at scan time.

Every call draws a fresh random iv. Do not store the returned encryptionMetadata and send it again with different content: registration rejects a repeated iv, and the SDK surfaces that as VerifiablIvReuseError (or, in a batch, an error result matched by isIvReuseResult).

Parameter	Type	Description
plaintext	string	The formatted string from formatPii.
key	Buffer	Your 32-byte provider encryption key.

Returns: EncryptedPii

formatAustralianPii

Function

formatAustralianPii(fields: { accountName?: string; accountNumber?: string; address?: { lines?: string[]; postcode?: string; stateOrTerritory?: string; suburb?: string }; bsb?: string; department?: string; employeeName?: string; employerAbn?: string; employerName?: string; position?: string }) => string

Format Australian employee PII as fixed-arity AU2 plaintext. Throws PiiValidationError for forbidden text, including address parts, ZodError for structural problems, and RangeError for the UTF-8 size limit.

Parameter	Type	Description
fields	{ accountName?: string; accountNumber?: string; address?: { lines?: string[]; postcode?: string; stateOrTerritory?: string; suburb?: string }; bsb?: string; department?: string; employeeName?: string; employerAbn?: string; employerName?: string; position?: string }

Returns: string

formatNewZealandPii

Function

formatNewZealandPii(fields: { accountName?: string; accountNumber?: string; address?: { city?: string; lines?: string[]; postcode?: string; suburb?: string }; department?: string; employeeName?: string; employerName?: string; irdNumber?: string; position?: string }) => string

Format New Zealand employee PII as fixed-arity NZ2 plaintext. Throws PiiValidationError for forbidden text, including address parts, ZodError for structural problems, and RangeError for the UTF-8 size limit.

Parameter	Type	Description
fields	{ accountName?: string; accountNumber?: string; address?: { city?: string; lines?: string[]; postcode?: string; suburb?: string }; department?: string; employeeName?: string; employerName?: string; irdNumber?: string; position?: string }

Returns: string

formatPii

Function

formatPii(fields: { accountName?: string; accountNumber?: string; address?: string; bsb?: string; department?: string; employeeName?: string; employerAbn?: string; position?: string }) => string

Format employee PII into Verifiabl’s current P2 compact plaintext wire format.

The result is what you encrypt with encryptPii before embedding it in a barcode. Throws PiiValidationError if any field contains content that cannot be encoded. Each such value must be corrected at the source, as the format has no escape mechanism. Throws ZodError for structural problems (unknown field, non-string value).

Parameter	Type	Description
fields	{ accountName?: string; accountNumber?: string; address?: string; bsb?: string; department?: string; employeeName?: string; employerAbn?: string; position?: string }

Returns: string

generateVerifiablReference

Function

generateVerifiablReference() => string

Generate a fresh Verifiabl reference: 16 cryptographically random bytes (128 bits) encoded as 22 base64url characters without padding. Matches the server’s algorithm so a provider-generated reference is indistinguishable from one issued by the API.

Use this for registerNonPiiBatch, and for registerNonPii when retries must remain correlated across separate calls or process restarts. Persist each such reference before registration and reuse it for later calls. Single-record registration may omit it; the SDK then generates and sends a reference for that call so its automatic retries remain idempotent.

Returns: string

isIvReuseResult

Function

isIvReuseResult(result: BatchRecordResult) => boolean

True when the API rejected this batch record because its encryptionMetadata.iv is already registered to your issuer, either against a stored record or against another record in the same batch.

Encrypt the payslip again with encryptPii to get a new iv, then resend the record with the new encryptionMetadata. Rebuild any barcode that you rendered from the previous ciphertext. Resending the record unchanged gives the same result.

Parameter	Type	Description
result	BatchRecordResult

Returns: boolean

parsePii

Function

parsePii(plaintext: string) => { accountName?: string; accountNumber?: string; address?: string; bsb?: string; department?: string; employeeName?: string; employerAbn?: string; position?: string }

Parse Verifiabl’s compact PII wire format, P2 or P1, back into named fields. Empty segments are omitted from the result, mirroring Verifiabl’s scan-time behaviour.

Useful for round-trip testing your integration; not needed in the normal issuance flow.

Parameter	Type	Description
plaintext	string

Returns: { accountName?: string; accountNumber?: string; address?: string; bsb?: string; department?: string; employeeName?: string; employerAbn?: string; position?: string }

prepareAustralianV2Payslip

Function

prepareAustralianV2Payslip(input: AustralianV2IssuanceInput) => PreparedV2Payslip

Parameter	Type	Description
input	AustralianV2IssuanceInput

Returns: PreparedV2Payslip

prepareNewZealandV2Payslip

Function

prepareNewZealandV2Payslip(input: NewZealandV2IssuanceInput) => PreparedV2Payslip

Parameter	Type	Description
input	NewZealandV2IssuanceInput

Returns: PreparedV2Payslip